MergingProperties.ElementMergingBehavior Attached Property

Gets or sets whether the current container’s elements are merged with elements of outside containers or elements of the same container or both. Also allows you to disable merging. This is an attached property.

Namespace: DevExpress.Xpf.Bars

Assembly: DevExpress.Xpf.Core.v24.1.dll

NuGet Package: DevExpress.Wpf.Core

Declaration

See GetElementMergingBehavior(DependencyObject) and SetElementMergingBehavior(DependencyObject, ElementMergingBehavior).

Returns

Type	Description
ElementMergingBehavior	The merging behavior of the object (or its elements) to which the property is applied.

Remarks

To enable merging, set the ElementMergingBehavior attached property for an element or element container. The ElementMergingBehavior property set for a container is propagated to child elements.

To merge bar objects (for example, MainMenuControl, StatusBarControl, and ToolBarControl), name scopes must be defined. Bar objects can only be merged with other bar objects that are defined in parent name scopes. Thus, bar objects defined in the same name scope or sibling name scopes are never merged. In some cases, name scopes are defined implicitly. To explicitly define a name scope, use the BarNameScope.IsScopeOwner attached property. The BarNameScope.IsScopeOwner topic also provides information on the cases when name scopes are created implicitly.

The following table lists available merge modes:

ElementMergingBehavior Value	Description
ElementMergingBehavior.None	Merging is disabled for elements of a container.
ElementMergingBehavior.InternalWithExternal	A container’s elements are only merged with elements of outside containers defined in parent name scopes (see BarNameScope.IsScopeOwner).
ElementMergingBehavior.InternalWithInternal	A container’s elements are only merged with other elements of the same container provided that they are defined in parent name scopes (see BarNameScope.IsScopeOwner).
ElementMergingBehavior.All	Elements are merged with other elements defined in parent name scopes (see BarNameScope.IsScopeOwner).
ElementMergingBehavior.Undefined	The merging feature is enabled or disabled for the current container, as specified by the merging settings of outer and inner containers. By default, merging is disabled.

Merging is enabled for all main menus, status bars, regular bars and Ribbon controls. However, a regular bar will only be merged with another regular bar if they have the same caption (the Caption property) or the same merge name (the MergingProperties.Name attached property).

To enable merging for certain bar objects and disable it for other objects, use the MergingProperties.ToolBarMergeStyle attached property. For instance, to enable merging only for main menus, set this property to ToolBarMergeStyle.MainMenu.

To merge a container’s elements to a certain target container, you can address the target container with the MergingProperties.Name attached property. This property must be set to the same value for the source and target containers.

You can bind the ElementMergingBehavior property to any Boolean (or Nullable<Boolean>) property. In this case, the following conversion automatically occurs:

• true is converted to ElementMergingBehavior.InternalWithExternal.
• false is converted to ElementMergingBehavior.None.
• null is converted to ElementMergingBehavior.InternalWithInternal.

Example: Merge MainMenuControls When You Select a TabControl’s Tabs

The TabControl in the example has two tabs, each containing a MainMenuControl. The MergingProperties.ElementMergingBehavior property is used to enable the merging of these MainMenuControls to the root MainMenuControl (located outside the TabControl) on tab selection. Note that the MergingProperties.ElementMergingBehavior property is bound to the TabItem.IsSelected Boolean property. The MergingProperties.ElementMergingBehavior property supports automatic conversion from Boolean values to corresponding ElementMergingBehavior enumeration values.

Note

Merging is only supported from a child name scope to the parent name scope. In this example, the root MainMenuControl belongs to the topmost name scope (inherited from the Window object). Child MainMenuControls are located in the tabs that have the ElementMergingBehavior property set. This property implicitly creates a name scope for each tab. This name scope is propagated to the tabs’ child elements.

The following image shows the result:

Xaml

<Window 
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:dxb="http://schemas.devexpress.com/winfx/2008/xaml/bars" 
        xmlns:dx="http://schemas.devexpress.com/winfx/2008/xaml/core"
        x:Class="WpfApplication21.MainWindow"
        Title="MainWindow" Height="350" Width="525">
    <Grid>

        <DockPanel LastChildFill="True">
            <dxb:MainMenuControl DockPanel.Dock="Top">
                <dxb:BarButtonItem Content="File"/>
            </dxb:MainMenuControl>
            <TabControl>
                <TabItem Header="Tab 1" dxb:MergingProperties.ElementMergingBehavior="{Binding IsSelected, RelativeSource={RelativeSource Self}}">
                    <dxb:BarContainerControl>
                        <dxb:MainMenuControl Caption="Main Menu">
                            <dxb:BarButtonItem Content="Tab1: Edit"/>
                        </dxb:MainMenuControl>
                        <dxb:ToolBarControl Caption="Bar">
                            <dxb:BarButtonItem Content="Tab1: Cut"/>
                        </dxb:ToolBarControl>
                    </dxb:BarContainerControl>
                </TabItem>
                <TabItem Header="Tab 2" dxb:MergingProperties.ElementMergingBehavior="{Binding IsSelected, RelativeSource={RelativeSource Self}}">
                    <dxb:BarContainerControl>
                        <dxb:MainMenuControl Caption="Main Menu">
                            <dxb:BarButtonItem Content="Tab2: Help"/>
                        </dxb:MainMenuControl>
                        <dxb:ToolBarControl Caption="Bar">
                            <dxb:BarButtonItem Content="Tab2: About"/>
                        </dxb:ToolBarControl>
                    </dxb:BarContainerControl>
                </TabItem>
            </TabControl>
        </DockPanel>

    </Grid>
