Customize the Document Preview Toolbar

• Jun 01, 2022
• 5 minutes to read

Tip

Online Example: DocumentPreviewControl - How to remove standard bar items and add custom ones to the toolbar

This example demonstrates how you can customize a Document Preview control’s Ribbon toolbar. In particular, it shows how you can remove standard toolbar controls, and add custom ones.

To start with this tutorial, create a new WPF application with the Document Preview or open an existing one.

To customize the Document Preview control’s toolbar, do the following.

1. In XAML, declare a custom command provider of the type DocumentCommandProvider for the Document Preview control. A command provider exposes the CommandProvider.RibbonActions property, which specifies a collection of actions used to customize the Document Preview control’s ribbon.

   XAML

   ...
   <dxp:DocumentPreviewControl Name="preview"> 
       <dxp:DocumentPreviewControl.CommandProvider> 
           <dxp:DocumentCommandProvider> 
           </dxp:DocumentCommandProvider> 
       </dxp:DocumentPreviewControl.CommandProvider> 
   </dxp:DocumentPreviewControl> 
   ...
   

   Tip

   For more information on action types, review the following help article: Bar Actions.

2. To replace a standard icon of a toolbar command, add an UpdateAction with a specified bar item name to the command provider’s RibbonActions collection property. To identify toolbar items by their names, use fields of the DefaultPreviewBarItemNames class. In the code sample below, a UpdateAction is used to update the Print command icon.

   XAML

   ...
   <dxp:DocumentPreviewControl Name="preview">
       <dxp:DocumentPreviewControl.CommandProvider>
           <dxp:DocumentCommandProvider>
               <dxp:DocumentCommandProvider.RibbonActions>
   
                   <dxb:UpdateAction ElementName="{x:Static dxpbars:DefaultPreviewBarItemNames.Print}" 
                                     Property="{x:Static dxb:BarItem.LargeGlyphProperty}" 
                                     Value="{dxp:PrintingImageSelector Source={dx:DXImage Image=Print_32x32.png}, 
                                               SvgSource='Images/BarItems/Print.svg'}"/>
   
               </dxp:DocumentCommandProvider.RibbonActions>
           </dxp:DocumentCommandProvider>
       </dxp:DocumentPreviewControl.CommandProvider>
   </dxp:DocumentPreviewControl>
   ...
   

3. To remove an element from a toolbar, add a RemoveAction with a specified toolbar element name to the command provider’s RibbonActions collection property. In the code sample below, a RemoveAction is used to remove the File command group.

   XAML

   ...
   
   <dxb:RemoveAction ElementName="{x:Static dxpbars:DefaultPreviewBarItemNames.FileGroup}"/>
   
   ...
   

4. To add a new element to a toolbar, add an InsertAction to the command provider’s RibbonActions collection property. The example below shows how to add a new custom command group to the ribbon toolbar, and then, add two buttons (Create Document and Clear Preview) to this command group.

   XAML

   ...
   <dxb:InsertAction>
       <dxb:InsertAction.Element>
           <dxr:RibbonPageGroup Caption="Custom Commands" Name="CustomCommandsGroup"/>
       </dxb:InsertAction.Element>                      
   </dxb:InsertAction>
   
   <dxb:InsertAction ContainerName="CustomCommandsGroup">
       <dxb:InsertAction.Element>
           <dxb:BarButtonItem Content="Create Document" ItemClick="CreateDocument_ItemClick"/>
       </dxb:InsertAction.Element>
   </dxb:InsertAction>
   
   <dxb:InsertAction ContainerName="CustomCommandsGroup">
       <dxb:InsertAction.Element>
           <dxb:BarButtonItem Content="Clear Preview" ItemClick="ClearPreview_ItemClick"/>
       </dxb:InsertAction.Element>
   </dxb:InsertAction>
   ...
   

   Then, handle the BarItem.ItemClick events of the added buttons as shown below.

   C#

   private void CreateDocument_ItemClick(object sender, DevExpress.Xpf.Bars.ItemClickEventArgs e) {
       link.CreateDocument();
   }
   
   private void ClearPreview_ItemClick(object sender, DevExpress.Xpf.Bars.ItemClickEventArgs e) {
       link.PrintingSystem.ClearContent();
   }
   

   VB.NET

   Private Sub CreateDocument_ItemClick(ByVal sender As Object, ByVal e As DevExpress.Xpf.Bars.ItemClickEventArgs)
       link.CreateDocument()
   End Sub
   
   Private Sub ClearPreview_ItemClick(ByVal sender As Object, ByVal e As DevExpress.Xpf.Bars.ItemClickEventArgs)
       link.PrintingSystem.ClearContent()
   End Sub
   

