Bar.Merge(Bar) Method

Adds the visible links from the specified bar onto the current bar.

Namespace: DevExpress.XtraBars

Assembly: DevExpress.XtraBars.v20.1.dll

Declaration

public void Merge(
    Bar bar
)
Public Sub Merge(
    bar As Bar
)

Parameters

Name Type Description
bar Bar

A bar whose links will be added onto the current bar. The current and the specified bar must belong to different BarManagers.

Remarks

In an MDI application, XtraBars gives you the ability to merge the bars of parent and child MDI forms, i.e. combine bar links belonging to different Bar Manager.

The merge mechanism is invoked according to the BarManager.MdiMenuMergeStyle's property value. It allows you to disable merge operations, enable merging when a child form is activated or enable merging when a child form is maximized. For the last two options mentioned, the corresponding unmerge mechanism is invoked when an MDI child becomes inactive or when a child form is restored or minimized from its maximized view.

The main menus of parent and child MDI forms are automatically merged. To merge other bars, you can handle the BarManager.Merge event, which is triggered at the same time as automatic main menu merging, specified by the BarManager.MdiMenuMergeStyle. The Merge method allows you to merge two bars belonging to different BarManagers (usually, parent and child MDI forms have their own managers). You are not able to merge bars belonging to the same BarManager.

To restore the bar layout and remove links that were added by the Merge method, you can call Bar.UnMerge. Usually, you handle the BarManager.UnMerge event to call this method. This event is generated as and when required according to BarManager.MdiMenuMergeStyle.

The order, in which new links will be combined with the existing links during merging is specified by the items' BarItem.MergeOrder properties. Links are combined according to the items' BarItem.MergeType properties. Refer to the MDI Merging document for more information on merging.

You are not able to merge multiple bars with a single bar.

NOTE

If bar items are created at design time and the Merge method should be called when the form is being loaded, the BarManager.ForceInitialize method must be called beforehand.

Examples

Assume you have parent and child MDI forms. On each one you place a Bar Manager and create an Edit toolbar. When the child MDI form is activated, we want to merge these toolbars (XtraBars supports automatic merging of main menus only). For this purpose, the BarManager.Merge event is handled. Toolbars are merged using the Bar.Merge method.

When the child form becomes inactive (for instance, focus may move to another form), we need to restore the original main menu layout of the parent form. For this purpose, the Bar.UnMerge method is called in an BarManager.UnMerge event handler.

using DevExpress.XtraBars;

private void barManager1_Merge(object sender, BarManagerMergeEventArgs e) {
    BarManager parentBarManager = sender as BarManager;
    Bar childBar = e.ChildManager.Bars["Edit"];
    Bar parentBar = parentBarManager.Bars["Edit"];
    parentBar.Merge(childBar);            
}

private void barManager1_UnMerge(object sender, BarManagerMergeEventArgs e) {
    BarManager parentBarManager = sender as BarManager;
    Bar parentBar = parentBarManager.Bars["Edit"];
    parentBar.UnMerge();
}
See Also