A newer version of this page is available. Switch to the current version.

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.v18.2.dll

Declaration

[ToolboxBitmap(typeof(ToolboxIconsRootNS), "RibbonControl")]
public class RibbonControl :
    ControlBase,
    IBarObject,
    IXtraSerializable,
    ICustomBarControl,
    IExtenderProvider,
    IDXMenuManager,
    IDXDropDownMenuManager,
    ISupportXtraAnimation,
    IToolTipControlClientEx,
    IToolTipControlClient,
    IEditorBackgroundProvider,
    IBackstageViewOwner,
    ISupportInitialize,
    ISupportGlassRegions,
    IGestureClient,
    ISupportAdornerUIRibbon,
    ISupportAdornerUIManager,
    IWin32Window,
    IUpdateAdornerUI,
    IPopupControlOwner,
    ICommandOwnerControl,
    ISupportDXSkinColors,
    ISupportImageDragDrop,
    IXtraSupportForceInitialize

Remarks

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.

RibbonControl

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:

  1. 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.

  1. 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.

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.

RibbonControl-PopupContextMenuOn

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.

Examples

This example demonstrates how to create a RibbonControl with one page (“Home”) and two page groups (“File” and “File 2”).

Ribbon_CreateTwoGroups_Ex

Ribbon commands are called bar items, as they are all derived from the BarItem class. This example creates three bar items - the Open, Close and Print buttons, encapsulated by the BarButtonItem objects. The Close and Print buttons are only added to the first group, while the Open button is added to both of the groups.

When bar items are created in code, ensure the following:

  1. All bar items are added to the RibbonControl.Items collection.

    This example demonstrates three ways of creating bar items while adding them to the RibbonControl.Items collection.

  2. 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. See the code below.

using DevExpress.XtraBars.Ribbon;
using DevExpress.XtraBars;

// 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);
//...


void itemPrint_ItemClick(object sender, ItemClickEventArgs e) {
   //...
}

void itemClose_ItemClick(object sender, ItemClickEventArgs e) {
   //...
}

void itemOpen_ItemClick(object sender, ItemClickEventArgs e) {
   //...
}
See Also