Share via

How to: Create Toolbars for Tool Windows

  • Article

You can add a toolbar to a tool window by defining a menu of type ToolWindowToolbar in a VSPackage .vsct file, and then programming the package to display it.

Toolbars in tool windows differ from toolbars in the general integrated development environment (IDE) in the following ways:

  • An IDE toolbar can be created just by defining a menu of type Toolbar in the .vsct file. A tool window toolbar must be programmatically created in the target tool window.

  • A user can configure an IDE toolbar by using the Customize dialog box. A tool window toolbar cannot be configured in this manner.

Creating a Tool Window Toolbar

A tool window toolbar is first defined as a Menu Element in the .vsct file.

The following procedures assume that you have a VSPackage project in which a tool window is defined in the .vsct file. If you are creating a VSPackage, in the package wizard, select Tool Window to add a .vsct file to the package project and define a tool window.

To create a tool window toolbar

  1. Open the .vsct file in the editor.

  2. Locate the section that is formed by the Symbols Element.

  3. Find the GuidSymbol Element that contains your menus, groups, and commands. By default, it is named guid<ProjectName>CmdSet.

  4. Add an IDSymbol Element for your toolbar, and one for a group to hold your commands, as shown in the following example.

    <IDSymbol name="TWToolbar" value="0x1000" />
<IDSymbol name="TWToolbarGroup" value="0x1050" />

    The name attributes of the GuidSymbol and IDSymbol elements in a defined toolbar, command, or group provide a GUID:ID pair that represents that toolbar, command, or group. The GUID represents a command set that is defined for your VSPackage. Multiple command sets may be defined in the package. The GUID:ID pair that is used to identify each item must be unique.

  5. Just above the section that is formed by the Groups Element, create a section by using the Menus Element.

  6. Define the toolbar as a Menu Element in the Menus section, as follows:

    1. Set the guid and id attributes to the GUID:ID of the new toolbar.

    2. Set the type attribute to ToolWindowToolbar.

    3. In the Menu element, use the Strings Element to create a section that contains a ButtonText Element and a CommandName Element. The ButtonText element is used to set the name of the toolbar as it appears in the IDE. The CommandName element is used to set the command name that can be typed in the Command window to access the toolbar.

    The following example defines a tool window toolbar.

    <Menu guid="guidTWToolbarCmdSet" id="TWToolbar"
      type="ToolWindowToolbar" >
  <CommandFlag>DefaultDocked</CommandFlag>
  <Strings>
    <ButtonText>Test Toolbar</ButtonText>
    <CommandName>Test Toolbar</CommandName>
  </Strings>
</Menu>

  7. In the Groups section, create a Group Element to contain the commands that you want to appear on your toolbar.

    1. Set the priority of the group to determine where it will appear on your toolbar.

      A group that has a low priority setting will appear on the left side of the toolbar (or the top, depending on how the toolbar is oriented).

    2. Set the parent of the group to the GUID:ID of the toolbar.

    The following group appears on the toolbar that is defined in the previous example.

    <Group guid="guidTWToolbarCmdSet" id="TWToolbarGroup"
      priority="0x0000">
  <Parent guid="guidTWToolbarCmdSet" id="TWToolbar"/>
</Group>

Displaying the Toolbar in the Tool Window

Use the Managed Package Framework (MPF) to program the package to display the toolbar in the tool window.

The ToolBar property of the ToolWindowPane class takes a CommandID instance as its value. The CommandID instance takes a (string) Guid and and an (int) ID. By setting these to the GUID:ID pair of the toolbar, the toolbar is bound to the tool window. Typically, this is done in the constructor of the class that derives from the ToolWindowPane class.

A managed code tool window that is built by using the MPF can have only one toolbar.

To display the toolbar in the tool window

  1. When you create a VSPackage by using the package wizard, the command set GUIDs are automatically added to the GuidList class, which is defined in the Guids.cs file. Generated menu and command IDs are added to the PkgCmdIDList class, which is defined in PkgCmdID.cs. Then, GUID and ID values can be accessed, in a readable form, through those two classes.

    Open PkgCmdID.cs.

  2. Add an entry for the tool window toolbar, and for any commands that you want to appear on the toolbar. The value of each entry must match the value attribute of the associated IDSymbol element.

    The following example creates an entry for the toolbar defined earlier.

    public const int TWToolbar = 0x1000;

  3. Open MyToolWindow.cs.

  4. In the constructor, set the ToolBar property of the MyToolWindow class to a new CommandID instance with the Guid and ID of the toolbar as parameters, as shown in the following example.

    this.ToolBar = new CommandID(
    GuidList.guidTWToolbarCmdSet,
    PkgCmdIDList.TWToolbar);

    If the GuidList and PkgCmdIDList classes are not defined, you can use the String value of the GUID and the Int value of the ID instead.

See Also

Tasks

How to: Create Reusable Groups of Buttons

Walkthrough: Adding a Toolbar to a Tool Window

Other Resources

Visual Studio Command Table (.Vsct) Files

Common Tasks with Commands, Menus, and Toolbars