5. Next, display only the PDF File button preforming the PDF export instead of the default Export… drop-down button. To do this, delete the standard Export bar item using the RemoveAction. Then, add a custom bar item and bind its Command and CommandParameter properties as in the code snippet below.

   XAML

   ...
   <dxb:RemoveAction ElementName="{x:Static dxpbars:DefaultPreviewBarItemNames.Export}"/>
   
   <dxb:InsertAction ContainerName="{x:Static dxpbars:DefaultPreviewBarItemNames.ExportGroup}">
       <dxb:InsertAction.Element>
           <dxb:BarButtonItem Content="{dxp:PrintingStringId StringId=ExportPdf}" 
               LargeGlyph="{dxp:PrintingImageSelector Source={dx:DXImage Image=ExportToPDF_32x32.png}, 
                               SvgSource='Images/BarItems/ExportToPDF.svg'}"
               Glyph="{dxp:PrintingImageSelector Source={dx:DXImage Image=ExportToPDF_16x16.png}, 
                               SvgSource='Images/BarItems/ExportToPDF.svg'}"
               Hint="{dxp:PrintingStringId StringId=ExportPdf}" 
               Command="{Binding Path=(dxp:DocumentPreviewControl.ActualViewer).ExportCommand, 
                   RelativeSource={RelativeSource Self}}" 
               CommandParameter="Pdf"/>
       </dxb:InsertAction.Element>
   </dxb:InsertAction>
   ...
   

MainWindow.xaml (C#)

<Window x:Class="CustomizePreviewToolbar.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:dx="http://schemas.devexpress.com/winfx/2008/xaml/core"
        xmlns:dxp="http://schemas.devexpress.com/winfx/2008/xaml/printing" 
        xmlns:dxe="http://schemas.devexpress.com/winfx/2008/xaml/editors"
        xmlns:dxb="http://schemas.devexpress.com/winfx/2008/xaml/bars"
        xmlns:dxpbars="http://schemas.devexpress.com/winfx/2008/xaml/printing/bars"
        xmlns:dxr="http://schemas.devexpress.com/winfx/2008/xaml/ribbon"
        Title="MainWindow" Height="650" Width="1100">
    <Window.Resources>
        <DataTemplate x:Key="dayNameTemplate">
            <dxe:TextEdit IsPrintingMode="True" Text="{Binding Path=Content}"/>
        </DataTemplate>
    </Window.Resources>
    <Grid>
        <dxp:DocumentPreviewControl Name="preview">
            <dxp:DocumentPreviewControl.CommandProvider>
                <dxp:DocumentCommandProvider>
                    <dxp:DocumentCommandProvider.RibbonActions>

                        <dxb:UpdateAction ElementName="{x:Static dxpbars:DefaultPreviewBarItemNames.Print}" 
                                          Property="{x:Static dxb:BarItem.LargeGlyphProperty}" 
                                          Value="{dxp:PrintingImageSelector Source={dx:DXImage Image=Print_32x32.png}, 
                                                    SvgSource='Images/BarItems/Print.svg'}"/>

                        <dxb:RemoveAction ElementName="{x:Static dxpbars:DefaultPreviewBarItemNames.Export}"/>
                        <dxb:RemoveAction ElementName="{x:Static dxpbars:DefaultPreviewBarItemNames.FileGroup}"/>

                        <dxb:InsertAction>
                            <dxb:InsertAction.Element>
                                <dxr:RibbonPageGroup Caption="Custom Commands" Name="CustomCommandsGroup"/>
                            </dxb:InsertAction.Element>                      
                        </dxb:InsertAction>

                        <dxb:InsertAction ContainerName="CustomCommandsGroup">
                            <dxb:InsertAction.Element>
                                <dxb:BarButtonItem Content="Create Document" ItemClick="CreateDocument_ItemClick"/>
                            </dxb:InsertAction.Element>
                        </dxb:InsertAction>

                        <dxb:InsertAction ContainerName="CustomCommandsGroup">
                            <dxb:InsertAction.Element>
                                <dxb:BarButtonItem Content="Clear Preview" ItemClick="ClearPreview_ItemClick" />                                
                            </dxb:InsertAction.Element>
                        </dxb:InsertAction>

                        <dxb:InsertAction ContainerName="{x:Static dxpbars:DefaultPreviewBarItemNames.ExportGroup}">
                            <dxb:InsertAction.Element>
                                <dxb:BarButtonItem Content="{dxp:PrintingStringId StringId=ExportPdf}" 
                                    LargeGlyph="{dxp:PrintingImageSelector Source={dx:DXImage Image=ExportToPDF_32x32.png}, 
                                                    SvgSource='Images/BarItems/ExportToPDF.svg'}"
                                    Glyph="{dxp:PrintingImageSelector Source={dx:DXImage Image=ExportToPDF_16x16.png}, 
                                                    SvgSource='Images/BarItems/ExportToPDF.svg'}"
                                    Hint="{dxp:PrintingStringId StringId=ExportPdf}" 
                                    Command="{Binding Path=(dxp:DocumentPreviewControl.ActualViewer).ExportCommand, 
                                        RelativeSource={RelativeSource Self}}" 
                                    CommandParameter="Pdf"/>
                            </dxb:InsertAction.Element>
                        </dxb:InsertAction>

                    </dxp:DocumentCommandProvider.RibbonActions>
                </dxp:DocumentCommandProvider>
            </dxp:DocumentPreviewControl.CommandProvider>
        </dxp:DocumentPreviewControl>
    </Grid>
