BUTTONS_BEGIN – BUTTONS_END

  • Article

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

The BUTTONS_BEGIN – BUTTONS_END section contains entries that describe the commands that a VSPackage has implemented.

The Command Button

A command, whether a toolbar button, menu item, or a split drop-down list box, is considered a button by Visual Studio.

All commands are defined in the BUTTONS_BEGIN - BUTTONS_END section. A command has up to twelve fields that control the definition of that command. A comma separates all fields and a semicolon denotes the end of each entry. For example:

Command ID, Group ID, Priority, Icon ID, Button Type, Flags, Button Text, Menu Text, ToolTip Text, Command Well Text, English Command Name, Localized Command Name;

These fields are described in the following table and must appear in the order given. The last field must end with a semicolon. See "The Command Fields" section later in this topic for more details on each field.

Field Name

Description

Command ID

A GUID:ID pair that identifies this command.

Group ID

A GUID:ID pair that identifies the group this command belongs to.

Priority

A value used to position this command relative to other commands in the same group.

Icon ID

A GUID:ID pair that identifies the icon to use.

Button Type

A constant that specifies the type of command.

Flags

A collection of flags that apply additional attributes to the command.

Button Text

The text that appears on a button on a toolbar or as the menu text on a menu if the Menu Text field is not specified.

Menu Text

The text that appears in a drop-down or context menu. This field is optional. If this field is not specified, the Button Text field is used.

ToolTip Text

The text that appears when the cursor is held over the command, when the command is placed on a toolbar. This field is optional. If this field is not specified, the Button Text field is used.

Command Well Text

The text that is used in the menu and toolbar customization display that describes the command. This field is optional; if not specified, the Button Text field is used.

English Command Name

The name of the command in English. This field is optional. If this field is not specified, the Button Text field is converted to a canonical form (for example, "&My Menu Item" becomes "MyMenuItem"). This field specifies the command name to be used from the Command Window.

Localized Command Name

The name of the command in the local language. This field is optional. If this field is not specified, the Button Text field is converted to a canonical form (for example, "&My Menu Item" becomes "MyMenuItem"). This field specifies the command name to be used from the Command Window.

Commands Example

The following example shows part of the BUTTONS_BEGIN – BUTTONS_END section from the File Explorer sample. Buttons are contained in groups. The group format is described in the NEWGROUPS_BEGIN – NEWGROUPS_END section. Entries in this example are indented for readability. In a typical implementation, each command entry would be placed on a single line and all of the fields would be lined up in columns.

The first button entry has been expanded from the one in the File Explorer sample in order to show all possible parameters. For additional information, see CMDS_SECTION – CMDS_END.

BUTTONS_BEGIN
// Buttons
    guidEUCmd:cmdidFileSysTool,                 // Command ID
          guidSHLMainMenu:IDG_VS_WNDO_WINDOWS2, // Group ID
          0xFF00,                               // Priority
          guidEUGrp:bmpidFileSysTool,           // Icon ID
          BUTTON,                               // Button Type
          0,                                    // Flags
          "&File System Browser",               // Command Text
          "&File System Browser",               // Menu Text
          "File System Browser",                // ToolTip Text
          "File System Browser",                // Command Well Text
          "FileSystemBrowser",                  // English Command Name
          "FileSystemBrowser";                  // Localized Command Name

// File Pane Commands
    guidEUCmd:cmdidFilesOpenFile,
        guidEUGrp:IDG_FILEPANE_COMMANDS,
        0x0010,  guidEUGrp:bmpidOpenFile,  BUTTON,
        DEFAULTDISABLED,
        "&Open";

// File Pane Arrange Cascading Menu Commands
    guidEUCmd:cmdidFilesSortName,
        guidEUGrp:IDG_FILEPANE_SORT,
        0x0010,  guidOfficeIcon:msotcidNoIcon,  BUTTON,
        0,
        "by &Name";
    guidEUCmd:cmdidFilesSortExtension,
        guidEUGrp:IDG_FILEPANE_SORT,
        0x0011,  guidOfficeIcon:msotcidNoIcon,  BUTTON,
        0,
        "by &Extension";

// Folder Pane Commands
    guidEUCmd:cmdidFolderView,
        guidEUGrp:IDG_FOLDERPANE_VIEW,
        0x0010,  guidEUGrp:bmpidFolderView,  BUTTON,
        0,
        "Folders";
    guidEUCmd:cmdidShortcutView,
        guidEUGrp:IDG_FOLDERPANE_VIEW,
        0x0011,  guidEUGrp:bmpidShortcutView,  BUTTON,
        0,
        "Shortcuts";
    guidEUCmd:cmdidAddShortcut,
        guidEUGrp:IDG_FOLDERCTX_SHORTCUT,
        0x0010,  guidEUGrp:bmpidAddShortcut,  BUTTON,
        DYNAMICVISIBILITY | DEFAULTINVISIBLE | DEFAULTDISABLED,
        "&Add Shortcut";

// Cascading menu commands
    guidEUCmd:cmdidDefineCommands,
        guidEUGrp:IDG_COMMANDS_DEFINE,
        0x0010,  guidOfficeIcon:msotcidNoIcon,  BUTTON,
        0,
        "&Define Commands...";
