Lesson 3 - Customize the Integrated Ribbon UI

• Dec 25, 2018
• 3 minutes to read

This lesson demonstrates how to use ribbon customization actions to add, modify, or remove elements from the PDF Viewer’s integrated Ribbon UI.

This tutorial consists of the following sections:

• Create a new WPF PDF Viewer Application
• Customize the Integrated Ribbon

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.

   

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

   

   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 Ribbon

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

XAML

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 ribbon actions.

XAML

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

Add the required customization actions to the CommandProvider.RibbonActions collection. The action’s ElementName property specifies the name of the existing ribbon element you wish to change or remove. Element names are the DefaultPdfBarManagerItemNames class fields. You can easily deduce the required element name by following naming rules listed in the table below:

Ribbon Element	Element Type	Page Name	Group Name	Item Name	DefaultPdfBarManagerItemNames Field
Page/Tab	RibbonPage	PDF Viewer			MainRibbonPage
Group	RibbonGroup	PDF Viewer	File		FileRibbonGroup
Item	RibbonItem	PDF Viewer	File	Save As	SaveAs

You can perform one of the following actions:

• Add a Ribbon Element

• Modify a Ribbon Element

• Remove a Ribbon Element

Add a Ribbon Element

To add a new element, add an InsertAction to the CommandProvider.RibbonActions 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.

XAML

<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 a Ribbon 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.

XAML

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

Remove a Ribbon Element

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

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

Note

The complete sample project is available on GitHub at https://github.com/DevExpress-Examples/how-to-customize-pdf-viewer-toolbar-items

XAML

<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>

The complete XAML code for the PDF Viewer with a custom ribbon is shown here:

Note

Show Me The complete sample project is available on GitHub at https://github.com/DevExpress-Examples/how-to-customize-pdf-viewer-toolbar-items

XAML

<Window x:Class="PdfViewerCustomization.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:dxb="http://schemas.devexpress.com/winfx/2008/xaml/bars"    
        xmlns:dxpdf="http://schemas.devexpress.com/winfx/2008/xaml/pdf"       
        Title="MainWindow"
        Height="350"
        Width="525">

    <dxpdf:PdfViewerControl x:Name="viewer">
        <dxpdf:PdfViewerControl.CommandProvider>
            <dxpdf:PdfCommandProvider>
                <dxpdf:PdfCommandProvider.RibbonActions>
                    <dxb:RemoveAction ElementName="{x:Static dxpdf:DefaultPdfBarManagerItemNames.CommentRibbonPage}"/>
                    <dxb:RemoveAction ElementName="{x:Static dxpdf:DefaultPdfBarManagerItemNames.FindRibbonGroup}"/>
                    <dxb:RemoveAction ElementName="{x:Static dxpdf:DefaultPdfBarManagerItemNames.SaveAs}"/>
                    <dxb:ReplaceAction  ElementName="{x:Static dxpdf:DefaultPdfBarManagerItemNames.Close}">
                        <dxb:BarButtonItem Content="Exit" LargeGlyph="{dx:DXImage Image=Close_32x32.png}"
                                           Command="{Binding ElementName=viewer, Path=CloseDocumentCommand}"/>
                    </dxb:ReplaceAction>
                    <dxb:UpdateAction ElementName="{x:Static dxpdf:DefaultPdfBarManagerItemNames.MainRibbonPage}" 
                                      PropertyName="Caption" Value="caption" />
                    <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>
            </dxpdf:PdfCommandProvider>
        </dxpdf:PdfViewerControl.CommandProvider>
    </dxpdf:PdfViewerControl>
</Window>