MENUS_BEGIN – MENUS_END

  • Article

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

The MENUS_BEGIN – MENUS_END section contains an entry for each menu that a VSPackage implements.

The Menu Entry

A menu in a .ctc file is a container for groups. A group is a container for commands, and also for other menus.

A menu is defined in an entry in the MENUS_BEGIN - MENUS_END section of a .ctc file. A menu entry has six fields, which are separated by commas. The menu entry ends with a semicolon. The following is an example of a menu entry.

Menu ID, Group ID, Priority, Type, Menu Name, Menu Text;

The menu entry fields are described in the following table. The fields must appear in the order given. The last field must end with a semicolon.

Field

Description

Menu ID

A GUID:ID pair identifying this menu.

Group ID

A GUID:ID pair identifying the parent group.

Priority

A value that is used to position this menu relative to other menus in the same group.

Type

A combination of flags that describe the type of menu and its behavior.

Menu Name

The name of the menu.

Menu Text

This is the text that the user clicks on to open the menu. This field is also the name of a toolbar that appears in the Toolbars submenu of the View menu. This field is also the name of the shortcut menu that appears in the Shortcut Menus toolbar during customization.

This field is optional; if not specified, the Menu Name field is used.

For more information, see "The Menu Entry Fields" section later in this topic.

The following code example from the File Explorer sample shows a MENUS_BEGIN – MENUS_END section. This example defines toolbars, shortcut menus, and a cascading menu. These menus are containers for groups that are defined in the NEWGROUPS_BEGIN – NEWGROUPS_END section.

Note

Entries in this example are indented for readability. In an actual entry, all fields should be on a single line. For more information, see How VSPackages Add User Interface Elements to the IDE and CMDS_SECTION – CMDS_END.

MENUS_BEGIN
// Toolbars                            
    guidEUGrp:IDM_TLB_FILESYSFOLDER,
        guidEUGrp:IDM_TLB_FILESYSFOLDER,
        0x0000,  TOOLWINDOWTOOLBAR,
        "File System Browser Folders",  "Folders";
    guidEUGrp:IDM_TLB_FILESYSFILE,
        guidEUGrp:IDM_TLB_FILESYSFILE,
        0x0000,  TOOLWINDOWTOOLBAR,
        "File System Browser Files",  "Files";
// Shortcut menus
    guidEUGrp:IDM_CTX_FILESYSFOLDER,
        guidEUGrp:0,
        0x0000,     CONTEXT,
        "FileSysFolder Context",  "FoldersContext";
    guidEUGrp:IDM_CTX_FILESYSFILE,
        guidEUGrp:0,
        0x0000,  CONTEXT,
        "FileSysFile Context",  "FilesContext";
    guidEUGrp:IDM_CTX_CMDMACRO,
        guidEUGrp:0,
        0x0000,  CONTEXT,
        "Command Macro Context",  "CommandMacro";
// Sort Cascading menu
    guidEUGrp:IDM_MNU_FILESYSFILE_SORT,
        guidEUGrp:IDG_FILEPANECTX_ARRANGE,
        0x0000,  ,
        "Arrange Files",  "&Arrange Files";
// Commands Cascading menu
    guidEUGrp:IDM_MNU_FILESYS_COMMANDS,
        guidEUGrp:IDG_FILESYSCTX_COMMANDS,
        0x0000,  ,
        "Commands",  "&Commands";
MENUS_END

The Menu Entry Fields

