Lesson 3 - Customize the Integrated Ribbon UI for the Spreadsheet

  • 4 minutes to read

This example demonstrates how to use bar customization actions to add, modify or remove elements from the WPF Spreadsheet's integrated ribbon UI.

NOTE

A complete sample project is available in the DevExpress-Examples/how-to-customize-the-integrated-ribbon-for-the-wpf-spreadsheet-t511399 repository on GitHub.

This tutorial consists of the following sections:

Create a New Spreadsheet Application

  1. Create a new WPF Application project and open the MainWindow.xaml file in the Visual Studio Designer.
  2. Add the SpreadsheetControl object to your project. To do this, drag the SpreadsheetControl item from the DX.20.1: Spreadsheet Toolbox tab onto the canvas.

    DXSpreadsheet_GettingStarted_DropFromToolbox

  3. Right-click the SpreadsheetControl object and select Layout | Reset All in the context menu to stretch the SpreadsheetControl to fit the window.

As a result, you have a ready-to-use spreadsheet application with an integrated ribbon that contains all the available spreadsheet ribbon pages.

Customize the Integrated Ribbon

Add the following namespace declarations to the MainWindow.xaml file:

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

To modify the SpreadsheetControl's integrated ribbon UI, add the necessary customization actions to the SpreadsheetControl.RibbonActions collection. The action's ElementName property specifies the name of the existing ribbon element you wish to change or remove. Element names are fields of the DevExpress.Xpf.Spreadsheet.DefaultBarItemNames class. 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

DefaultBarItemNames Field

Ribbon

ribbon

Ribbon Control

RibbonControl

Page/Tab

DXSpreadsheet_GettingStarted4_RibbonNaming_Tab

RibbonPage

Home

RibbonPage_Home

Contextual Tab

DXSpreadsheet_GettingStarted4_RibbonNaming_ContextualTab

RibbonCategory

ChartTools

RibbonCategory_ChartTools

Group

DXSpreadsheet_GettingStarted4_RibbonNaming_Group

RibbonGroup

Home

Clipboard

RibbonGroup_Home_Clipboard

Item

DXSpreadsheet_GettingStarted4_RibbonNaming_Item

RibbonItem

Home

Clipboard

Paste

RibbonItem_Home_Clipboard_Paste

Select the action you wish to perform:

Remove a Ribbon Element

To remove an element from the ribbon, add a RemoveAction with the required element's name to the SpreadsheetControl.RibbonActions collection.

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

<dxsps:SpreadsheetControl.RibbonActions>
    <!--Remove the Review tab.-->
    <dxb:RemoveAction ElementName="{x:Static dxsps:DefaultBarItemNames.RibbonPage_Review}"/>

    <!--Remove the Window group on the View tab.-->
    <dxb:RemoveAction ElementName="{x:Static dxsps:DefaultBarItemNames.RibbonGroup_View_Window}"/>

    <!--Remove the Quick Print item on the File tab, in the Common group.-->
<dxb:RemoveAction ElementName="{x:Static dxsps:DefaultBarItemNames.RibbonItem_File_Common_QuickPrint}"/>
</dxsps:SpreadsheetControl.RibbonActions>

Modify a Ribbon Element

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

The example below demonstrates how to activate the Home tab on the ribbon and hide different ribbon elements.

<!--Make the Home tab the default tab in the application.-->
<dxb:UpdateAction ElementName="{x:Static dxsps:DefaultBarItemNames.RibbonPage_Home}" PropertyName="IsSelected" Value="True"/>

<!--Hide the Page Layout tab.-->
<dxb:UpdateAction ElementName="{x:Static dxsps:DefaultBarItemNames.RibbonPage_PageLayout}" PropertyName="IsVisible" Value="False"/>

<!--Hide the Formulas tab.-->
<dxb:UpdateAction ElementName="{x:Static dxsps:DefaultBarItemNames.RibbonPage_Formulas}" PropertyName="IsVisible" Value="False"/>

<!--Hide the Data tab.-->
<dxb:UpdateAction ElementName="{x:Static dxsps:DefaultBarItemNames.RibbonPage_Data}" PropertyName="IsVisible" Value="False"/>

<!--Hide the Show group on the View tab.-->
<dxb:UpdateAction ElementName="{x:Static dxsps:DefaultBarItemNames.RibbonGroup_View_Show}" PropertyName="IsVisible" Value="False"/>

<!--Hide the PivotTable item on the Insert tab, in the Tables group.-->
<dxb:UpdateAction ElementName="{x:Static dxsps:DefaultBarItemNames.RibbonItem_Insert_Tables_PivotTable}" PropertyName="IsVisible" Value="False"/>

Add a New Ribbon Element

To add a new element to the ribbon, add an InsertAction to the SpreadsheetControl.RibbonActions collection.

The following code snippet shows how to create a new Example ribbon tab with the Info group and add the About button to this group. The About button uses the BarItem.ItemClick event to display a custom message containing information about the current example. The code also adds the Comment button to the Insert tab and new Comments group and binds the button to the existing spreadsheet command which inserts a new comment.

<!--Create a new Example tab.-->
<!--Create the Info group on the Example tab.-->
<!--The group contains a single button displaying information about this example.-->
<dxb:InsertAction Index="8" ContainerName="{x:Static dxsps:DefaultBarItemNames.RibbonCategory_Default}">
    <dxr:RibbonPage x:Name="RibbonPage_Example" Caption="Example">
        <dxr:RibbonPageGroup Caption="Info">
            <dxb:BarButtonItem Content="About"
                                LargeGlyph="{dx:SvgImageSource Uri='pack://application:,,,/WpfSpreadsheet_RibbonCustomization;component/Images/About.svg'}"
                                ItemClick="About_ItemClick"/>
        </dxr:RibbonPageGroup>
    </dxr:RibbonPage>
</dxb:InsertAction>

<!--Create the Comments group on the Insert tab and add the Comment button to it.-->
<dxb:InsertAction Index="5" ContainerName="{x:Static dxsps:DefaultBarItemNames.RibbonPage_Insert}">
    <dxr:RibbonPageGroup Caption="Comments">
        <dxb:BarButtonItem Content="Comment"
                            LargeGlyph="{dxsps:SpreadsheetSvgImage Name=InsertComment.svg, UseOfficeImage=True}"
                            Command="{Binding RelativeSource={RelativeSource Self}, Path=(dxsps:SpreadsheetControl.Spreadsheet).CommandProvider.InsertComment}"/>
    </dxr:RibbonPageGroup>
</dxb:InsertAction>

Handle the About button's BarItem.ItemClick event as shown below.

private void About_ItemClick(object sender, DevExpress.Xpf.Bars.ItemClickEventArgs e)
{
    DXMessageBox.Show("This example demonstrates how to customize the WPF Spreadsheet's integrated ribbon UI.\n\n
        Use the SpreadsheetControl's RibbonActions collection to create, remove or modify ribbon elements.",
        "Spreadsheet Ribbon Customization", MessageBoxButton.OK, MessageBoxImage.Information);
}

Result

Run the project. The following image illustrates the result:

DXSpreadsheet_GettingStarted4_Result

See Also