Registering Menus and Commands - kaisu1986/ATF GitHub Wiki

The CommandService component handles creating menus and registering commands, which makes them available for use in menus and tool strips. After registration, you create command clients for the commands you have just registered to specify what the commands actually do. For details, see Creating Command Clients.

CommandService implements ICommandService, which provides methods to create menus and register commands. ICommandService is different for WinForms and WPF, though both offer similar capabilities.

If you use one of ATF's components for standard commands, as described in Using Standard Command Components, these standard commands are already registered for you. You only need to register your custom commands.

You don't need to create most menus, because CommandService creates a standard set of menus in the StandardMenus class for both WinForms and WPF:

• File
• Edit
• View
• Modify
• Format
• Window
• Help

Menus are created with the ICommandService.RegisterMenu() method:

void RegisterMenu(MenuInfo info);

The constructor for MenuInfo simply requires a tag and text for the UI and description:

public MenuInfo(
    object menuTag,
    string menuText,
    string description);

The menuTag parameter is one of the StandardMenu enumerations.

For example, the standard File menu is created in ATF by first creating a MenuInfo in the MenuInfo class:

public static MenuInfo File =
    new MenuInfo(StandardMenu.File, "File".Localize(), "File Commands".Localize());

and then registering the menu using that MenuInfo object in CommandService (which derives from CommandServiceBase and that implements ICommandService, so the RegisterMenu() method is available):

RegisterMenu(StandardMenus.File);

You can create custom menus similarly, using the application's CommandService object.

Menus are created with the ICommandService.RegisterMenu() method:

void RegisterMenu(MenuDef definition);

The constructor for MenuDef, similarly to MenuInfo, simply requires a tag and text for the UI and description:

public MenuDef(object menuTag, string text, string description);

The menuTag parameter is one of the StandardMenu enumerations.

For example, the standard File menu is created in ATF by first creating a MenuDef in the StandardMenus class:

public static MenuDef File =
    new MenuDef(StandardMenu.File, Localizer.Localize("_File"), Localizer.Localize("File Commands"));

and then registering the menu using that MenuDef object in CommandService, which implements ICommandService so the RegisterMenu() method is available:

RegisterMenu(StandardMenus.File);

You can create custom menus similarly, using the application's CommandService object.

You need to provide two objects (or equivalent information) to register a command:

• CommandInfo or CommandDef: Describe the command's interaction with the UI, as described in CommandInfo and CommandDef Classes.
• ICommandClient: Tell what the command does. To learn more about this, see Creating Command Clients.

The order in which RegisterCommand() is called in your application determines the order in which commands and groups of commands appear in menus and tool strips.

The simplest registration method is this:

void RegisterCommand(CommandInfo info, ICommandClient client);

This line from StandardEditCommands registers the EditCut command:

m_commandService.RegisterCommand(CommandInfo.EditCut, this);

CommandInfo.EditCut was already created in the CommandInfo class. m_commandService is an ICommandService instance.

StandardEditCommands not only registers this command, but provides an implementation, because it implements ICommandClient. In the line above, this specifies the required ICommandClient parameter.

This longer call in the SourceControlCommands component specifies all the command info parameters for the Enabled command:

m_sourceControlEnableCmd = m_commandService.RegisterCommand(
    Command.Enabled,
    StandardMenu.File,
    SourceControlCommandGroup.OnOff,
    "Source Control/Enable".Localize(),
    "Enable source control".Localize(),
    Keys.None,
    Resources.SourceControlEnableImage,
    CommandVisibility.Menu | CommandVisibility.Toolbar,
    this);

This registration specifies the command visibility explicitly. This component also provides the ICommandClient for the command.

The simplest registration method is this:

ICommandItem RegisterCommand(CommandDef definition, ICommandClient client);

ICommandItem is an interface for command items, which provides properties to get the various pieces of information in a CommandDef object.

This call in the WPF HelpCommands component registers 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);

This registration specifies the command visibility explicitly. This component also provides the ICommandClient for the command.