Ribbon Merging
- 5 minutes to read
Ribbon Controls and Ribbon Status Bars support the item merge feature in MDI applications. This feature allows you to temporarily hide the Ribbon and/or Status Bar Controls, and move their items to the main form’s Ribbon (Status Bar).
Merge Style
A merge typically triggers when a child MDI form is maximized. When a child form is restored to a normal view, this form’s Ribbon and Status Bar controls become visible again.
To specify when merge/unmerge processes trigger, use the RibbonControl.MdiMergeStyle property of the main MDI form’s Ribbon Control.
- Default - this setting is the same as the OnlyWhenMaximized option.
- OnlyWhenMaximized - Ribbons merge when a child MDI form is maximized.
- Always - Ribbons merge whenever a child MDI form becomes active.
- Never - use this mode to prevent child form controls from automatically merging with main form controls. Call the RibbonControl.MergeRibbon and RibbonControl.UnMergeRibbon methods to merge or unmerge Ribbons.
Refer to this help article for the sample: How to: Merge Ribbon Controls.
How Ribbon Merging (Unmerging) Works
The merge process has the following stages:
- Child pages and page groups are copied to the main form’s RibbonControl.
- Page header commands (the RibbonControl.PageHeaderItemLinks collection) are copied.
- Ribbon Quick Access Toolbar commands are copied.
- The child form RibbonControl is hidden.
- The parent Ribbon Control fires the RibbonControl.Merge event. Handle it to perform additional actions (for instance, merge Status Bars).
Ribbon elements are combined by captions: if child and parent Ribbon Controls have pages with same captions, these pages are merged. If there is no parent Ribbon page with the same caption, main Ribbon adds a new blank page.
The unmerge mechanism restores original bar link layouts in the main and child Ribbon Controls, and fires the RibbonControl.UnMerge event. Handle it to undo additional customizations that you performed on the RibbonControl.Merge event.
Unlike Ribbon Controls, child Ribbon Status Bars cannot automatically move their items into a parent form Status Bar. See the How to Manually Merge Controls section for more information.
Note
A parent control can be merged with only one child control. To merge another child control, you first need to unmerge the previous.
What Happens to Merged Pages, Groups and Bar Items
When a child RibbonControl is merged, its categories, pages and page groups are copied. These copies are placed into the following collections of the main Ribbon:
- the RibbonControl.MergedCategories collection stores copies of child Ribbon categories;
- the RibbonControl.MergedPages collection stores child Ribbon page copies;
- the RibbonPage.MergedGroups collection stores child page group copies;
- the RibbonPageCategory.MergedPages collection stores contextual page copies.
Any change applied to an original (source) item has no effect. Use these collections to modify source item copies.
Child RibbonControl bar items are also copied during a merge. These copies are added to same collections that store regular parent Ribbon items:
- RibbonPageGroup.ItemLinks
- RibbonQuickAccessToolbar.ItemLinks
- RibbonStatusBar.ItemLinks
- RibbonControl.PageHeaderItemLinks
How to Activate a Specific Page After Merging Ribbon Controls
When two Ribbons merge, you can call the RibbonControl.SelectPage method to select an active page. This method accepts both parent and child Ribbon pages.
Another way to activate a child Ribbon page is to locate this page copy in the RibbonControl.MergedPages or RibbonPageCategory.MergedPages collection, and assign it to the RibbonControl.SelectedPage property.
How to Manually Merge Controls
Ribbon Status Bars are not merged automatically. To merge and unmerge Status Bars:
handle the parent RibbonControl.Merge event and call the RibbonStatusBar.MergeStatusBar method;
handle the parent RibbonControl.UnMerge event and call the RibbonStatusBar.UnMergeStatusBar method.
private void RibbonControl1_Merge(object sender, RibbonMergeEventArgs e) {
RibbonControl parentRRibbon = sender as RibbonControl;
RibbonControl childRibbon = e.MergedChild;
parentRRibbon.StatusBar.MergeStatusBar(childRibbon.StatusBar);
}
private void RibbonControl1_UnMerge(object sender, RibbonMergeEventArgs e) {
RibbonControl parentRRibbon = sender as RibbonControl;
parentRRibbon.StatusBar.UnMergeStatusBar();
}
Item Merge Modes
To specify what happens to merged Ribbon items, specify their BarItem.MergeType properties.
Add - the bar item is added to a Ribbon Control or to the bar item container (e.g., a menu) of a parent form.
MergeItems - set this mode for both parent and child Ribbon container items (descendants of the BarCustomContainerItem class) to merge their subitems.
Remove - merged Ribbons do not show items with this MergeStyle property value.
Replace - if there are items with the same caption in both child and parent Ribbons, and these items’
MergeStyleequals “Replace”, the child item replaces the parent item. If no parent item is found, the child item is added to the “Add” mode.
Quick Access Toolbar (QAT) Merging
When you merge two Ribbons, you can add a link to a child Ribbon item in the parent Ribbon’s Quick Access Toolbar. This also adds a corresponding link to the child Ribbon QAT, so that the link is not lost when Ribbons unmerge.
A user can save the parent Ribbon layout using the Customization Window. When the application restarts and you attempt to restore this saved layout while the Ribbons are not merged, neither of the QATs will display this link. To prevent this from happening, save/restore the child Ribbon layout as well.