MDI Bar Merging
- 5 minutes to read
You can implement MDI mode in your applications using the DocumentGroup and DocumentPanel objects. The DocumentGroup will be a container for individual windows/panels (DocumentPanel objects).
The Bars library allows you to add menus and bars to your application. You can create bars at the root level and for individual DocumentPanel objects at the same time. For instance, the menu at the root level can provide general commands for working with files, windows, etc, while a child window (panel) can have bars and menus providing specific functionality.
When your application contains menus and bars at the root level and within individual DocumentPanel objects, the bar merging feature is supported.
Note
Refer to the MDI Ribbon Merging document if you use Ribbon controls instead of traditional toolbars.
With the bar merging feature, child menus and bars are merged into the parent menus and bars, as specified by the bar’s settings.
Menus and bars are implemented using a BarManager control, which is a container for all bar objects. To define bars at the root level, you need to define a BarManager object at the root level (In the text below we’ll refer to it as the parent BarManager). To define bars within a DocumentPanel, you need to define a separate BarManager within this panel. We’ll refer to it as the child BarManager.
The merging mechanism merges menus and bars of a child BarManager into the menus and bars of a parent BarManager. The unmerge mechanism restores the previous layout.
The Merging Mechanism
By default, the merging mechanism is invoked:
- in regular MDI mode, when a DocumentPanel is maximized.
- in tabbed MDI mode, when a tab (DocumentPanel) is activated.
The unmerge mechanism is invoked:
- in regular MDI mode, when a DocumentPanel is restored from the maximized to the normal state or before another DocumentPanel is maximized.
- in tabbed MDI mode, when a tab (DocumentPanel) is deactivated (for instance, before another tab is selected).
Note
When a bar is populated with items based on a certain ViewModel collection, the merging functionality can correctly work only if this bound bar is populated before another bar is merged with it. To make sure that your bar is populated before it is merged with another one, disable the automatic merging functionality and manually merge bars when they are loaded.
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 bar merging, allow merging for activated tabs and maximized MDI panels only, or specify that all currently activated tabs and maximized MDI panels should be merged at the same time. To specify the merging behavior for individual panels, use the DocumentPanel.MDIMergeStyle attached property instead. This property has a higher priority than the DockLayoutManager.MDIMergeStyle property.
Set the BarManager.MDIMergeStyle property to MDIMergeStyle.Never to prevent bars from being merged.
Automatic and Manual Bar Merging
Automatic merging/unmerging is supported for main menus. Other bars need to be merged and unmerged manually. For this purpose, you can handle the DockLayoutManager.Merge and DockLayoutManager.UnMerge events. The latter allows you to undo the results of the manual merge operation you performed via the DockLayoutManager.Merge event handler.
To merge two bars that belong to different BarManagers, call the parent bar’s Bar.Merge method. Call Bar.UnMerge to restore the original links layout for the bar, after the merge operation.
Similarly, use ILinksHolder.Merge and ILinksHolder.UnMerge methods to perform merging operations on link containers (e.g., submenu).
Links Merging Types
During merging, you can specify whether the bar item links of a child BarManager’s bar/link container should be added to the parent BarManager’s bar/link container (this is the default behavior), should replace item links on the parent bar with identical captions or should be removed from a bar.
To specify these settings, use the BarItemLinkBase.MergeType properties of the child BarManager’s links that need to be merged. Note that the settings for the parent BarManager’s links may also need to be changed in specific cases, to get the desired behavior (see the table below which illustrates the available merging techniques):
| BarItemLinkBase.MergeType value | Description |
|---|---|
| Add | Specifies that the child BarManager’s BarItemLink should be added to a bar/link container of a parent BarManager. When merging bars and link containers, the position to insert the BarItemLink is determined by the BarItemLinkBase.MergeOrder properties of this link and of the links within the target bar/link container. |
| MergeItems | This setting is applied to link containers (e.g. sub-menu). It specifies that subitems of the child BarManager’s link container should be merged with subitems of a parent BarManager’s link container. Merging occurs for the parent BarManager’s link container, when the type and BarItem.Content match the source item, and only if its BarItemLinkBase.MergeType property is set to MergeItems. Otherwise, the child BarManager’s link container will be added to the parent BarManager’s bar (similar to the Add setting). |
| Remove | For a child BarManager’s BarItemLink, indicates that the link must not be added to the parent BarManager’s bar/link container during merging. For a parent BarManager’s BarItemLink, indicates that the link must be removed from the bar/link container during merging. |
| Replace | Indicates that the child BarManager’s BarItemLink should replace the parent BarManager’s link that has the same BarItem.Content, but only if the parent link’s BarItemLinkBase.MergeType property is also set to Replace. If such a link is not found in the parent BarManager’s bar/link container, the child BarManager’s link will be added to the bar/link container (similar to the Add setting). |
When adding items during a merge operation, the original links of a parent BarManager and the new links of the child BarManager are arranged according to their BarItemLinkBase.MergeOrder property values. Links with the lowest MergeOrder come first. The last links will be those that have the greatest MergeOrder value. If a parent BarManager’s bar has links with a MergeOrder equal to the MergeOrder of a child BarManager’s link, then the child BarManager’s link will be placed after all the parent BarManager’s matching links.