</Window>

MainWindow.xaml.cs

using System.Globalization;
using System.Windows;
using DevExpress.Xpf.Printing;
// ...

namespace CustomizePreviewToolbar {
    /// <summary>
    /// Interaction logic for MainWindow.xaml
    /// </summary>
    public partial class MainWindow : Window {
        private SimpleLink link;

        public MainWindow() {
            InitializeComponent();

            // Create a document to display.
            string[] data = CultureInfo.CurrentCulture.DateTimeFormat.DayNames;

            link = new SimpleLink {
                DetailTemplate = (DataTemplate)Resources["dayNameTemplate"],
                DetailCount = data.Length
            };
            link.CreateDetail += (s, e) => e.Data = data[e.DetailIndex];

            preview.DocumentSource = link;
            link.CreateDocument();
        }

        private void CreateDocument_ItemClick(object sender, DevExpress.Xpf.Bars.ItemClickEventArgs e) {
            link.CreateDocument();
        }

        private void ClearPreview_ItemClick(object sender, DevExpress.Xpf.Bars.ItemClickEventArgs e) {
            link.PrintingSystem.ClearContent();
        }
    }
}

MainWindow.xaml (VB.NET)

<Window x:Class="CustomizePreviewToolbar.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:dx="http://schemas.devexpress.com/winfx/2008/xaml/core"
        xmlns:dxp="http://schemas.devexpress.com/winfx/2008/xaml/printing" 
        xmlns:dxe="http://schemas.devexpress.com/winfx/2008/xaml/editors"
        xmlns:dxb="http://schemas.devexpress.com/winfx/2008/xaml/bars"
        xmlns:dxpbars="http://schemas.devexpress.com/winfx/2008/xaml/printing/bars"
        xmlns:dxr="http://schemas.devexpress.com/winfx/2008/xaml/ribbon"
        Title="MainWindow" Height="650" Width="1100">
    <Window.Resources>
        <DataTemplate x:Key="dayNameTemplate">
            <dxe:TextEdit IsPrintingMode="True" Text="{Binding Path=Content}"/>
        </DataTemplate>
    </Window.Resources>
    <Grid>
        <dxp:DocumentPreviewControl Name="preview">
            <dxp:DocumentPreviewControl.CommandProvider>
                <dxp:DocumentCommandProvider>
                    <dxp:DocumentCommandProvider.RibbonActions>

                        <dxb:UpdateAction ElementName="{x:Static dxpbars:DefaultPreviewBarItemNames.Print}" 
                                          Property="{x:Static dxb:BarItem.LargeGlyphProperty}" 
                                          Value="{dxp:PrintingImageSelector Source={dx:DXImage Image=Print_32x32.png}, 
                                                    SvgSource='Images/BarItems/Print.svg'}"/>

                        <dxb:RemoveAction ElementName="{x:Static dxpbars:DefaultPreviewBarItemNames.Export}"/>
                        <dxb:RemoveAction ElementName="{x:Static dxpbars:DefaultPreviewBarItemNames.FileGroup}"/>

                        <dxb:InsertAction>
                            <dxb:InsertAction.Element>
                                <dxr:RibbonPageGroup Caption="Custom Commands" Name="CustomCommandsGroup"/>
                            </dxb:InsertAction.Element>                      
                        </dxb:InsertAction>

                        <dxb:InsertAction ContainerName="CustomCommandsGroup">
                            <dxb:InsertAction.Element>
                                <dxb:BarButtonItem Content="Create Document" ItemClick="CreateDocument_ItemClick"/>
                            </dxb:InsertAction.Element>
                        </dxb:InsertAction>

                        <dxb:InsertAction ContainerName="CustomCommandsGroup">
                            <dxb:InsertAction.Element>
                                <dxb:BarButtonItem Content="Clear Preview" ItemClick="ClearPreview_ItemClick" />                                
                            </dxb:InsertAction.Element>
                        </dxb:InsertAction>

                        <dxb:InsertAction ContainerName="{x:Static dxpbars:DefaultPreviewBarItemNames.ExportGroup}">
                            <dxb:InsertAction.Element>
                                <dxb:BarButtonItem Content="{dxp:PrintingStringId StringId=ExportPdf}" 
                                    LargeGlyph="{dxp:PrintingImageSelector Source={dx:DXImage Image=ExportToPDF_32x32.png}, 
                                                    SvgSource='Images/BarItems/ExportToPDF.svg'}"
                                    Glyph="{dxp:PrintingImageSelector Source={dx:DXImage Image=ExportToPDF_16x16.png}, 
                                                    SvgSource='Images/BarItems/ExportToPDF.svg'}"
                                    Hint="{dxp:PrintingStringId StringId=ExportPdf}" 
                                    Command="{Binding Path=(dxp:DocumentPreviewControl.ActualViewer).ExportCommand, 
                                        RelativeSource={RelativeSource Self}}" 
                                    CommandParameter="Pdf"/>
                            </dxb:InsertAction.Element>
                        </dxb:InsertAction>

                    </dxp:DocumentCommandProvider.RibbonActions>
                </dxp:DocumentCommandProvider>
            </dxp:DocumentPreviewControl.CommandProvider>
        </dxp:DocumentPreviewControl>
    </Grid>
