Lesson 2 - Customize the Integrated Command UI

  • 3 minutes to read

This lesson demonstrates how to use ribbon and bar customization actions to add, modify or remove elements from the PDF Viewer's integrated Command UI.

This tutorial consists of the following sections:

NOTE

The complete sample projects are available in the How to customize the Integrated PDF Viewer Ribbon and in the How to: Customize the PDF Viewer's Integrated Bar command UI repositories on GitHub.

Create a new WPF PDF Viewer Application

Follow the steps below to create a sample application.

  1. Create a new WPF Application project and open the MainWindow.xaml file in the Visual Studio Designer.

  2. Add the PdfViewerControl object to your project. You can do this by dragging the PdfViewerControl item from the DX.18.2: Data & Analytics Toolbox tab and drop it onto the main window.

    PdfViewerDragDrop

  3. Right-click the PdfViewerControl object and select Layout | Reset All in the context menu. This stretches the PdfViewerControl to fill the entire window.

    resetlayout_pdf

    As a result, you have a ready-to-use PDF Viewer application with the integrated ribbon containing all the available ribbon pages (the DocumentViewerControl.CommandBarStyle property is set to the CommandBarStyle.Ribbon value by default).

Customize the Integrated Command UI

Add the following XML namespace attributes to the MainWindow.xaml document:

xmlns:dx="http://schemas.devexpress.com/winfx/2008/xaml/core"
xmlns:dxb="http://schemas.devexpress.com/winfx/2008/xaml/bars"

Create PdfCommandProvider using the DocumentViewerControl.CommandProvider property to access command ui actions.

<dxpdf:PdfViewerControl x:Name="viewer">
    <dxpdf:PdfViewerControl.CommandProvider>
        <dxpdf:PdfCommandProvider/>
    </dxpdf:PdfViewerControl.CommandProvider>
</dxpdf:PdfViewerControl>

Add the bar customization actions to the CommandProvider.RibbonActions (for Ribbon command UI) or CommandProvider.Actions ( for Bar command UI) collection. The action's ElementName property specifies the name of the existing element you want to change or remove. Element names are the DefaultPdfBarManagerItemNames class fields. You can use the following naming rules to find the name of the element:

Element

Element Type

Page Name

Group Name

Item Name

DefaultPdfBarManagerItemNames Field

Ribbon

image

Ribbon Control

RibbonControl

Bar Manager

image

Bar Manager

Bar

Page/Tab

CustomizeRibbon_RibbonPage

RibbonPage

PDF Viewer

MainRibbonPage

Group

CustomizeRibbon_FileRibbonGroup

RibbonGroup

PDF Viewer

File

FileRibbonGroup

Bar or Ribbon Item

CustomizeRibbon_SaveAs

RibbonItem

PDF Viewer

File

Save As

SaveAs

You can perform one of the following actions:

Add a New Element

To add a new element, add an InsertAction to the CommandProvider.RibbonActions or CommandProvider.Actions collection.

The code below adds a Save button to the File ribbon group, assigns an image to the button and binds it to the PdfViewerControl.SaveAsCommand. This command invokes the Save As dialog.

<dxpdf:PdfCommandProvider.RibbonActions>
        <dxb:InsertAction Index="1" ContainerName="{x:Static dxpdf:DefaultPdfBarManagerItemNames.FileRibbonGroup}">
            <dxb:BarButtonItem Content="Save" LargeGlyph="{dx:DXImage Image=SaveAs_32x32.png}"
                                Command="{Binding ElementName=viewer, Path=SaveAsCommand}"/>
        </dxb:InsertAction>
</dxpdf:PdfCommandProvider.RibbonActions>

Update an Element

To change an item's property, use an UpdateAction. Specify the element's name, the property you want to modify and a new value that should be assigned to this property.

The code snippet below shows how to change the PDF Viewer's Ribbon Page caption.

<dxb:UpdateAction ElementName="{x:Static dxpdf:DefaultPdfBarManagerItemNames.MainRibbonPage}" PropertyName="Caption" Value="caption" />

Remove an Element

To remove an element from a Ribbon, add a RemoveAction with the specified element name to the CommandProvider.RibbonActions or CommandProvider.Actions collection.

The following code demonstrates how to remove a ribbon tab, group, or item:

<dxpdf:PdfCommandProvider.RibbonActions>
    <!--Remove the Comment tab.-->
    <dxb:RemoveAction ElementName="{x:Static dxpdf:DefaultPdfBarManagerItemNames.CommentRibbonPage}"/>

    <!--Remove the Find group on the PDF Viewer tab.-->
    <dxb:RemoveAction ElementName="{x:Static dxpdf:DefaultPdfBarManagerItemNames.FindRibbonGroup}"/>

    <!--Remove the Save As item on the PDF Viewer tab, in the File group.-->
    <dxb:RemoveAction ElementName="{x:Static dxpdf:DefaultPdfBarManagerItemNames.SaveAs}"/>
</dxpdf:PdfCommandProvider.RibbonActions>