</Window>

Example: Merge Bars With Controls That Do Not Support Automatic Merging

This example demonstrates the merging behavior of bars when they are used in controls that don’t support automatic merging.

The example creates a TabControl in which a Tab contains three MainMenuControls:

1) An empty menu called ‘elementHost’.

2) A menu with ‘Cut’, ‘Copy’, and ‘Paste’ commands.

3) A menu with ‘Left’, ‘Center’, and ‘Right’ commands.

The second and third MainMenuControls will be merged to the first MainMenuControl.

The merging feature is enabled with the ElementMergingBehavior property attached to the Tab. This property is set to ‘InternalWithInternal’, which means that the Tab’s internal elements are merged with other internal elements that are defined in parent name scopes.

The ‘elementHost’ MainMenuControl belongs to the name scope inherited from the Window object (a name scope is implicitly created for each Window object). The BarNameScope.IsScopeOwner properties set for the second and third MainMenuControls define child name scopes. Thus, these MainMenuControls will be merged to the ‘elementHost’ MainMenuControl (defined in the parent name scope).

Note

If you want to merge the Tab’s second and third MainMenuControls to the Window’s topmost MainMenuControl (the one that contains ‘File’, ‘Settings’, and ‘Exit’ commands), replace the Tab’s property setting:

dxb:MergingProperties.ElementMergingBehavior="InternalWithInternal"

with:

dxb:MergingProperties.ElementMergingBehavior="InternalWithExternal"

View Example

MainWindow.xaml

<Window
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:dxb="http://schemas.devexpress.com/winfx/2008/xaml/bars" 
        xmlns:dx="http://schemas.devexpress.com/winfx/2008/xaml/core"
        x:Class="WpfApplication20.MainWindow"
        Title="MainWindow" Height="275" Width="525">
    <Grid>

        <Grid.RowDefinitions>
            <RowDefinition Height="Auto"/>
            <RowDefinition Height="*"/>
        </Grid.RowDefinitions>

        <dxb:MainMenuControl Grid.Row="0">
            <dxb:BarButtonItem Content="File"/>
            <dxb:BarButtonItem Content="Settings"/>
            <dxb:BarButtonItem Content="Exit"/>
        </dxb:MainMenuControl>
        <TabControl Grid.Row="1">
            <TabControl.Resources>
                <ControlTemplate x:Key="menuPresenterTemplate" TargetType="ContentControl">
                    <Grid>
                        <Grid.RowDefinitions>
                            <RowDefinition Height="Auto"/>
                            <RowDefinition Height="*"/>
                        </Grid.RowDefinitions>
                        <!--The following MainMenuControl belongs to the name scope implicitly defined for the Window.
                        The Window's name scope is topmost.-->
                        <dxb:MainMenuControl Grid.Row="0" x:Name="elementHost"/>
                        <ContentPresenter  Grid.Row="1"/>
                    </Grid>
                </ControlTemplate>
            </TabControl.Resources>
            <!--Specify the InternalWithInternal merging behavior:  a Tab's elements are only merged with other elements of the same Tab 
                if they are defined in parent name scopes 
            -->
            <TabItem Header="Tab 1" dxb:MergingProperties.ElementMergingBehavior="InternalWithInternal">  
                <ContentControl Template="{StaticResource menuPresenterTemplate}">
                    <StackPanel>
                        <!--control 1-->
                        <!--Explicitly define a name scope for the StackPanel.-->
                        <!--Elements of this container will be merged to the 'elementHost' MainMenuControl, as it is defined in the parent name scope-->
                        <StackPanel dxb:BarNameScope.IsScopeOwner="True">
                            <dxb:MainMenuControl>
                                <dxb:BarButtonItem Content="Cut"/>
                                <dxb:BarButtonItem Content="Copy"/>
                                <dxb:BarButtonItem Content="Paste"/>
                            </dxb:MainMenuControl>
                            <TextBox Text="Text 1"/>
                        </StackPanel>
                        <!--control 2-->
                        <!--Explicitly define a name scope for the StackPanel.-->
                        <!--Elements of this container will be merged to the 'elementHost' MainMenuControl, as it is defined in the parent name scope-->
                        <StackPanel dxb:BarNameScope.IsScopeOwner="True">
                            <dxb:MainMenuControl>
                                <dxb:BarButtonItem Content="Left"/>
                                <dxb:BarButtonItem Content="Center"/>
                                <dxb:BarButtonItem Content="Right"/>
                            </dxb:MainMenuControl>
                            <TextBox Text="Text 2"/>
                        </StackPanel>
                    </StackPanel>
                </ContentControl>
            </TabItem>
            <TabItem Header="Tab 2" dxb:MergingProperties.ElementMergingBehavior="InternalWithInternal">
                <ContentControl Template="{StaticResource menuPresenterTemplate}">
                    <!--...-->
                </ContentControl>                
            </TabItem>
        </TabControl>
    </Grid>
</Window>