All docs
V21.1
21.2 (EAP/Beta)
21.1
20.2
The page you are viewing does not exist in version 20.2. This link will take you to the root page.
20.1
The page you are viewing does not exist in version 20.1. This link will take you to the root page.
19.2
The page you are viewing does not exist in version 19.2. This link will take you to the root page.
19.1
The page you are viewing does not exist in version 19.1. This link will take you to the root page.
18.2
The page you are viewing does not exist in version 18.2. This link will take you to the root page.
18.1
The page you are viewing does not exist in version 18.1. This link will take you to the root page.
17.2
The page you are viewing does not exist in version 17.2. This link will take you to the root page.

Get Started

  • 12 minutes to read

This topic explains core Ribbon Control concepts.

Base Ribbon UI Settings

  1. Invoke the form smart tag menu to convert your form to a Ribbon Form. This action converts a form and adds the RibbonControl and RibbonStatusBar controls.

Convert standard form to RibbonForm

  1. The Ribbon Control arranges its buttons into page groups, and page groups merge into pages (tabs). Apart from these main areas, you can also add items to:
  • form title bar area;
  • page header area;
  • Quick Access Toolbar (QAT);
  • main application menu.

Main Ribbon Elements

  1. Every area that can host an item (button, editor, etc.) has a “+” icon that you can click to create a new item and place it in this area. Icons next to page groups and pages allow you to add more of these areas.

Click the “+” icon inside a page group and select “Button (BarButtonItem)” to create a regular push button.

Add new Ribbon item to a page group

  1. You can invoke a smart tag menu for a selected item to modify its main settings: caption, image, and ribbon style. The “Ribbon style” setting allows you to choose whether or not a button should display its text, and which size its icon should have (16x16 or 32x32 pixels). See this property for more details: BarItem.RibbonStyle.

Ribbon Item Smart Tag Menu

Note that you can select and invoke smart tag menus for pages and page groups as well. You can do this to quickly rename tabs and page groups.

  1. The DevExpress WinForms installation ships with the Image Gallery tool. This Gallery includes hundreds of raster and vector icons drawn by our designers that you can freely use in your apps.

You can also open the Image Picker panel and dock it anywhere inside Visual Studio. This panel reads the currently selected item’s title, and suggests corresponding DevExpress icons. Double-click (or drag-and-drop) an icon to instantly assign it to the selected item.

Image Picker - Smart Search

  1. Both Ribbon and BarManager controls employ the “items - item links” concept. Whenever you create a button, an editor, or any other toolbar command, a corresponding BarItem is created (BarButtonItem, BarEditItem, etc.). However, these items are stored internally and aren’t visible at runtime. Instead, users see copies of these items: item links. This techique allows you to create one item (for instance, the “Open” button) and display links to this item in multiple areas.

Link copies

To copy a command to a new area (create another bar item link to an existing bar item), drag-and-drop this command with the “Ctrl” key pressed. The “+” sign appears under the mouse pointer to indicate the item is being copied, not moved.

  1. When you press “Del” to remove a command, the Ribbon Control asks whether you want to remove this item link only, or the parent bar item with all of its bar item links.

confirmation dialog

If you check the “Remember this selection and do not ask me next time” option, the confirmation dialog will no longer appear. If you change your mind and require the confirmation dialog to pop up again, find the HKEY_CURRENT_USER\Software\Developer Express\Designer\XtraBars\ShowBarElementDeletionConfirmation registry key and set its value to True.

TIP

You can delete all Bar Items that do not have links (that is, they are not accessible through the UI) simultaneously. To remove these Bar Items, click “Remove Unassigned Items” in the Ribbon Control’s smart tag menu.

  1. When you add an editor to a Ribbon or Ribbon Status Bar, the control creates a BarEditItem that wraps this editor. You can access the editor through the BarEditItem’s Edit property. The image below illustrates a ProgressBarControl inside a Ribbon Status Bar; the Minimum and Maximum editor properties allow you to set up its value range.

editor settings

Editor width and current value are set with the BarEditItem.EditWidth and BarEditItem.EditValue properties.

Page Categories

All Ribbon Pages that you add are placed into a default category. You can click the “Add Category” button on the Ribbon surface to add custom categories. These categories have a Visible property that allows you to decide whether a category is constantly visible, or shown only under a specific condition. For instance, in the Ribbon Simple Pad Demo, the “Selection” category is shown only when a user selects text.

custom Ribbon category

See this topic for more information about Ribbon page categories: Categories and Contextual Tabs.

Unless the RibbonControl.ShowApplicationButton property is disabled, a Ribbon control displays a button that invokes a main application menu. Depending on the Ribbon Style (see the Ribbon Styles section of this document), this element can be shown as a button in the Ribbon Control’s top left corner, as a tab with a menu icon, or as the “File” tab.

