Ribbon UI

  • 4 minutes to read

The Dashboard Designer's Ribbon toolbar provides two page categories.

  • Main pages
  • Contextual pages

UserInterface_RibbonPagesDashboard

The main pages include:

  • Home - contains common dashboard commands that allow users to create a new dashboard and add dashboard items, add a title, save the created dashboard, etc.;
  • Data Source - contains commands related to creating and editing data sources, calculated fields, etc.;
  • View - allows users to switch between built-in application themes.

Contextual pages contain commands related to a specific dashboard item. For instance, these commands are used to apply filtering to dashboard item data, perform layout operations, etc.

Create a Ribbon at Design Time

Click the DashboardDesigner's smart tag to create and initialize a Ribbon at design time within Visual Studio:

UserInterface_CreateRibbonDesignTime

Select Create Ribbon in the invoked context menu to add the following visual and non-visual components:

Customize a Ribbon at Design Time

To customize the RibbonControl, click its smart tag and choose Run Designer. To learn how to customize Ribbon items, the Quick Access Toolbar, a popup menu, etc., see the Ribbon Control Designer topic.

Update a Ribbon

If your application already contains a Ribbon (for instance, from the earlier version of the Dashboard Designer), you can select the Update Ribbon menu item to update it:

DesignerSmartTag_Update

The Update Ribbon command from the smart tag menu updates all elements related to the default ribbon created by the Dashboard Designer. If you customize default elements in the Ribbon and then use the Update Ribbon command, apply the same customizations after updating has been finished.

IMPORTANT

If you are upgrading your project to another major release, you should update the Ribbon.

Customize a Ribbon in Code

To create and initialize a Ribbon in code, use the DashboardDesigner.CreateRibbon method.

Use the following code to obtain a RibbonControl instance:

using DevExpress.XtraBars.Ribbon;
//...
RibbonControl ribbon = dashboardDesigner.MenuManager as RibbonControl;

You can add new control elements to the current Ribbon instance. Use the DashboardDesignerBarExtensions class' static methods to get the current Ribbon instance. The DashboardRibbonPage and DashboardBarItemCategory values are used to specify the button's position.

This example creates a new Custom Properties group on the Grid's Design page and adds the Fix Columns button to it:

void AddBarItem(SvgImage svgImage) {
    RibbonControl ribbon = designer.Ribbon;
    RibbonPage page = ribbon.GetDashboardRibbonPage(DashboardBarItemCategory.GridTools, DashboardRibbonPage.Design);
    RibbonPageGroup group = page.GetGroupByName("Custom Properties");
    if(group == null) {
        group = new RibbonPageGroup("Custom Properties") { Name = "Custom Properties" };
        page.Groups.Add(group);
    }
    barItem = new BarCheckItem(ribbon.Manager);
    barItem.Caption = "Fix Columns";
    barItem.ImageOptions.SvgImage = svgImage;
    group.ItemLinks.Add(barItem);
    page.Groups.Add(group);
}

In this example, the Description button is added to the Dashboard group on the Dashboard's Home page.

void AddBarItem(SvgImage barImage) {
    var page = ribbon.GetDashboardRibbonPage(DashboardBarItemCategory.None, DashboardRibbonPage.Home);
    RibbonPageGroup group = page.Groups.GetGroupByText("Dashboard");
    barItem = new BarButtonItem(ribbon.Manager, "Dashboard Description");
    if(barImage != null)
        barItem.ImageOptions.SvgImage = barImage;
    group.ItemLinks.Add(barItem);
}

Ribbon Elements

The Dashboard Designer's Ribbon contains the following elements:

UserInterface_RibbonDashboard

The table below lists these elements and their descriptions, as well as properties that affect element functionality and appearance.

Element

Description

Ribbon API

Quick Access Toolbar

Provides access to the most important and frequently used features in the Dashboard Designer.

RibbonControl.Toolbar

RibbonQuickAccessToolbar.ItemLinks

Application Button

Provides access to the Dashboard Designer's main menu.

RibbonControl.ShowApplicationButton

RibbonControl.ApplicationButtonDropDownControl

Main pages

Contain common dashboard commands.

RibbonControl.Pages

Page Category

Combines pages related to a particular dashboard item.

RibbonControl.Categories

Contextual pages

Contain commands related to a particular dashboard item.

RibbonPageCategory.Pages

Page Groups

Represent groups of bar item links within a Ribbon Page.

RibbonPage.Groups

RibbonPageGroup.ItemLinks

Bar Item links

Visual elements (command buttons, editors, submenus, static text, etc.) displayed within the Ribbon. A Bar Item link refers to a specific bar item.

RibbonControl.Items

BarItemLink.Item

See Also