Customizing Ribbon at Design Time
- 5 minutes to read
#Dropping Ribbon Control onto Window
When you drop a DXRibbon control onto a Window, you may see the following message: "A RibbonControl must be defined within a BarManager control. Click here to create a BarManager".
The reason for this message is that the Ribbon Control has been dropped onto a Page that does not have a BarManager component. The Ribbon Control must be placed inside a BarManager component, which will serve as a container for Bar Items. To create a BarManager, click the link incorporated into the message, or you can manually wrap a Ribbon Control into a BarManager in XAML.
Once the BarManager has been created, the Ribbon Control is displayed in its normal way at design time.
The new Ribbon Control contains a default page category (the default category's caption is never visible), a "Home" page within this category and a "Tools" page group within this page. The following sections show how to create new page categories, pages, page groups and bar items.
You can select between the Office 2007 and Office 2010 paint styles for the Ribbon Control via the RibbonControl.RibbonStyle property. Below, this property is set to Office2010:
<dxr:RibbonControl Name="ribbonControl1" DockPanel.Dock="Top" RibbonStyle="Office2010">
. . .
#Creating Ribbon Page Categories
Initially, the Ribbon Control contains a single default page category (RibbonDefaultPageCategory) (the default category's caption is never visible). Pages displayed within the default category can be considered as main, context-independent pages. You can add custom page categories to the Ribbon by right-clicking the Ribbon Control and selecting the Add RibbonPageCategory command from the menu:
This command adds a new Page Category containing a single page, whose caption is highlighted when selected:
You will notice that corresponding code has been added to the XAML to create a new Page Category:
<dxr:RibbonControl Name="ribbonControl1" DockPanel.Dock="Top" RibbonStyle="Office2010">
. . .
<dxr:RibbonPageCategory Caption="Ribbon Category">
<dxr:RibbonPage Caption="Ribbon Page 2" Name="ribbonPage2" />
</dxr:RibbonPageCategory>
</dxr:RibbonControl>
The visibility of page categories (and therefore the visibility of pages belonging to this category) can be changed via the RibbonPageCategoryBase.IsVisible property.
To specify the background color for custom categories and pages, use the RibbonPageCategoryBase.Color property. This color is mixed with the control's background when captions of page categories and pages are rendered.
See Ribbon Page Categories and Contextual Pages, to learn more about page categories.
#Creating Pages
To add Ribbon Pages to the default or custom Page Category, right-click at any point within this category (for instance, you can right-click a page header belonging to this category) and select the Add RibbonPage menu command:
This adds a new Page to the clicked category:
The corresponding code is added to the XAML:
<dxr:RibbonControl Name="ribbonControl1" DockPanel.Dock="Top" RibbonStyle="Office2010">
<dxr:RibbonDefaultPageCategory Caption="defaultCategory" Name="ribbonDefaultPageCategory1">
<dxr:RibbonPage Caption="Home" Name="ribbonPage1">
<dxr:RibbonPageGroup Caption="Tools" Name="ribbonPageGroup1" />
</dxr:RibbonPage>
<dxr:RibbonPage Caption="Ribbon Page 3" Name="ribbonPage3" />
</dxr:RibbonDefaultPageCategory>
. . .
#Creating Page Groups
Like Pages, Page Groups can also be created via context menus. Click any point within a page to open the context menu and select Add RibbonPageGroup:
This command adds a new Page Group to the clicked page by generating the corresponding XAML code:
<dxr:RibbonPage Caption="Home" Name="ribbonPage1">
<dxr:RibbonPageGroup Caption="Tools" Name="ribbonPageGroup1" />
<dxr:RibbonPageGroup Caption="Ribbon Page Group 2" Name="ribbonPageGroup2" />
</dxr:RibbonPage>
#Creating Bar Items
Regular and check buttons, submenus, static text, different editors from the DXEditors library, string lists, etc can be embedded into the Ribbon Control by creating corresponding Bar Item and Bar Item Link objects. Bar Items, which are non-visual elements, implement business logic. Bar Item Links - visual elements - refer to particular Bar Items and can render themselves onscreen. This object model allows you to create multiple Bar Item Links referring to a single Bar Item and display these links at different places within the Ribbon Control and external PopupMenus (if needed). To learn more, see Bar Items and Links.
You can add new Bar Items and Bar Item Links via a context menu invoked for Ribbon Page Groups. The context menu contains the Add BarItem sub-menu, which provides access to a list of available Bar Items:
A click on any Bar Item does two things. First, a corresponding BarItem descendant is added to the BarManager.Items collection:
<dxb:BarManager Name="barManager1">
<dxb:BarManager.Items>
<dxb:BarButtonItem Content="barButtonItem1" Name="barButtonItem1" />
</dxb:BarManager.Items>
. . .
Second, a Bar Item Link referring to the generated Bar Item is added to the clicked Ribbon Page Group:
<dxr:RibbonPageGroup Caption="Ribbon Page Group 2" Name="ribbonPageGroup2">
<dxb:BarButtonItemLink BarItemName="barButtonItem1" />
</dxr:RibbonPageGroup>
Note that the Bar Item Link refers to the Bar Item by its name ("barButtonItem1").
#Selecting Ribbon Elements
At design time, you can click any visual Ribbon element (custom Ribbon Page Category, Page, Page Group and Bar Item Link) to highlight this element in XAML and list the element's settings in the Properties window:
When you click a Bar Item Link for the first time, the corresponding Bar Item object is highlighted in XAML and this Bar Item's settings are shown in the Properties window. A subsequent click on the same Bar Item Link results in highlighting this link in XAML and showing the link's settings in the Properties window.
#Adding Bar Items to Application Menu, Quick Access Toolbar and Page Header Region
Existing Bar Item Links can be copied to the Application Menu, Ribbon Quick Access Toolbar and Page Header Region (the region at the right edge of the Ribbon Control in line with Ribbon Page Headers). To copy a Bar Item Link to these regions, right-click the link and select one of the menu commands: Add to Quick Access Toolbar, Add to Page Header or Add to Application Menu:
When copied to the Quick Access Toolbar, Bar Item Links are added to the RibbonControl.ToolbarItemLinks collection. Copying links to the Page Header Region adds them to the RibbonControl.PageHeaderItemLinks collection.
If you add Bar Item Links to an Application Menu, this menu is created, if it doesn't exist.