[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Collapse]WPF Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Common Concepts
 [Expand]MVVM Framework
 [Collapse]Controls and Libraries
   Reporting
  [Expand]Data Grid
  [Collapse]Ribbon, Bars and Menu
   [Expand]Common Features
   [Collapse]Bars
    [Expand]Getting Started
    [Expand]Bar Layout
    [Expand]Populating Bars
     Bar Actions
    [Expand]Runtime Customization
    [Expand]Examples
     Saving and Restoring a Bar Layout
   [Expand]Ribbon
   [Expand]Menus
  [Expand]Charts Suite
  [Expand]Pivot Grid
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Tree List
  [Expand]Gauge Controls
  [Expand]Map Control
  [Expand]Layout Management
  [Expand]Windows Modern UI
  [Expand]Printing-Exporting
  [Expand]Data Editors
  [Expand]Navigation Controls
  [Expand]Spell Checker
  [Expand]Property Grid
  [Expand]PDF Viewer
  [Expand]TreeMap Control
  [Expand]Diagram Control
  [Expand]Windows and Utility Controls
   Dialogs, Notifications and Panels
  [Expand]Scheduler (legacy)
 [Expand]Scaffolding Wizard
 [Expand]Localization
  Redistribution and Deployment
  Get More Help
 [Expand]API Reference
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Reporting
[Expand]Report and Dashboard Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Bar Actions

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.

Expanded 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 Value.

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

Expanded Example - Defining Actions

Show Me

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E1749.

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.



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

Expanded Example - Executing Actions

Show Me

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E1749.

Is this topic helpful?​​​​​​​