DevComponents Knowledge Base

Applies to DotNetBar for Windows Forms 7.2 and later.

Commands in DotNetBar for Windows Forms help you separate the originator of the action like button from the logic that executes the action. They also help you communicate the current program state like Enabled, Text or Checked to any User Interface component that is utilizing the command. This allows multiple and disparate sources to invoke same command logic and it allows command logic to be customized and communicated to different targets.

Commands are based around ICommand interface and specifically the Command object which implements the ICommand interface. Examples of commands are file operations like Save, Open and Print or editing command like Copy, Cut and Paste.

Using Commands you can separate the actual logic that performs the operation from the source that invoked command. You can have multiple sources that invoke same command, and through the Command you can communicate the application state back to the source that uses it.

Most direct way to use Commands is to add Command component to the form from Visual Studio.NET Toolbox, handle its Executed event and assign it to any source you want by setting the Command property on the source like ButtonItem. The advantage of this method is that you can rely on the Visual Studio.NET Design-time features for manipulation of the commands.

Another approach is to define the commands as static members on static class and assign them to the User Interface elements. Advantage of this approach is the ease of access to the command from any form or part of your application.

Commanding Concepts

Command model in DotNetBar consist of 3 main concepts:

• The command (ICommand, Command) is the action to be executed
• The command source (ICommandSource) is the object which invokes the command
• The command manager (CommandManager) is the object which maps command to the command source

Commands

Commands are created by implementing the ICommand interface. The Command object implements the ICommand interface and you can inherit from it to add any custom functionality you need.

Your action associated with the command is placed inside of the Executed event handler. You can use PreviewExecuted event to decide whether to allow the firing of Executed event. Command provides an Execute method that you can call to raise the Executed event programmatically.

Command also provides properties that are propagated to all command sources using the command. This includes Enabled, Text, Checked etc. properties. When you set for example Enabled property, the value is propagated to all command sources that support that property. Sources that do not provide that property are ignored. That way you can simply disable the attached command sources when command cannot be executed. This property propagation applies to all other properties exposed on the Command object.

To set any property that is not explicitly defined on the Command, SetValue method is provided that allows you to set property by name.

Command Sources

Command source is any object that implements ICommandSource interface. BaseItem class and other control in DotNetBar all implement ICommandSource interface and you can implement it on any other object you wish to add command support for.

ICommandSource exposes two properties:

• Command which is command to execute when command source is invoked
• CommandParameter which is a user defined data used to pass information to the handlers implementing the command.

Internally any object that implements the ICommandSource will call the Execute method on the Command assigned to execute the command action as response to some user-generated or other type of event.

Note that some objects that support ICommandSource, like LabelItem or LabelX never execute the command, but rather can reflect the state of the command when you set the Text or Image property on the command itself.

Command Manager

Command Manager as represented by CommandManager object is the glue that binds the Commands and Command Sources. It is used by Command Source to connect source to a Command (through RegisterCommand and UnregisterCommand methods).

Usually you do not need to interact with CommandManager at all unless you are implementing the ICommandSource on your objects.

RibbonPad sample provides demonstration on how to use Commands in a application.