Application Button in different styles

TIP

You can customize the Application Button image and text with the ApplicationButtonImageOptions and ApplicationButtonText properties.

In order for the Application Button to display a main app menu, you need to assign this menu to the RibbonControl.ApplicationButtonDropDownControl property. This property can accept an Object of the following types:

  • ApplicationMenu - a panel-like menu that has a limited size. This menu style was used in Microsoft Office 2007 and older versions.

Application Menu

  • BackstageViewControl - a menu that occupies an entire form. This menu style can be seen in modern Microsoft Office versions starting with the 2010 release. You can use the RecentItemControl to create BackstageViewControl’s item layout.

Backstage View

Choose the required menu type and drop a corresponding control from the Visual Studio Toolbox directly onto the form surface. Once you assign it to the ApplicationButtonDropDownControl, it is not visible at runtime.

Ribbon Styles

The Ribbon Control includes multiple styles that affect control features and appearance of its elements. For instance, the “Office Universal” style does not support large Ribbon links and arranges all buttons in a single row, and “Office 2019” adds a button that allows users to switch between regular and “Simplified” Ribbon modes. You can read about unique Ribbon features specific to every style in this help article: Ribbon Styles.

To switch a Ribbon Control style, use the control smart tag menu or modify the RibbonStyle property value in the Visual Studio Property Grid.

Context Menus

To create a popup (context) menu, invoke the Ribbon Control smart tag menu, click “Run Designer” and switch to the designer “Sub Menus and Popup Menus” tab. Click “Add New Popup Menu” to create an empty PopupMenu object.

Menus Tab in Ribbon Designer

In this designer tab you can drag and drop existing Ribbon items from the middle panel to add them to a selected menu. The “[Add]” link allows you to create new items.

Add items to Popup Menu

TIP

Add BarHeaderItems to insert captions between regular menu items. This allows you to break down menu items into multiple categories.

To show a menu, call its ShowPopup method inside a required event handler (for instance, MouseDown).

void GridControl_MouseDown(object sender, MouseEventArgs e) {
    GridControl grid = sender as GridControl;
    if (e.Button == MouseButtons.Right)
        popupMenu1.ShowPopup(grid.PointToScreen(e.Location));
}
TIP

When you place a RibbonControl on a form at design time, all controls publish the PopupContextMenu extender property (its caption in the Visual Studio Properties window is “PopupContextMenu on <Ribbon control name>“). If you assign a context menu to this property, this menu will pop up at runtime when users right-click the control. You do not need to manually handle MouseDown or other mouse events.

See also: Radial Menu | DXPopupMenu

Auto-Generated Ribbon Controls

A number of DevExpress WinForms controls can generate a Ribbon control and populate it with commands related to this control. For example, the Chart Control generates a Ribbon that allows users to change a series’ view type, add and remove indicators, draw lines, and so forth.

The Chart Control with the [Ribbon](xref:2500)

See the following help articles for more information about auto-generated Ribbons:

Ribbon Control in MVVM Apps

DevExpress MVVM Framework allows you to build applications that follow a Model-View-ViewModel concept. This concept implies that data, UI, and application logic are split into independent layers.

Based on this concept, you cannot handle Click events for Ribbon Items because that moves business logic to the UI (View) layer. Instead, you need to declare a Command inside a ViewModel and bind it to a required Ribbon item.

//a View with Ribbon
public partial class RibbonForm1 : DevExpress.XtraBars.Ribbon.RibbonForm {
    public RibbonForm1() {
        InitializeComponent();
        if(!mvvmContext.IsDesignMode)
            InitializeBindings();
    }
    void InitializeBindings() {
        var fluent = mvvmContext1.OfType<RibbonForm1ViewModel>(); 
        fluent.BindCommand(barButtonItem1, x=>x.OpenDocument;
        fluent.SetBinding(barEditItem1, e => e.EditValue, x => x.Ed);
    }
}

//ViewModel with business logic
[POCOViewModel()]  
class RibbonForm1ViewModel {
    public void OpenDocument() {
        //...
    }
}

See the following help article for more information: Commands.

How to Create a Ribbon UI in Code

The code from this section creates a sample Ribbon UI.

Key Takeaways

Area

Link collection

Page Group

RibbonPageGroup.ItemLinks

Page Header Area

RibbonControl.PageHeaderItemLinks

QAT

RibbonControl.Toolbar.ItemLinks

Form Title Bar

RibbonControl.CaptionBarItemLinks

Ribbon Status Bar

RibbonStatusBar.ItemLinks

