MDI Bar Merging

• May 22, 2020
• 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 Toolbar-Menu 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.

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

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

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.

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