windowsforms-402959-controls-and-libraries-ribbon-bars-and-menu-get-started.md
This topic explains core Ribbon Control concepts.
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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
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.
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));
}
Private Sub GridControl_MouseDown(ByVal sender As Object, ByVal e As MouseEventArgs)
Dim grid As GridControl = TryCast(sender, GridControl)
If e.Button = MouseButtons.Right Then
popupMenu1.ShowPopup(grid.PointToScreen(e.Location))
End If
End Sub
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
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.
See the following help articles for more information about auto-generated Ribbons:
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() {
//...
}
}
'a View with Ribbon
Partial Public Class RibbonForm1
Inherits DevExpress.XtraBars.Ribbon.RibbonForm
Public Sub New()
InitializeComponent()
If Not mvvmContext.IsDesignMode Then
InitializeBindings()
End If
End Sub
Private Sub InitializeBindings()
Dim fluent = mvvmContext1.OfType(Of RibbonForm1ViewModel)()
fluent.BindCommand(barButtonItem1, Function(x) x.OpenDocument; fluent.SetBinding(barEditItem1, Function(e) e.EditValue, Function(x) x.Ed);
End Sub
End Class
'ViewModel with business logic
<POCOViewModel()>
Friend Class RibbonForm1ViewModel
Public Sub OpenDocument()
'...
End Sub
End Class
See the following help article for more information: Commands.
The code from this section creates a sample Ribbon UI.
Key Takeaways
Ribbon Pages are instances of the RibbonPage class stored in the RibbonControl.Pages collection.
Ribbon Page Groups are instances of the RibbonPageGroup class stored in the RibbonPage.Groups collections of their parent Pages.
Categories are RibbonPageCategory objects stored in the RibbonControl.Categories collection. To add a Page to a custom category, place this Page into the RibbonPageCategory.Pages collection of this category.
To add a bar item link to the required area, place a parent bar item into the related collection:
|
Area
|
Link collection
| | --- | --- | |
Page Group
|
| |
Page Header Area
|
RibbonControl.PageHeaderItemLinks
| |
QAT
|
RibbonControl.Toolbar.ItemLinks
| |
Form Title Bar
|
RibbonControl.CaptionBarItemLinks
| |
Ribbon Status Bar
|
|
csharpBarButtonItem bbiClose = new BarButtonItem(rc.Manager, "Close", 1); //or BarButtonItem biUndo = new BarButtonItem(); biUndo.Caption = "Undo"; biUndo.ImageIndex = 3; rc.Items.Add(biUndo);vbDim bbiClose As New BarButtonItem(rc.Manager, "Close", 1) 'or Dim biUndo As 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.
csharprc.Images = svgImageCollection1; //... biUndo.ImageIndex = 3;vbrc.Images = svgImageCollection1 '... biUndo.ImageIndex = 3
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();
}
}
}
Imports DevExpress.XtraBars
Imports DevExpress.XtraBars.Ribbon
Imports DevExpress.XtraEditors.Repository
Imports System.Drawing
Namespace DXApplication18
Partial Public Class MainForm
Inherits RibbonForm
Private Function Form2() As Public
InitializeComponent()
'Create Ribbon UI
Dim rc As New RibbonControl()
rc.Images = svgImageCollection1
rc.RibbonStyle = RibbonControlStyle.Office2019
Dim rsb As New RibbonStatusBar()
rsb.Ribbon = rc
Me.Controls.Add(rc)
Me.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
Dim bbiOpen As New BarButtonItem(rc.Manager, "Open", 0)
bbiOpen.RibbonStyle = RibbonItemStyles.Large
bbiOpen.Hint = "Load an existing document"
Dim bbiClose As New BarButtonItem(rc.Manager, "Close", 1)
bbiClose.RibbonStyle = RibbonItemStyles.SmallWithText
Dim bbiCopy As 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
Dim rCat As 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
Dim biUndo As 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
Dim statusLabel As New BarStaticItem() With {.Caption = "Ready", .Alignment = BarItemLinkAlignment.Right}
rc.Items.Add(statusLabel)
rsb.ItemLinks.Add(statusLabel)
Dim riZoom As New RepositoryItemZoomTrackBar()
riZoom.Maximum = 200
riZoom.Minimum = 0
Dim biZoom As New BarEditItem(rc.Manager, riZoom)
biZoom.EditWidth = 150
biZoom.EditValue = 100
rsb.ItemLinks.Add(biZoom)
rc.EndInit()
End Function
End Class
End Namespace