BUTTONS_END

The Command Fields

Each entry in the BUTTONS_BEGIN – BUTTONS_END section contains up to twelve fields, which are described here.

  • Command ID

    The Command ID field identifies the new command you are creating. The Command ID is always a GUID:ID pair and uniquely identifies the command. The ID must be different from the ID associated with any other command, menu, or group with the same GUID.

    Some of the Command ID fields in the code example are:

    guidEUCmd:cmdidFileSysTool
guidEUCmd:cmdidFilesOpenFile
guidEUCmd:cmdidFilesSortName
guidEUCmd:cmdidFilesSortExtension
guidEUCmd:cmdidFolderView

  • Group ID

    The Group ID field identifies the primary group to which the command belongs as a GUID:ID pair. This field cannot be left blank.

    Some of the Group ID parameters in the code example are:

    guidSHLMainMenu:IDG_VS_WNDO_WINDOWS2
guidEUGrp:IDG_FILEPANE_COMMANDS
guidEUGrp:IDG_FILEPANE_SORT
guidEUGrp:IDG_FILEPANE_SORT
guidEUGrp:IDG_FOLDERPANE_VIEW

    To create a command without a primary group, it should either be self-hosted, that is using its own Command ID as its parent group, for instance:

    guidEUCmd:cmdidFileSysTool, guidEUCmd:cmdidFileSysTool, ...

    or use the button's GUID and an ID of 0:

    guidEUCmd:cmdidFileSysTool, guidEUCmd:0, ...

    If a command does not have a primary group, it must be placed on a menu or toolbar with an entry in the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section; otherwise, it does not appear in the environment.

  • Priority

    The Priority field specifies the placement of the command within the specified group relative to the other items in the group. Items with a lower priority value appear before items with a larger priority value. This field cannot be left blank.

    Some of the Priority fields in the example are:

    0x0010
0x0011

    When a command's placement is defined in the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section, the priority value specified here is ignored in favor of that specified by the entry in the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section.

    If two commands have the same priority, the command that is defined first appears before the other in the group.

  • Icon ID

    The Icon ID field specifies an identifier for the icon that is associated with the command using a GUID:ID pair. This field cannot be left blank.

    A standard set of bitmaps is provided and is accessed when a GUID of GuidOfficeIcon is used. In this case, the environment searches Visual Studio SDK resource files for the corresponding icon identifier. These identifiers are defined in the Msobtnid.h header file in the \Program Files\VSIP\EnvSDK\common\inc\office10 folder.

    If your command does not need an icon, specify guidOfficeIcon:msotcidNoIcon.

    The Visual Studio SDK allows the creation of custom icons through a project's resource file. These must be added to a project using the BITMAPS_BEGIN – BITMAPS_END section of the .ctc file.

    For further information on how to create custom bitmap icon resources and include them in a project, see BITMAPS_BEGIN – BITMAPS_END. In Visual Studio 2005 SDK, bitmap resources may be located in managed packages. See Resources in Managed VSPackages for details.

    Some of the Icon ID fields in the code example are:

    guidEUGrp:bmpidFileSysTool
