How to: Create Toolbars for Tool Windows

  • [アーティクル]

注意

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 XML-Based Command Table Configuration (.vsct) Files.

A VSPackage can create a toolbar on a tool window by defining a .ctc menu entry with a type of ToolWindowToolbar (see the MENUS_BEGIN – MENUS_END section for details on this type of menu).

Toolbars (defined with the flag Toolbar) in the integrated development environment (IDE) and toolbars in tool windows have a few notable differences:

  • Toolbars in tool windows must be explicitly and programmatically created within the target tool window.

  • The tool window toolbar is not configurable under the IDE's Customize dialog box.

The Walkthrough: Adding a Toolbar to a Tool Window walkthrough shows how to create a toolbar in a tool window in both managed (Visual C#) and unmanaged (Visual C++) code.

To create a tool window toolbar

  1. Select a GUID:IDpair to represent the new menu command. 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 pair definition continues with a colon and finally a unique number. In a typical VSPackage, a single GUID is created for all commands, menus, and toolbars. Since all such elements are identified by a GUID:ID pair, all of the commands, menus and toolbars are distinguished from each other by the ID portion of the GUID:ID pair.

  2. Create a new line in the MENUS_BEGIN – MENUS_END section of the Command Table Configuration (.Ctc) Files. For more information, see the MENUS_BEGIN – MENUS_END section.

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

    2. Set the Group ID field to the same GUID:ID pair as the Menu ID field.

      Menus of type ToolWindowToolbar are programmatically placed on the tool window, and the Group ID field is always ignored.

      By convention, the toolbar's GUID:ID pair specified in the Menu ID field is also used in the Group ID field.

      注意

      Tool window toolbars can not be used as submenus of other menus.

    3. Set the Priority field to 0.

      Tool window toolbars do not use the Priority field and this value is therefore ignored. By convention, the Priority field is set to 0 when it is not used.

    4. Set the Type field to ToolWindowToolbar. As appropriate, add the following flags to the Type field, using the | (logical OR) operator:

      AlwaysCreate – the toolbar is created even if it contains no commands. Normally, at least one visible command must appear on a tool window toolbar for the toolbar to be made visible.

      TextChanges – the toolbar has dynamic text (ToolTips.)

    5. Set the Menu Name field to the name of the menu object, enclosed in quotes. This field is used as the command name.

    6. Set the Menu Text field to the short name of the menu object. For tool window toolbars, this field is not used and can be left blank.

  3. Add commands to the tool window toolbar. For more information, see How VSPackages Add User Interface Elements. This is done by creating one or more groups (see the NEWGROUPS_BEGIN – NEWGROUPS_END section for details on adding groups). Each group should have as its Menu ID field the GUID:ID pair of the tool window toolbar.

  4. To display the tool window toolbar, the VSPackage must call to the Visual Studio SDK tool window toolbar creation method AddToolbar in the IVsToolWindowToolbarHost interface. The AddToolbar method is passed the GUID:ID pair of the toolbar to add and the location to dock the toolbar.

    The IVsToolWindowToolbarHost interface is obtained from the VSFPROPID_ToolbarHost property on the tool window frame (typically an IVsWindowFrame interface).

    Typically, the AddToolbar method is executed when the tool window is created. However, a VSPackage can dynamically add a tool window toolbar at other times. A tool window can have multiple toolbars.

    注意

    The managed package framework (MPF) hides the details of adding a toolbar: all that is needed is to set the ToolBar property of the ToolWindowPane class to the GUID:ID pair of the toolbar. This is typically done in the constructor of the class that derives from the ToolWindowPane class. This means that a managed code tool window built from the MPF can have only one toolbar per tool window.

See Also

Concepts

Common Menu Tasks

Designing Command Table Configuration Files

CMDPLACEMENT_SECTION – CMDPLACEMENT_END

How to: Create Reusable Groups of Buttons