windowsforms-3451-controls-and-libraries-ribbon-bars-and-menu-ribbon-runtime-capabilities-ribbon-merging.md
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).
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.
Refer to this help article for the sample: How to: Merge Ribbon Controls.
The merge process has the following stages:
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.
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:
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:
Note
The Customize the Ribbon... command is not displayed in the context menu when the Ribbon controls are merged.
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.
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();
}
Private Sub RibbonControl1_Merge(ByVal sender As System.Object, _
ByVal e As RibbonMergeEventArgs) Handles RibbonControl1.Merge
Dim parentRRibbon As RibbonControl = TryCast(sender, RibbonControl)
Dim childRibbon As RibbonControl = e.MergedChild
parentRRibbon.StatusBar.MergeStatusBar(childRibbon.StatusBar)
End Sub
Private Sub RibbonControl1_UnMerge(ByVal sender As System.Object, _
ByVal e As RibbonMergeEventArgs) Handles RibbonControl1.UnMerge
Dim parentRRibbon As RibbonControl = TryCast(sender, RibbonControl)
parentRRibbon.StatusBar.UnMergeStatusBar()
End Sub
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’ MergeStyle equals “Replace”, the child item replaces the parent item. If no parent item is found, the child item is added to the “Add” mode.
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.
The WinForms Document Manager component allows you to easily create popular classic and modern application UIs: tabbed MDI, native MDI, Windows 10-inspired, and Widget UI.
See Also