</Window>

MainWindow.xaml.vb

Imports System.Globalization
Imports System.Windows
Imports DevExpress.Xpf.Printing
' ...

Namespace CustomizePreviewToolbar
    ''' <summary>
    ''' Interaction logic for MainWindow.xaml
    ''' </summary>
    Partial Public Class MainWindow
        Inherits Window

        Private link As SimpleLink

        Public Sub New()
            InitializeComponent()

            ' Create a document to display.
            Dim data() As String = CultureInfo.CurrentCulture.DateTimeFormat.DayNames

            link = New SimpleLink With { _
                .DetailTemplate = DirectCast(Resources("dayNameTemplate"), DataTemplate), _
                .DetailCount = data.Length _
            }
            AddHandler link.CreateDetail, Sub(s, e) e.Data = data(e.DetailIndex)

            preview.DocumentSource = link
            link.CreateDocument()
        End Sub

        Private Sub CreateDocument_ItemClick(ByVal sender As Object, ByVal e As DevExpress.Xpf.Bars.ItemClickEventArgs)
            link.CreateDocument()
        End Sub

        Private Sub ClearPreview_ItemClick(ByVal sender As Object, ByVal e As DevExpress.Xpf.Bars.ItemClickEventArgs)
            link.PrintingSystem.ClearContent()
        End Sub
    End Class
End Namespace

Application.xaml.vb

Imports System
Imports System.Collections.Generic
Imports System.Configuration
Imports System.Data
Imports System.Linq
Imports System.Windows
Imports DevExpress.Xpf.Core

Namespace CustomizePreviewToolbar
    ''' <summary>
    ''' Interaction logic for App.xaml
    ''' </summary>
    Partial Public Class App
        Inherits Application

    End Class
End Namespace

Application.xaml

<Application x:Class="CustomizePreviewToolbar.App"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             StartupUri="MainWindow.xaml">
    <Application.Resources>

    </Application.Resources>
</Application>

The result is shown in the following image.