Bar Actions

• Aug 01, 2019
• 7 minutes to read

You can define the structure of bars in two ways:

• Directly between the BarManager start and end tags. In this approach, you define the explicit hierarchical structure of bar objects (Bar, BarItem and BarItemLink objects).

• Using bar customization actions, which are dedicated objects capable of creating bars, bar items and bar item links, or by modifying the existing structure of a BarManager object.

  In general, bar customization actions are used when you do not have direct access to the BarManager. For instance, these actions can be used to customize the layout of bars within a predefined Print Preview window (How to: Customize the Document Preview Toolbar), and to modify a control’s built-in menu (How to: Remove Items from the Context Menu). In other cases, it is up to you whether to define bars and items directly, or use actions.

  Actions are defined separately from a BarManager object. Typically, multiple actions are required to modify/create the structure of bars, and the actions are put together into a linear list in resources. A BarManager executes the actions, applying them to the current structure of bar objects.

  Since actions can be defined in resources, they can be shared between multiple windows or even applications (if actions are defined in the resources of a DLL library). For instance, you can define actions that create a bar (MyBar) with some bar items. If these actions are linked to a BarManager, they will be executed (after the BarManager’s own bars are initialized by default), and the new MyBar (including its items) will be added to the existing structure of bars.

Actions

Actions are objects that implement the IBarManagerControllerAction interface. All actions have an internal Execute method that implements the action’s functionality. When a list of actions is executed, the Execute method is called for every action, in the order defined by the list.

The Bar class and all descendants of the BarItem and BarItemLink classes implement the IBarManagerControllerAction interface, so that these objects can serve as actions.

The following table lists the available actions and attached properties supported by the actions.

Action	Description
Bar	Adds/inserts a Bar to the BarManager.Bars collection.   Attached properties: InsertBarAction.BarIndex - Allows you to specify the position at which a bar is inserted in the BarManager.Bars collection. If this property is omitted, the bar is appended to the bar collection.
BarItem class descendants	Adds/inserts a bar item to the BarManager.Items collection, and optionally allows you to create a link for the bar item and add/insert it to a target link holder (a bar, menu, etc.). A link is created if the BarItemLinkActionBase.Target or BarItemLinkActionBase.TargetType attached property is specified.   Attached properties: InsertBarItemAction.ItemIndex - Allows you to specify the position at which a bar item is inserted into the BarManager.Items collection. If this property is omitted, the item is appended to the item collection. BarItemLinkActionBase.Target - Allows you to specify the name of the target link holder to which the created link is added. The Target property is in effect when the TargetType attached property is not specified, or set to Other. BarItemLinkActionBase.TargetType - Allows you to specify the type of the target link holder to which the created link is added. BarItemLinkActionBase.ItemLinkIndex - Allows you to specify the position at which the created link is inserted in the target link holder. If this property is omitted, the link is appended to the link collection of the link holder.
BarItemLinkBase class descendants	Adds/inserts a bar item link to the Links collection of a specific link holder (a bar, a menu, etc.).   Attached properties: BarItemLinkActionBase.Target - Allows you to specify the name of the target link holder to which the link is added. The Target property is in effect when the TargetType attached property is not specified, or set to Other. BarItemLinkActionBase.TargetType - Allows you to specify the type of the target link holder to which the link is added. BarItemLinkActionBase.ItemLinkIndex - Allows you to specify the position at which the link is inserted in the target link holder. If this property is omitted, the link is appended to the link holder’s link collection.
AddBarAction	Adds a bar to the BarManager.Bars collection.
AddBarItemAction	Adds a bar item to the BarManager.Items collection.
AddBarItemLinkAction	Adds a bar item link to the link container (a bar, a menu, etc.).
CreateStandardLayoutAction	Creates four BarContainerControls at the four edges of the window, allowing you to dock bars to the window. See the BarManager.CreateStandardLayout topic to learn more.
InsertBarAction	Inserts a bar at a specific position within the BarManager.Bars collection.
InsertBarItemAction	Inserts a bar item at a specific position within the BarManager.Items collection.
InsertBarItemLinkAction	Inserts a bar item link to the item link collection of a target object (a bar, a menu, etc.).
InsertMainMenuIfNotExistAction	Inserts a bar at a specific position within the BarManager.Bars collection and sets the Bar.IsMainMenu flag for it. The action does nothing if a bar already exists with this flag enabled.
InsertStatusBarIfNotExistAction	Inserts a bar at a specific position within the BarManager.Bars collection and sets the Bar.IsStatusBar flag for it. The action does nothing if a bar already exists with this flag enabled.
RemoveBarAction	Removes a bar from the BarManager.Bars collection.
RemoveBarItemAction	Removes a bar item from the BarManager.Items collection.
RemoveBarItemAndLinkAction	Removes a bar item from the BarManager.Items collection, and removes all links to this bar item from link holders (bars, submenus, menus, etc.).
RemoveBarItemLinkAction	Removes a specific link from the bar item link collection of a target object (a bar, a menu, etc.).
SetBarAction	Replaces a bar at a specific position within the BarManager.Bars collection with another bar.
SetBarItemAction	Replaces a bar item at a specific position within the BarManager.Items collection with another bar item.
SetBarItemLinkAction	Replaces a bar item link at a specific position within a target object (a bar, a menu, etc.) with another bar item link.
UpdateAction	Updates a specific bar or ribbon item’s property with a value specified via the UpdateAction.Value.

