Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Expand]Editors and Simple Controls
  [Collapse]Ribbon, Bars and Menu
   [Expand]Bars
   [Collapse]Ribbon
    [Expand]The Ribbon UI
    [Expand]Visual Elements
    [Expand]Items and Item Links
     Ribbon Styles
    [Expand]Galleries
    [Expand]Main Menus
    [Expand]Ribbon Control Designer
    [Collapse]Runtime Capabilities
      Ribbon Merging
      Key Tips
      Runtime Customization
      Touch Support
    [Expand]Miscellaneous
     Known Issues
   [Expand]Popup Menus
    Radial Menu
   [Expand]Common Features
   [Expand]Examples
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Ribbon Merging

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.

Expanded 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.

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: When performing a merge, the copies of a child RibbonControl's categories, pages and page groups are added to the main RibbonControl, and not to the objects themselves. So, after Ribbon Controls have been merged, do not access the merged objects using the merged child RibbonControl. Instead, use the RibbonControl.MergedCategories, RibbonControl.MergedPages, RibbonPage.MergedGroups and RibbonPageCategory.MergedPages properties. For instance, to activate a specific merged page, locate it in the RibbonControl.MergedPages collection or the 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.

Expanded 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.

Expanded 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).

Expanded 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.

Expanded Examples

Expanded See Also

How would you rate this topic?​​​​​​​