RibbonControl Class
Allows you to create a Ribbon toolbar with commands grouped into categories, pages and page groups. See Ribbon.
Namespace: DevExpress.XtraBars.Ribbon
Assembly: DevExpress.XtraBars.v20.2.dll
NuGet Package: DevExpress.Win.Navigation
Declaration
public class RibbonControl :
ControlBase,
IBarObject,
IXtraSerializable,
IXtraSerializableLayout,
ICustomBarControl,
IExtenderProvider,
IDXMenuManager,
IDXDropDownMenuManager,
ISupportXtraAnimation,
IToolTipControlClientEx,
IToolTipControlClient,
IEditorBackgroundProvider,
IBackstageViewOwner,
ISupportInitialize,
ISupportGlassRegions,
IGestureClient,
ISupportAdornerUIRibbon,
ISupportAdornerUIManager,
IWin32Window,
IUpdateAdornerUI,
IPopupControlOwner,
ICommandOwnerControl,
ISupportDXSkinColors,
ISupportImageDragDrop,
IXtraSupportForceInitialize,
IScaleDpiProviderRemarks
The Ribbon Control displays various commands, generally represented as buttons, by categorizing them into pages and page groups. The following screenshot shows a sample Ribbon Control which consists of two pages (“Home” and “View”). The first page contains three groups (“New”, “Actions”, and “Quick Letter”), and each group contains specific commands.
Structurally, a Ribbon Control contains one or more pages which are displayed as tabs. The control’s pages, which are represented by RibbonPage objects, can be accessed with the RibbonControl.Pages collection. You can use the RibbonControl.Pages property to add, remove and access specific pages and customize their settings.
A Ribbon page is divided into groups which display specific commands. Page groups (RibbonPageGroup class objects) can be accessed from the RibbonPage.Groups property.
Each page group can display various elements: buttons, static text, submenus, editors, etc. To add a specific element to the group, create a corresponding bar item and add it to the RibbonPageGroup.ItemLinks collection. For information on bar items and bar item links, refer to Items and Item Links.
Note
If you create bar items in code, ensure the following:
- All bar items are added to the RibbonControl.Items collection. Otherwise, bar items may not function properly (for instance, a submenu may not be displayed).
The following list shows the correct ways to create bar items while adding them to the RibbonControl.Items collection.
- Using the BarItems.CreateButton, BarItems.CreateCheckItem, BarItems.CreateMenu, BarItems.CreateSplitButton and RibbonBarItems.CreateButtonGroup methods of the RibbonControl.Items object.
- Using the BarItem descendant constructor with the manager parameter. Pass the object specified by the RibbonControl.Manager property as this parameter.
- Using the BarItem descendant default constructor and then manually adding the created bar item to the RibbonControl.Items collection.
- All bar items have their BarItem.Id properties initialized to unique values. This ensures correct functioning of the bar item (de)serialization mechanism.
The BarItem.Id properties can be initialized with the BarManager.GetNewItemId method accessible from the RibbonControl.Manager object.
The Quick Access Toolbar displayed by default at the top of the Ribbon Control allows you to display the most used commands. Use the RibbonControl.ToolbarLocation property to control the toolbar’s position and visibility. The RibbonControl.Toolbar property permits you to access the toolbar and customize its contents.
For more information on Ribbon elements, see Ribbon Control.
Popup Menus for External Controls
When you place a RibbonControl on a form at design time, all controls publish the PopupContextMenu extender property (its caption in the Properties window looks like ‘PopupContextMenu on ribbonControl1’). You can use this property to assign a PopupMenu or RadialMenu menu for this control. This menu will be displayed when right-clicking the control at runtime.
To assign a popup menu for a control in code, use the RibbonControl.SetPopupContextMenu method.
Note
Specific complex controls such as Grid Control and Tree List do not publish the PopupContextMenu property, as these controls support different context menus for different visual elements. See the help documentation on these products to learn how to work with context menus in these controls.
Notes
Note
Using regular bars (a BarManager component) and a RibbonControl within the same form/user control is not recommended, as the Bar Manager and Ribbon Control components may conflict with each other. Use either a Bar Manager or a Ribbon Control within a single form/user control.
Example
This example demonstrates how to create a RibbonControl and
RibbonStatusBar in code.
The RibbonControl contains one page (“Home”), two page groups (“File” and “File 2”) and three commands (bar items). The RibbonStatusBar contains two commands aligned to the left and right respectively.
When you create a Ribbon UI in code, ensure the following:
- All bar items are added to the RibbonControl.Items collection.
- All bar items have their BarItem.Id properties initialized to unique values.
using DevExpress.XtraBars.Ribbon;
using DevExpress.XtraBars;
private void Form1_Load(object sender, EventArgs e) {
// Create a RibbonControl
RibbonControl ribbon = new RibbonControl();
this.Controls.Add(ribbon);
// Assign the image collection that will provide images for bar items.
ribbon.Images = imageCollection1;
// Create a Ribbon page.
RibbonPage page1 = new RibbonPage("Home");
// Create a Ribbon page group.
RibbonPageGroup group1 = new RibbonPageGroup("File");
// Create another Ribbon page group.
RibbonPageGroup group2 = new RibbonPageGroup("File 2");
// Create a button item using the CreateButton method.
// The created item is automatically added to the item collection of the RibbonControl.
BarButtonItem itemOpen = ribbon.Items.CreateButton("Open...");
itemOpen.ImageIndex = 0;
itemOpen.Id = ribbon.Manager.GetNewItemId(); //Ensures correct runtime layout (de)serialization.
itemOpen.ItemClick += new ItemClickEventHandler(itemOpen_ItemClick);
// Create a button item using its constructor.
// The constructor automatically adds the created item to the RibbonControl's item collection.
BarButtonItem itemClose = new BarButtonItem(ribbon.Manager, "Close");
itemClose.ImageIndex = 1;
itemClose.Id = ribbon.Manager.GetNewItemId(); //Ensures correct runtime layout (de)serialization.
itemClose.ItemClick += new ItemClickEventHandler(itemClose_ItemClick);
// Create a button item using the default constructor.
BarButtonItem itemPrint = new BarButtonItem();
// Manually add the created item to the item collection of the RibbonControl.
ribbon.Items.Add(itemPrint);
itemPrint.Caption = "Print";
itemPrint.ImageIndex = 2;
itemPrint.Id = ribbon.Manager.GetNewItemId(); //Ensures correct runtime layout (de)serialization.
itemPrint.ItemClick += new ItemClickEventHandler(itemPrint_ItemClick);
// Add the created items to the group using the AddRange method.
// This method will create bar item links for the items and then add the links to the group.
group1.ItemLinks.AddRange(new BarItem[] { itemOpen, itemClose, itemPrint });
// Add the Open bar item to the second group.
group2.ItemLinks.Add(itemOpen);
// Add the created groups to the page.
page1.Groups.Add(group1);
page1.Groups.Add(group2);
// Add the page to the RibbonControl.
ribbon.Pages.Add(page1);
//...
// Create a status bar with two commands.
RibbonStatusBar ribbonStatusBar = new RibbonStatusBar();
ribbonStatusBar.Ribbon = ribbon;
BarItemLink linkClose = ribbonStatusBar.ItemLinks.Add(itemClose);
linkClose.UserRibbonStyle = RibbonItemStyles.SmallWithoutText;
linkClose.UserAlignment = BarItemLinkAlignment.Right;
BarItemLink linkPrint = ribbonStatusBar.ItemLinks.Add(itemPrint);
linkPrint.UserRibbonStyle = RibbonItemStyles.SmallWithoutText;
ribbonStatusBar.Parent = this;
}
void itemPrint_ItemClick(object sender, ItemClickEventArgs e) {
//...
}
void itemClose_ItemClick(object sender, ItemClickEventArgs e) {
//...
}
void itemOpen_ItemClick(object sender, ItemClickEventArgs e) {
//...
}