guidEUGrp:bmpidOpenFile
guidOfficeIcon:msotcidNoIcon
guidEUGrp:bmpidFolderView
guidEUGrp:bmpidShortcutView

  • Button Type

    The Button Type field is case-insensitive and specifies the type of command that is being implemented. If the Button Type field is left blank, the type defaults to Button. While all commands in the example are of the type Button, the Command Table supports four types of commands as detailed in the following table:

    Button type

    Description

    Button

    A standard command that appears on toolbars (typically as an iconic button), menus, and context menus.

    MenuButton

    A menu item that does not execute a command, but produces another menu.

    SplitDropDown

    Controls, such as the Undo/Redo buttons on the standard toolbar in Microsoft Word.

    Swatch

    Controls that display color choices, such as a font color dialog box. Requires the implementation of some underlying interfaces.

  • Flags

    The Flags field is case-insensitive and specifies attributes that you can place on a command button. If the Flags field is left blank, the command is, by default, enabled and visible. Multiple flags can be specified by using the | (OR) operator; for example, NoKeyCustomize | NoButtonCustomize. The following table lists the flags that Visual Studio supports.

    Flag

    Description

    NoKeyCustomize

    Do not allow keyboard customization.

    NoButtonCustomize

    Do not allow the user to customize this button.

    NoCustomize

    A combination of both the NoKeyCustomize and NoButtonCustomize flags.

    Pict

    Show only an icon on a toolbar, but only text on a menu. If no icon is specified, shows a selectable blank space on a toolbar.

    TextOnly

    Show only text on a toolbar or a menu but no icon even if the icon is specified.

    IconAndText

    Show an icon and text on menu and toolbar.

    TextContextUseButton

    Use the Button Text field on context menus. The default is the Menu Text field if specified.

    TextMenuUseButton

    Use the Command Text field for menus. The default is the Menu Text field if specified.

    TextMenuCtrlUseMenu

    Use the Menu Text field on menu controllers. The default is the Command Text field.

    TextCascadeUseButton

    Use the Command Text field on a cascade menu. The default is the Menu Text field if specified.

    TextChanges

    The command's text can be changed at runtime, typically through the QueryStatus method.

    DefaultDisabled

    By default, the command is disabled if the VSPackage that implements the command is not loaded or the QueryStatus method has not been called.

    DefaultInvisible

    By default, the command is invisible if the VSPackage that implements the command is not loaded or the QueryStatus method has not been called.

    This should be combined with the DynamicVisibility flag.

    DynamicVisibility

    The command's visibility can be changed through the QueryStatus method or through a context GUID placed in the VISIBILITY_SECTION – VISIBILITY_END section.

    This applies to commands that appear on menus, not on toolbars. Top-level toolbar items can be disabled but not hidden, when the OLECMDF_INVISIBLE flag is returned from the QueryStatus method.

    This flag should be combined with the DefaultInvisible flag.

    DynamicItemStart

    Indicates the beginning of a dynamic list. This allows the environment to build a list by successively calling the QueryStatus method on list items until the OLECMDERR_E_UNSUPPORTED flag is returned. This works well for items such as most recently used (MRU) lists and window lists.

    CommandWellOnly

    Apply this flag if the command does not appear on the top-level menu and you would like to make it available for additional shell customization, for instance, binding it to a key. After the VSPackage is installed you may customize these commands by opening the Options dialog box from the Tools menu and editing the command placement under the Keyboard Environment category. This flag does not affect placement on context menus, toolbars, menu controllers, or cascade menus.

    AllowParams

    Indicates that the user can enter command parameters in the command window when typing the command's canonical name.

    PostExec

    Makes the command non-blocking. The environment defers execution until all pre-processing queries are complete.

    DontCache

    The environment does not cache the QueryStatus method results for this command.

    FixMenuController

    If this command is placed on a menu controller, the command is always the default, that is, the command is always selected whenever the menu controller button itself is selected. If the menu controller has the TextIsAnchorCommand flag set, then the menu controller also takes its text from the command with the FixMenuController flag. See the MENUS_BEGIN – MENUS_END section for more details on the TextIsAnchorCommand flag.

    There should be only one command on a menu controller that is marked with the FixMenuController flag. If there is more than one command so marked, the last command in the menu becomes the default command.

    NoShowOnMenuController

    If this command is placed on a menu controller, the command does not appear in the drop-down list.

    RouteToDocs

    The command is routed to the active document.

    The Flags fields in the example are:

    DYNAMICVISIBILITY
DEFAULTINVISIBLE
DEFAULTDISABLED
DEFAULTDISABLED
0

  • Button Text

    This field and the five following text fields in a command definition let you specify the text that appears in various menus. The Button Text field appears, by default, in menu controllers. The Button Text field also becomes the default if the other text fields are left blank. The Button Text field cannot be left blank even if the other text fields are specified.

    An ampersand within the text string specifies the keyboard shortcut for the command. Some of the Button Text fields in the example are:

    "&Open"
"by &Name"
"by &Extension"
"&Define Commands..."

  • Menu Text

    The Menu Text field specifies the text displayed for a command if it is in a toolbar, in a context menu, or in a cascade menu. If the Menu Text field is left blank, the environment uses the Button Text field. The Menu Text field can also be used for localization. In the example above, the Menu Text field is not specified, so the Button Text field becomes the default.

  • ToolTip Text

    The ToolTip Text field specifies the text that appears in the ToolTip for a menu item. If the ToolTip Text field is left blank, the Button Text field is used. In the example, the ToolTip Text field is not used, so the ToolTip text defaults to the Button Text field.

  • Command Well Text

    The Command Well TExt field specifies the text that appears in the keyboard category in the Options dialog box (available by selecting Options from the Tools menu) and the Commands list in the Customize dialog box (available by selecting Customize from the Tools menu). In the example, the Command Well Text field is not used, so the Command Well Text defaults to the Button Text field.

  • English Command Name

    The English Command Name field specifies the name of the command in English text that can be entered in the Command Window to execute the menu item. The environment strips out any characters that are not letters, digits, underscores, or embedded periods. This text is then concatenated to the menu's Button Text field to define the command. For example, New Project from the File menu becomes the command, File.NewProject.

    If the English Command Name field is not specified, the environment uses the Button Text field, stripping out all but letters, digits, underscores, and embedded periods. For example, the Button Text "&Define Commands..." becomes DefineCommands, where the ampersand, the space, and the ellipsis are removed.

    If the TextChanges flag is specified and the text of the command is changed, the corresponding command recognized by the Command Window does not change; it remains the canonical form of the original Button Text or English Command Name fields. In the example command set at the beginning of this topic, the English Command Name version of the command guidEUCmd:cmdidFile is FileSystemBrowser.

  • Localized Command Name

    The Localized Command Name field behaves identically to the English Command Name field but allows localized command text to be specified. Both canonical fields can be specified. Because the environment simply parses text entered in the command window and associates it with a command, both English and non-English text can be associated with the same command.

See Also

Concepts

How VSPackages Add User Interface Elements to the IDE