CommandInfo and CommandDef Classes - kaisu1986/ATF GitHub Wiki

The CommandInfo and CommandDef classes describe a command's interaction with the UI: its visibility, location, and appearance, as described in Registering Commands. This information is needed to register a command.

CommandInfo offers a variety of constructors, and the following one offers the most options:

public CommandInfo(
    object commandTag,
    object menuTag,
    object groupTag,
    string menuText,
    string description,
    IEnumerable<Keys> shortcuts,
    string imageName,
    CommandVisibility visibility);

The tag parameters identify the command itself, as well as the menu and group the command belongs to. The commandTag parameter can be one of the StandardCommand enums. The menuTag tag is typically one of the StandardMenu enums. Similarly, groupTag is a StandardCommandGroup enum. For details on groups, see ATF Command Groups.

String parameters give the menu item name and a more detailed tool tip description. In the menu item name:

• A forward slash indicates the command is in a submenu of the menu. For example, "Size/Make Heights Equal" creates a "Size" menu with a submenu item "Make Heights Equal".
• The "&" character in the name indicates that the next character is underlined and used as the menu item's accelerator key for this menu item (used with the Alt key), as in standard Windows® menu conventions. For example, "&About" underlines the "A" in "About" and enables Alt+A to be used to choose the "About" menu item.

You can provide an image for the command's tool strip and menu item, typically a member of the Resources class.

The CommandVisibility enum tells where command is visible, as on menus, tool strips, and so on.

This example, from the CommandInfo class, shows instantiating the CommandInfo for the FileSave command:

public static CommandInfo FileSave =
    new CommandInfo(
        StandardCommand.FileSave,
        StandardMenu.File,
        StandardCommandGroup.FileSave,
        "Save".Localize("Save the active file"),
        "Save the active file".Localize(),
        Keys.Control | Keys.S,
        Resources.SaveImage);

The constructor used here differs from the other constructor in that it provides a single Keys object rather than a collection of them for the command shortcut in the second-last parameter. It doesn't specify a CommandVisibility either, which defaults to the command being visible on both a menu and tool strip.

Similarly to CommandInfo, CommandDef has a variety of constructors, and this one has the most parameters:

public CommandDef(
    object commandTag,
    object menuTag,
    object groupTag,
    string text,
    string[] menuPath,
    string description,
    object imageSourceKey,
    InputGesture[] inputGestures,
    CommandVisibility visibility)

The parameters are similar to those of CommandInfo constructors, providing information on the command, the menu and group the command belongs to, command image, and its visibility. It does not provide a keyboard shortcut, but instead provides a more general InputGesture array, for describing input device gestures to execute the command.

This example, from the WPF HelpCommands component, creates a Help command:

var commandItem = m_commandService.RegisterCommand(
    new CommandDef(
    new ContextMenuHelpTag() { Index = i },
    null,
    Groups.Help,
    "Help".Localize(),
    new string[] { "Help".Localize() },
    "Help".Localize(),
    null,
    null,
    Sce.Atf.Applications.CommandVisibility.None), this);