How to: Create Submenus

  • Article

Note

Beginning with Visual Studio 2008 SDK, use XML Command Table (.vsct) files instead of command table configuration (.ctc) files to define how menus and commands appear in your VSPackages. For more information, see Visual Studio Command Table (.Vsct) Files.

A cascading submenu is a menu accessible from a parent menu. The items within the submenu are displayed when the user selects the menu name from the parent menu.

Any normal menu or context menu can be used as a submenu of another menu. This automatically includes any existing submenus as well.

A submenu can be placed in a parent menu by first placing the submenu in a group. Then, do one of the following to place the group in the parent menu:

  • Set group's parent to be the parent menu. Even if you are going to place the submenu in multiple parent menus, you should always set the group's parent to the first parent menu.

  • Use the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section to place the group in the parent menu. This approach is how the same submenu can be placed in multiple parent menus.

All commands, menus, and toolbars are identified by a GUID:ID pair. In a typical VSPackage, a single GUID is created for all commands, menus, and toolbars. Since all such elements are identified by a combination of GUID and ID, all of the commands, menus and toolbars are distinguished from each other by the ID portion of the GUID:ID pair. The ctc.exe compiler expects a GUID data type in this format:

#define guidCmd  { 0xBC8DA515, 0x5743, 0x4FEB, { 0xA9, 0x29, 0x29, 0x38, 0x24, 0x9C, 0xBA, 0x26 } }

The Walkthrough: Adding a Submenu to a Menu (C#) walkthrough shows how to create a cascading submenu in both managed (Visual C#) and unmanaged (Visual C++) code.

To create a cascading sub-menu

  1. Create a new group, which is to contain the submenu, by creating an entry in the NEWGROUPS_BEGIN – NEWGROUPS_END section:

    1. Set the Group ID field to the GUID:ID of the new group.

    2. Set the Menu ID field to the GUID:ID of the parent menu that is to contain the submenu.

      Alternatively, you can set the Menu ID field to the same GUID:ID as in the Group ID field and use an entry in the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section to place this group in the parent menu.

      Note

      It is recommended that the Menu ID field be set with a valid menu ID when creating this sort of a submenu group, even if the submenu is to appear in multiple parent menus. This way, the submenu appears in at least one parent menu if the entries in the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section are removed.

    3. Set the Priority field to an appropriate value.

      Groups with lower priority values appear before groups with higher priority values.

  2. If you are creating a new submenu, create a new entry in the MENUS_BEGIN – MENUS_END section:

    1. Set the Menu ID field to the GUID:ID of the new menu.

    2. Set the Group ID field to the GUID:ID of the group created in step 1.

    3. Set the Priority field to 0.

      If you are going to place multiple menus or commands in the group created in step 1 then set the Priority field to a value other than 0.

    4. Set the Type field to Context or leave the field blank (for a normal menu). No other type of menu can be a submenu.

      , add the following flags to the Type field, using the | (logical OR) operator, as appropriate:

      AlwaysCreate – if you want the submenu to appear even if it contains no commands.

      DefaultInvisible - if you want the submenu to be initially hidden before the VSPackage is loaded. This flag is typically combined with the DynamicVisibility flag.

      DynamicVisibilty - if you want the submenu to automatically be hidden when all its members are hidden. This flag is typically combined with the DefaultInvisible flag. By setting the DynamicVisibility flag, when a submenu is hidden, its parent menu can also be hidden automatically.

      TextChanges– if you want the submenu to have dynamic text. This affects the name of the submenu itself. Typical user interface (UI) guidelines suggest that the names of submenus should not change; therefore, it is recommended that the TextChanges flag not be used.

    5. Set the Menu Name field to the name of the menu.

      The Menu Name field is used when constructing a path to the commands in the submenu for use in the Command Window. See the discussion of the Menu Name field in the MENUS_BEGIN – MENUS_END section for more details.

    6. Set the Menu Text field to the text that is to be displayed as the name of the submenu. This text is what is clicked on to open the submenu.

      You can specify a keyboard shortcut in the Menu Text field by placing an ampersand '&' before an appropriate character. For example, "&Files" allows the user to press Alt+F on the keyboard to open the Files menu when the parent menu is already open.

      Note

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

  3. If you want to use an existing menu as a submenu, create an entry in the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section to place the menu in the appropriate group:

    1. Set the Item ID field to the GUID:ID of the existing menu.

    2. Set the Parent ID field to the GUID:ID of the group created in step 1.

    3. Set the Priority field to an appropriate value.

      This priority value is relative to the priority values of any other elements added to the group created in step 1.

See Also

Concepts

Common Menu Tasks

CMDPLACEMENT_SECTION – CMDPLACEMENT_END

How to: Create and Handle Commands in VSPackages (C#)