  • When you create a Bar Item in code, always specify the Ribbon that owns this item. To do this, either use an overload that has the “manager” parameter, or add this item to the RibbonControl.Items collection.
BarButtonItem bbiClose = new BarButtonItem(rc.Manager, "Close", 1);

//or

BarButtonItem biUndo = new BarButtonItem();
biUndo.Caption = "Undo";
biUndo.ImageIndex = 3;
rc.Items.Add(biUndo);
  • Ribbon Status Bar has two areas that display links: left and right. The parent bar item’s Alignment property value specifies the area where the bar item link is displayed.

  • There is no API to retrieve images from the DevExpress Image Gallery in code. Instead, create an ImageCollection or SvgImageCollection at design time, populate it with Image Gallery images, and assign this collection to the control’s Images property. Then you can use ImageIndex properties to obtain collection images by their indexes, and assign these images to visual elements.

rc.Images = svgImageCollection1;
//...
biUndo.ImageIndex = 3;
  • Wrap large Ribbon customization code in the BeginInit / EndInit method calls to avoid excessive visual updates.

Complete Code

using DevExpress.XtraBars;
using DevExpress.XtraBars.Ribbon;
using DevExpress.XtraEditors.Repository;
using System.Drawing;

namespace DXApplication18 {
    public partial class MainForm : RibbonForm {
        public Form2() {
            InitializeComponent();
            //Create Ribbon UI
            RibbonControl rc = new RibbonControl();
            rc.Images = svgImageCollection1;
            rc.RibbonStyle = RibbonControlStyle.Office2019;
            RibbonStatusBar rsb = new RibbonStatusBar();
            rsb.Ribbon = rc;
            this.Controls.Add(rc);
            this.Controls.Add(rsb);
            rc.BeginInit();
            //Add Ribbon tabs
            rc.Pages.Clear();
            rc.Pages.Add(new RibbonPage("Main Page"));
            rc.Pages.Add(new RibbonPage("Secondary Page"));
            //Add RibbonPageGroups to the first page
            rc.Pages["Main Page"].Groups.Clear();
            rc.Pages["Main Page"].Groups.Add(new RibbonPageGroup("Edit"));
            rc.Pages["Main Page"].Groups.Add(new RibbonPageGroup("Format"));
            //Add buttons to the "Edit" page group
            BarButtonItem bbiOpen = new BarButtonItem(rc.Manager, "Open", 0);
            bbiOpen.RibbonStyle = RibbonItemStyles.Large;
            bbiOpen.Hint = "Load an existing document";
            BarButtonItem bbiClose = new BarButtonItem(rc.Manager, "Close", 1);
            bbiClose.RibbonStyle = RibbonItemStyles.SmallWithText;
            BarButtonItem bbiCopy = new BarButtonItem(rc.Manager, "Copy", 2);
            bbiCopy.RibbonStyle = RibbonItemStyles.SmallWithText;
            rc.Pages[0].Groups[0].ItemLinks.AddRange(new BarItem[] {
                bbiOpen, bbiClose, bbiCopy
            });
            //Add custom categories
            RibbonPageCategory rCat = new RibbonPageCategory("Contextual Category", Color.DeepPink);
            rc.PageCategories.Add(rCat);
            rCat.Pages.Add(new RibbonPage("Selection"));
            rCat.Pages[0].Groups.Add(new RibbonPageGroup("Selection Tools"));
            rCat.Visible = true;
            rCat.AutoStretchPageHeaders = true;
            //Add a links to existing items to Page Header area and QAT
            rc.PageHeaderItemLinks.Add(bbiOpen);
            rc.Toolbar.ItemLinks.Add(bbiOpen);
            //Add a new item to QAT
            BarButtonItem biUndo = new BarButtonItem();
            biUndo.Caption = "Undo";
            biUndo.ImageIndex = 3;
            rc.Items.Add(biUndo);
            rc.Toolbar.ItemLinks.Add(biUndo);
            //Add new item to Form Title Bar area
            rc.CaptionBarItemLinks.Add(new SkinPaletteDropDownButtonItem());
            rc.CaptionBarItemLinks.Add(new SkinDropDownButtonItem());
            //Add Items to Ribbon Status Bar
            BarStaticItem statusLabel = new BarStaticItem() {
                Caption = "Ready", Alignment = BarItemLinkAlignment.Right
            };
            rc.Items.Add(statusLabel);
            rsb.ItemLinks.Add(statusLabel);
            RepositoryItemZoomTrackBar riZoom = new RepositoryItemZoomTrackBar();
            riZoom.Maximum = 200;
            riZoom.Minimum = 0;
            BarEditItem biZoom = new BarEditItem(rc.Manager, riZoom);
            biZoom.EditWidth = 150;
            biZoom.EditValue = 100;
            rsb.ItemLinks.Add(biZoom);
            rc.EndInit();
        }
    }
}