Merging Overview
- 4 minutes to read
Ribbon merging allows you to combine elements of two different ribbon controls or ribbon status bars. This makes sense in MDI-like applications, where both main and child windows have their own ribbon controls and ribbon status bars. Although WPF lacks the native support of the MDI creation, you can overcome this with the help of the DevExpress DockLayoutManager component. This component provides the DocumentGroup and DocumentPanel containers that help you create native and tabbed MDI interfaces. The following animation illustrates how ribbon merging operates.
The merging process affects the following elements: RibbonPageCategorys, RibbonPages, RibbonPageGroups and BarItemLinks within page groups, quick access toolbars and ribbon status bar controls. These elements are being added from a child RibbonControl (RibbonStatusBarControl) to the parent RibbonControl (RibbonStatusBarControl).
#The Merging Mechanism
By default, the merging mechanism is triggered:
- when a DocumentPanel is maximized in a regular MDI mode.
- when a tab (DocumentPanel) is activated in a tabbed MDI mode.
This default behavior can be changed via the DockLayoutManager.MDIMergeStyle property that affects all child panels within a DockLayoutManager. Depending on this property value, you can either completely restrict ribbon merging, allow merging for activated tabs and maximized MDI panels only, or specify all currently activated tabs and maximized MDI panels should be merged at the same time. To specify merging behavior for individual panels, use the DocumentPanel.MDIMergeStyle attached property instead. This property has a higher priority than the DockLayoutManager.MDIMergeStyle property.
To merge ribbon objects, use the RibbonControl.Merge and/or RibbonStatusBarControl.Merge methods in the DockLayoutManager.Merge event as shown below.
private void dockLayoutManager1_Merge(object sender, DevExpress.Xpf.Docking.BarMergeEventArgs e) {
RibbonControl childRC = RibbonControl.GetRibbon(e.ChildBarManager);
RibbonControl mainRC = RibbonControl.GetRibbon(e.BarManager);
mainRC.Merge(childRC);
RibbonStatusBarControl childSB = RibbonStatusBarControl.GetRibbonStatusBar(e.ChildBarManager);
RibbonStatusBarControl mainSB = RibbonStatusBarControl.GetRibbonStatusBar(e.BarManager);
mainSB.Merge(childSB);
}
Every element that is being merged has the MergeType property, which regulates how exactly parent and child ribbon elements merge. For instance, using the MergeType property, you can specify that parent and child ribbon elements with the same caption should be combined into a single element. You can also specify that child ribbon elements should be simply added to the parent ribbon or hidden after merging. See the DevExpress.Xpf.Ribbon.RibbonMergeType topic for information on available merging options. To change merge types for ribbon elements, use the RibbonPageCategoryBase.MergeType, RibbonPage.MergeType, RibbonPageGroup.MergeType and BarItemLinkBase.MergeType properties.
By default, merged elements are arranged in the following order: first are the parent object elements and then child object elements . You can re-arrange elements during a merge using the MergeOrder property (see the RibbonPageCategoryBase.MergeOrder, RibbonPage.MergeOrder, RibbonPageGroup.MergeOrder and BarItemLinkBase.MergeOrder topics to learn more). The first element comes with the MergeOrder of 0. An element with the greatest MergeOrder value is the last. The default MergeOrder value for all elements is 0.
Consider the following Ribbon Controls:
The parent Ribbon Control:
<dxr:RibbonPage MergeOrder="0" Caption="Home" Name="mainHomePage"> ... </dxr:RibbonPage>
<dxr:RibbonPage MergeOrder="2" Caption="View" Name="mainViewPage"> ... </dxr:RibbonPage>
The child Ribbon Control:
<dxr:RibbonPage MergeOrder="1" Caption="Insert" Name="child2InsertPage"> ... </dxr:RibbonPage>
<dxr:RibbonPage MergeOrder="3" Caption="Add-ins" Name="child2AddInsPage"> ... </dxr:RibbonPage>
<dxr:RibbonPage MergeOrder="4" Caption="Test" Name="child2TestPage"> ... </dxr:RibbonPage>
Merging these Ribbon Controls will cause the page arrangement shown below.
After elements are merged according to the MergeType and MergeOrder properties, the merging process repeats the described actions for merging sub-items. This means page categories are merged and arranged first. Then come ribbon pages, ribbon page groups and lastly - group items (commands). All these sub-elements have their own independent MergeType and MergeOrder properties, just like their holders.
#Unmerging Mechanism
The merging operation is not irreversible. The unmerging is performed via the RibbonControl.UnMerge and RibbonStatusBarControl.UnMerge methods. If you have merged multiple Ribbon objects, you can either define which child Ribbon object should be umerged from the parent one or completely restore the parent control's layout. In the latter case, use the required Unmerge method with no parameters.
The most common way to perform an unmerging operation is to handle the DockLayoutManager.UnMerge event, which is the reverse for the DockLayoutManager.Merge event. So in order to unmerge parent and child ribbon objects, use the same code as in the 'Merging Mechanism' section and simply replace Merge methods with related Unmerge ones.