Actions are typically combined into a BarManagerActionContainer object, and declared within a DataTemplate object in the resources.

Example - Defining Actions

This example shows how to define bar customization actions in a DataTemplate. In the example, various actions are demonstrated: actions used to create bars and bar items, add bar items to the bar and submenus, and remove bar items.

Note

A complete sample project is available at https://github.com/DevExpress-Examples/how-to-define-bar-customization-actions-e1749.

Window1.xaml

<Window.Resources>
    <DataTemplate x:Key="barManagerControllerTemplate1">
        <dxb:BarManagerActionContainer>
            <!--An action that creates four bar containers-->
            <dxb:CreateStandardLayoutAction />
            <!--An action that adds a bar representing the Main Menu-->
            <dxb:InsertMainMenuIfNotExistAction x:Name="barMainMenu">
                <dxb:InsertMainMenuIfNotExistAction.Bar>
                    <dxb:Bar x:Name="MainMenu" Caption="Main menu" UseWholeRow="True">
                        <dxb:Bar.DockInfo>
                            <dxb:BarDockInfo ContainerType="Top" />
                        </dxb:Bar.DockInfo>
                    </dxb:Bar>
                </dxb:InsertMainMenuIfNotExistAction.Bar>
            </dxb:InsertMainMenuIfNotExistAction>
            <!--An action that adds a File submenu to the Main Menu-->
            <dxb:BarSubItem x:Name="menuFile" Content="File" dxb:BarItemLinkActionBase.TargetType="MainMenu" dxb:BarItemLinkActionBase.ItemLinkIndex="0" />
            <!--An action that adds a New button to the File submenu-->
            <dxb:BarButtonItem x:Name="btnNew" Content="New" dxb:BarItemLinkActionBase.Target="menuFile" />
            <!--An action that adds a Save button to the File submenu-->
            <dxb:BarButtonItem x:Name="btnSave" Content="Save" dxb:BarItemLinkActionBase.Target="menuFile" />
            <!--An action that adds an Exit button to the File submenu-->
            <dxb:BarButtonItem x:Name="btnExit" Content="Exit" dxb:BarItemLinkActionBase.Target="menuFile" />
            <!--An action that inserts an Open button in the File submenu at position 1-->
            <dxb:BarButtonItem x:Name="btnOpen" Content="Open" dxb:BarItemLinkActionBase.ItemLinkIndex="1" dxb:BarItemLinkActionBase.Target="menuFile" />

            <!--An action that adds a Help submenu to the Main Menu-->
            <dxb:BarSubItem x:Name="menuHelp" Content="Help" dxb:BarItemLinkActionBase.TargetType="MainMenu" />
            <!--An action that adds an About button to the Help submenu-->
            <dxb:BarButtonItem x:Name="btnAbout" Content="About" dxb:BarItemLinkActionBase.Target="menuHelp" />
        </dxb:BarManagerActionContainer>
    </DataTemplate>

    <DataTemplate x:Key="barManagerControllerTemplate2">
        <dxb:BarManagerActionContainer>
            <!--An action that removes a "menuHelp" button and all its links-->
            <dxb:RemoveBarItemAndLinkAction ItemName="menuHelp" />
            <!--An action that removes a "btnExit" button and all its links-->
            <dxb:RemoveBarItemAndLinkAction ItemName="btnExit" />
        </dxb:BarManagerActionContainer>
    </DataTemplate>

</Window.Resources>

Executing Actions

To apply actions stored in a BarManagerActionContainer object declared within a DataTemplate to a BarManager, add a TemplatedBarManagerController object to the BarManager.Controllers collection. Set the TemplatedBarManagerController.Template property so that it refers to the defined DataTemplate. An example is shown below.

Example - Executing Actions

Note

A complete sample project is available at https://github.com/DevExpress-Examples/how-to-define-bar-customization-actions-e1749.

Window1.xaml

<dxb:BarManager Name="barManager1" CreateStandardLayout="True">
    <!--Apply the actions defined by the BarManagerActionContainer within the local resources-->
    <dxb:BarManager.Controllers>
        <!--Execute the actions before the bar structure of the BarManager object is initialized-->
        <dxb:TemplatedBarManagerController Template="{StaticResource barManagerControllerTemplate1}" />
        <!--Execute the actions after the bar structure of the BarManager object is initialized-->
        <dxb:TemplatedBarManagerController Template="{StaticResource barManagerControllerTemplate2}" />
    </dxb:BarManager.Controllers>