Each entry in the MENUS_BEGIN – MENUS_END section has six fields. The fields must be separated by a comma and the entry must end with a semicolon. The fields, in order, are as follows:

  • Menu ID

    The Menu ID field identifies the menu. The Menu ID field is always a GUID:ID pair. In the example, the first Menu ID definition is

    guidEUGrp:IDM_TLB_FILESYSFOLDER

  • Group ID

    The Group ID field identifies the parent group of the menu. Except for toolbars and shortcut menus, all menus should have a parent group that is specified either in the menu entry or in the command placement section. In the example, the first Group ID toolbar definition is

    guidEUGrp:IDM_TLB_FILESYSFOLDER

    Toolbars and shortcut menus do not have parent groups. Therefore, the parent group is ignored in the .ctc file for these kinds of menus. By convention, the parent group of a toolbar is set to the same GUID:ID pair that is specified in the Menu ID field, for example,

    guidEUGrp:IDM_TLB_FILESYSFOLDER, guidEUGrp:IDM_TLB_FILESYSFOLDER , ...

    By convention, context menus use the menu GUID and an ID of 0 as the parent group, for example,

    guidEUGrp:IDM_CTX_FILESYSFOLDER, guidEUGrp:0, ...

    For menus of type MENU, MenuController, and MenuControllerLatched, if a primary group is not specified, then the menu entry must have an entry in the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section or it will not appear in the Visual Studio integrated development environment (IDE).

  • Priority

    The Priority field determines the relative position of a menu in its parent container. Items that have lower numbers appear before those that have higher numbers. When you add menus to existing groups, specify a priority that will put your command or menu in a position that maintains a consistent user experience. For example, if you add a button to the main toolbar, set the priority so that the button will appear to the left of the Help button.

    Because the File Explorer sample is implemented in a tool window, its toolbars are not contained in another menu. Therefore, their Priority fields are 0x0000.

    When a parent group of a menu is defined by command placement, the Priority field in the menu entry is ignored in favor of the Priority field that is specified in the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section.

  • Type

    The Type field specifies the kind of menu that is created. The values are not case-sensitive. Type can be combined with other flags. For more information, see the "Type Flags" section in this topic.

    The following table lists the possible values for the Type field. If you leave the Type field empty (Default), the result is a standard menu.

    Menu type

    Description

    (Default)

    Provides a drop-down menu that has the following characteristics:

    • Is specified by leaving the type argument blank in a menu declaration.

    • Respects the Group ID field in its definition.

    • Must have a parent group that is defined either in the Group ID field or the command placement section.

    • Can be a submenu in any other menu.

    • Is automatically made visible by the IDE whenever the parent menu of a menu is visible.

    • Does not require the implementation of any VSPackage code to make it visible.

    Toolbar

    Provides a standard toolbar in the IDE that has the following characteristics:

    • Ignores the Group ID field in its definition.

    • Cannot be made a submenu of any group, not even by using command placement.

    • Is always available on the Toolbars menu in the IDE.

    • Can be made visible and a default part of the user's IDE environment by setting flags. For more information, see the "Type Flags" section in this topic.

    • Is automatically made available by the IDE.

    • Does not require the implementation of any VSPackage code to make it visible.

    ToolWindowToolbar

    Provides a toolbar that is attached to a specific tool window and has the following characteristics:

    • Ignores the Group ID field in its definition.

    • Cannot be made a submenu of any group, not even by using command placement.

    • Is not automatically made available by the IDE.

    • Is only visible when its host tool window is visible and the VSPackage explicitly adds the toolbar to the tool window.

      This is typically done when the tool window is created by obtaining the toolbar host property (as represented by the IVsToolWindowToolbarHost interface) from the tool window frame and then calling the AddToolbar method.

    Context

    Provides a menu that can be shown when a user right-clicks on a window. A Context menu has the following characteristics:

    • Does not use the Group ID and Priority fields when the menu is displayed as a shortcut menu.

    • Can be used as a submenu or a shortcut menu. In this case, both Group ID and Priority fields are respected.

    • Is not automatically made available by the IDE as a shortcut menu.

    • Is only visible as a shortcut menu when the following conditions are true:

      1. The window that hosts it is visible.

      2. A VSPackage's mouse handler detects a right-click on the window and calls an implementing method.

        This shortcut menu is displayed by using a call to either the ShowContextMenu method in the IOleComponentUIManager interface (the preferred approach), or the ShowContextMenu method in the IVsUIShell interface.

    MenuController

    Provides a split-button menu, which is typically used in toolbars. A MenuController menu has the following characteristics:

    • Must be contained in another menu by using a group or command placement.

    • Respects the Group ID field in its definition.

    • Can have any kind of menu as its parent.

    • Is automatically made available by the IDE whenever its parent menu is visible.

    • Does not require programmatic support to make the menu visible.

    • A command name is always displayed on the menu button. The displayed command is one of the following:

      1. The last command that was selected, if the command is still visible and enabled.

      2. The first visible command.

    MenuControllerLatched

    Provides a split-button menu in which a default selection can be specified by marking the command as latched. A MenuControllerLatched menu has the following characteristics:

    • Must be contained in another menu by using a group or command placement.

    • Respects the Group ID field in its definition.

    • Can have any kind of menu as its parent.

    • Is automatically made available by the IDE whenever its parent menu is visible.

    • Does not require programmatic support to make the menu visible.

    • A command name is displayed on the menu button. The displayed command is one of the following:

      1. The first visible command that is latched.

      2. The first visible command.

      A latched command is command that is marked in the menu as having been selected, typically by displaying a check mark. A command can be marked as latched if it has the OLECMDF_LATCHED flag set on it in an implementation of the QueryStatus method of the IOleCommandTarget interface.

      NoteNote
      In managed code that uses the managed package framework (MPF), the MenuCommand class offers the Checked property, which sets or clears the latched status of the command.

    The first Type definition in the example is the following.

    ToolWindowToolbar

  • Type Flags

    Type Flags are actually part of the Type field. The following table shows the flags that can be combined with the Type values by using the | (OR) operator, for example, Toolbar | DefaultDocked.

    Flag

    Description

    AlwaysCreate

    Menu is created even if it has no groups or buttons.

    DefaultDocked

    By default, docked to the IDE. This is valid only for Toolbar menu types.

    DefaultInvisible

    The menu is hidden until the VSPackage that implements the menu is loaded. This flag is typically assigned to submenus.

    This flag should be combined with the DynamicVisibility flag.

    DontCache

    Tells a menu controller not to cache the text of its menu items. Use this flag when the menu contains dynamic items or items that have dynamic text.

    DynamicVisibility

    The visibility of a menu is dynamic and can be changed by by using an entry in the VISIBILITY_SECTION – VISIBILITY_END section of the .ctc file. The VSPackage that implements the menu does not have to be loaded.

    This flag also indicates that the menu is automatically hidden when all its members are hidden. This flag is typically assigned to submenus because top-level menus already have this behavior.

    This flag should be combined with the DefaultInvisible flag.

    NoCustomize

    Users cannot rename any items on the menu or change the order in which they appear. This is valid only for Context menu types.

    Shortcut menus can be customized by selecting Shortcut Menus in the list of toolbars in the Customize dialog box. Doing this displays a toolbar that has all available shortcut menus. If a shortcut menu is marked by the NoCustomize flag, it can be viewed on the Shortcut Menus toolbar, but it cannot be changed.

    NoteNote
    Tool window toolbars can never be customized.

    NotInTBList

    Does not appear in the list of available toolbars. This is valid only for Toolbar menu types.

    NoToolBarClose

    User cannot close the toolbar. This is valid only for Toolbar menu types.

    TextChanges

    Menu has dynamic text. This affects the text that the user can click.

    TextIsAnchorCommand

    For a menu controller, the text of the menu is taken from the anchor command. An anchor command is the last command that was selected or latched. If this flag is not set, the menu controller uses its own Menu Text field. However, clicking the menu controller still runs the last selected command from that controller.

    This flag should be combined with the TextChanges flag.

    This flag applies only to menus of type MenuController or MenuControllerLatched.

    Notice that none of the menu entries in the example use the Type Flags.

  • Menu Name

    The Menu Name field specifies the name of the menu. This name appears as an item in the Customize dialog box. The IDE also uses the Menu Name together with the Button Text of the commands that appear in the menu. This enables the use of menu commands from the Command Window, for example, File.FileNew. The IDE converts the Menu Name field to a canonical form, and strips out all characters except letters, digits, underscores, and embedded periods. The first Menu Name field toolbar definition in the example is the following.

    File System Browser Folders

    This is converted to the following command name.

    FileSystemBrowserFolders

  • Menu Text

    The Menu Text field contains the text that is displayed when the item is a menu on the main menu bar or is a submenu. The Menu Text field also serves as the localization text for a menu item.

    For shortcut menus, the Menu Text field is the name that is displayed in the Shortcut Menus toolbar that enables customization of shortcut menus in the IDE. Therefore, be specific in how you name your shortcut menu, for example, use "Widget Package Shortcut Menu" instead of "Shortcut".

    If the Menu Text field is not specified, the Menu Name field is used.

    The Menu Text field in the first toolbar definition is the following.

    Folders

See Also

Concepts

How VSPackages Add User Interface Elements to the IDE

CMDS_SECTION – CMDS_END

NEWGROUPS_BEGIN – NEWGROUPS_END

Other Resources

File Explorer