Ribbon Merging
- 7 minutes to read
Like bars, Ribbon Controls support the bar item merging feature in MDI applications. Parent and child MDI forms can contain their own Ribbon Controls and RibbonStatusBars that provide specific bar items. The merging feature allows the Ribbon Control and status bar of a child MDI form to be merged with the main form’s Ribbon Control and status bar.
The Merging Mechanism
A Ribbon Control can be merged with another RibbonControl. The same is true for a RibbonStatusBar. This is useful in MDI applications where the parent and child MDI forms can contain their own Ribbon Controls with specific bar items.
By default, the merging mechanism for a Ribbon Control is invoked when maximizing a child MDI form. In this instance, all bar items of a child form’s Ribbon Control are automatically moved to the main form’s RibbonControl, and the child form’s Ribbon Control is hidden, saving space. When restoring the child form to a normal view, the unmerge mechanism is invoked. Thus, the child form’s Ribbon Control is made visible, and the original layout of bar items within the Ribbon Control is restored.
Refer to the How to: Merge Ribbon Controls topic to view an example.
Automatic merging/unmerging is supported for bar items displayed in a Ribbon Control. Bar commands displayed within a Ribbon Status Bar are not combined automatically. This can be done manually, as described in the Manual Merging section below.
Use the RibbonControl.MdiMergeStyle property of the main MDI form’s Ribbon Control to specify when the merge and unmerge mechanisms are invoked. The available settings are listed in the table below.
| RibbonMdiMergeStyle value | Description |
|---|---|
| Default | This setting is the same as the OnlyWhenMaximized option. |
| OnlyWhenMaximized | Specifies that the merge mechanism is invoked when a child MDI form is maximized. The unmerge mechanism is invoked when a child form is restored from the maximized view. |
| Always | Specifies that the merge mechanism is invoked when a child MDI form is activated. The unmerge mechanism is invoked when a child form becomes inactive. |
| Never | Specifies that the merge mechanism is never invoked. |
The merge mechanism does the following.
- Merges the page content and page groups of a child form’s Ribbon Control with the main form’s RibbonControl.
- Merges page header commands specified by the RibbonControl’s RibbonControl.PageHeaderItemLinks property.
- Merges commands displayed on the Ribbon Quick Access Toolbars.
- Hides the child form’s RibbonControl.
- Fires the RibbonControl.Merge event, which allows additional actions to be performed during a merge (for instance, merging Ribbon Status Bars).
The merge mechanism combines Ribbon elements according to their display captions. If a child Ribbon Control and parent Ribbon Control contain pages with identical display captions, their contents are combined within the main RibbonControl. If the child RibbonControl’s page caption does not match any page in the main RibbonControl, this page is added to the main RibbonControl’s page collection. This also applies to Ribbon page groups.
The unmerge mechanism restores the original bar link layouts within the main and child Ribbon Controls, and fires the RibbonControl.UnMerge event. By handling this event, you can undo additional customizations that have been performed during the RibbonControl.Merge event.
Note
A merge operation hides the child RibbonControl, creates copies of its categories, pages and page groups, and adds these copies to the main RibbonControl. The original child categories, pages and page groups are hidden during the merge operation. To manipulate currently displayed child categories, pages and page groups, access them using the RibbonControl.MergedCategories, RibbonControl.MergedPages, RibbonPage.MergedGroups and RibbonPageCategory.MergedPages collections, which hold the copies of the original counterparts. Changing settings of the original counterparts, when they are hidden, has no visual effect.
To select (activate) a specific main or child page during a merge operation, call the RibbonControl.SelectPage method. This method accepts either a page that belongs to the main Ribbon, or a page that belongs to the currently hidden child Ribbon.
Another way to activate a page that belongs to a child Ribbon during merging is to locate the page’s counterpart in the RibbonControl.MergedPages or RibbonPageCategory.MergedPages collection, and then assign it to the RibbonControl.SelectedPage property.
A child RibbonControl’s bar items are also copied during a merge. The copies are not added to separate collections. Instead, they are added directly to the RibbonPageGroup.ItemLinks, RibbonQuickAccessToolbar.ItemLinks, RibbonStatusBar.ItemLinks and RibbonControl.PageHeaderItemLinks collections.
Manual Merging
Ribbon Status Bars are not merged automatically. If required, they can be merged/unmerged manually using the RibbonStatusBar.MergeStatusBar and RibbonStatusBar.UnMergeStatusBar methods. To merge status bars immediately after the main and child Ribbon Controls have been merged, call the RibbonStatusBar.MergeStatusBar method duing the RibbonControl.Merge event. To unmerge status bars when the unmerge mechanism is invoked, call the RibbonStatusBar.UnMergeStatusBar method during the RibbonControl.UnMerge event.
The automatic merging feature can be disabled by setting the RibbonControl.MdiMergeStyle property to Never. In this instance, Ribbon Controls can be merged and unmerged manually using the RibbonControl.MergeRibbon and RibbonControl.UnMergeRibbon methods, respectively.
Note: The merging of multiple Ribbon Controls and bars into a single RibbonControl/bar is not supported.
Item Merge Modes
When merging, you can specify whether bar items of a child form’s RibbonControl/bar should be added to the main form’s RibbonControl/bar (the default behavior), or if they must replace items on the parent form with identical captions or if they must simply be hidden.
To specify these settings, use the BarItem.MergeType properties of the child form’s bar items. In specific instances, the BarItem.MergeType property for the parent form’s bar items may also need to be changed depending on your requirements (see the table below, which illustrates the available merging techniques).
BarItem.MergeType value | Description |
|---|---|
Add | Specifies that the child form’s bar item will be added to a Ribbon Control or bar item container (e.g., a menu) of a parent form. |
MergeItems | This setting is applied to container items (BarCustomContainerItem descendants). It specifies that subitems of the child form’s container item should be merged with subitems of a parent form’s container item. Merging occurs for the parent form’s container item whose type and BarItem.Caption match the source item, but only if its BarItem.MergeType property is set to MergeItems. Otherwise, the child form’s container item will be added to the parent form’s Ribbon Control (as it is done using the Add setting). |
Remove | For a child form’s bar item, indicates that the item will not be added to the parent form’s Ribbon Control during merging. For a parent form’s bar item, indicates that the item should be removed from the Ribbon Control during merging. |
Replace | Indicates that the child form’s bar item should replace the parent form item that has the same BarItem.Caption, but only if the parent item’s BarItem.MergeType property is also set to Replace. If such an item is not found in the parent form’s RibbonControl, the child form item will be added to the Ribbon Control (as it is done using the Add setting). |
Quick Access Toolbar (QAT) Merging
Quick Access Toolbar merging is a bit more complex. Assume you have RibbonControl objects in both parent and child forms. When these Ribbon Controls are merged, you can add BarItemLinks from the child Ribbon Control to the main RibbonControl’s QAT (this also adds the corresponding link to the child Ribbon’s QAT, so the link is not lost when unmerged). Then, you can save the parent Ribbon layout using the Customization Window. As expected, this saved layout includes information about the QAT along with the child Ribbon’s item links. However, if you restart the application and try to restore this layout, the child Ribbon’s links will only be restored in the parent QAT if the parent and child Ribbons are currently merged. Thus, to make sure a custom user QAT layout is properly restored regardless of whether or not Ribbons are merged, save and restore the layouts for both the child and parent Ribbon Control objects. In this case, even if parent and child forms are currently unmerged, restoring a child RibbonControl’s layout will restore its QAT items. This information will be passed on to the parent Ribbon QAT when these forms are merged.