Using Commands in ATF

Table of Contents Commands Command Groups Standard and Custom Commands Registering Commands Command Behavior Command Contexts Topics in this section

Commands

A command is an action that is invoked from a menu item or tool strip button. You can create menu items and tool strip buttons and associate them with commands. The command specifies its appearance and behavior in the UI: text, icon, keyboard shortcut, and actual command action.

All standard commands are listed in the enum StandardCommand. You can also create new commands. For details, see Registering Menus and Commands.

Command Groups

Commands are grouped by related functions, both in menus and tool strips. At the top level, menus contain related functions. The Edit menu contains editing commands, for instance. Menu items are also grouped together, separated from other groups by divider lines. For example, File > Save and File > SaveAs are closely related commands, grouped together. ATF provides a set of standard command groups, and you can add custom groups.

Tool strip buttons are grouped by menu; all the Edit commands are in one tool strip and all the File commands in another, for instance.

For details, see ATF Command Groups.

Standard and Custom Commands

You can add both standard and custom commands to your application.

ATF provides components to add commands that are common to many applications. For instance, StandardFileCommands adds the standard File commands New, Open, Save, SaveAs, Save All, and Close. For details, see Using Standard Command Components.

An application can also create custom menus, tool strips, and commands. For more information, see Registering Menus and Commands.

Registering Commands

The CommandService component provides a service to handle commands in menus and tool strips. All commands must be registered with CommandService. CommandService implements ICommandService, which contains methods to register and unregister commands, display context menus, and process keyboard shortcuts.

Note that there is a separate CommandService component for WinForms and WPF. Each implements a different ICommandService as well. Though the components and interfaces differ somewhat, both offer comparable capability, tailored to the platform.

You can register a command with a CommandInfo (WinForms) or CommandDef (WPF) object. The CommandInfo and CommandDef classes provides information about a command: its visibility, location, and appearance. The CommandInfo class also creates CommandInfo objects for common commands, such as the standard File and Edit menu item commands.

Visibility determines whether a command appears in a menu or tool strip, both, or neither. Commands that are not visible can be added to menus or tool strips later on.

Location indicates what group a command is a member of, its order in the group, and where the group is in the menus and tool strips. In addition, menu items can be in submenus.

Appearance specifies what text, tool tips, and icons are associated with the command.

CommandInfo can also specify keyboard shortcuts. Also set up accelerator keys (as in Help >About) by using the "&" character before the designating character in the menu name text. On the other hand, CommandDef can specify an InputGesture, which describes input device gestures.

For more information about CommandInfo and CommandDef, see CommandInfo and CommandDef Classes.

Tool strips can also contain text entry and combo box controls for commands. These controls are registered through CommandService.

To learn how to register commands, see Registering Menus and Commands.

Command Behavior

Define command behavior with the methods in the ICommandClient interface; WinForms and WPF use the same ICommandClient. In addition to performing the command, this interface provides methods to determine whether the command can be performed and to update the CommandState. Command state includes the menu item name and whether the command menu item has a check mark. For instance, the command state's name may switch back and forth between "Group" and "Ungroup", depending on what actions have occurred.

The command client is the client class in which you implement ICommandClient for the command. The command client can be the same class as the one in which you register the command, or some other class. You specify the client when you register the command, although you can switch between different clients at any time.

For details, see Creating Command Clients.

Command Contexts

A command may behave differently depending on what context is active. A context can be a document, editor, palette, or other object in your application.

Your application can define different contexts, each with a different set of data, and each requiring different command behavior. For example, Select All in a text editor is a very different operation from Select All on a drawing canvas. You can switch the command client for a command to the appropriate one for the context. An application can also have different contexts of the same type, for example, multiple open documents.

The command context is used in building context menus. For more information, see Using Context Menus.

The command context changes when a control gains or loses focus. Your application needs to keep track of the current command context, notify the command client when the context has changed, and implement context behavior in your client.

For more information about contexts, see ATF Contexts.

Topics in this section