How to: Create Toolbars in the IDE

You can add a toolbar to the integrated development environment (IDE) by defining a menu of type Toolbar in a VSPackage .vsct file.

A toolbar has the following characteristics:

• A toolbar is a horizontal or vertical bar that contains buttons. The buttons can have an icon or text, or a combination of icon and text.

• A toolbar can be docked on any edge of its parent window.

• The IDE treats a VSPackage-contributed toolbar just like it treats toolbars that are included in Visual Studio. The VSPackage does not have to do anything programmatically to enable its toolbar to be recognized by the Customize dialog box. If a user customizes the toolbar, the IDE automatically tracks the changes.

• The IDE automatically enables the toolbar to appear on the Toolbars submenu of the View menu so that users can hide it or display it.

• A toolbar that does not have a visible command is automatically hidden.

You can change these characteristics by specifying flags when you define the toolbar in the .vsct file, as shown in the following procedure.

To create a toolbar in the IDE

1. Create a package by running the Visual Studio Package Template. Follow the package-creation instructions in Walkthrough: Adding a Toolbar to the IDE.

2. Open the .vsct file in the editor. In the section that is formed by the Symbols section, find the GuidSymbol element that contains your menus, groups, and commands.

3. As shown in the following example, add an IDSymbol element for each of these: a toolbar, a command group, and one or more commands.

   <IDSymbol name="MyMenuGroup" value="0x1020" />
   <IDSymbol name="cmdidTestCmd" value="0x0100" />
   <IDSymbol name="Toolbar" value="0x1000" />
   <IDSymbol name="ToolbarGroup" value="0x1050" />
   

   The name attributes of the GuidSymbol and IDSymbol elements in a defined toolbar, command, or group provide the 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.

4. Just above the section that is formed by the Groups section, create a Menus section.

5. 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 priority attribute (optional).

      The priority attribute is typically omitted for a toolbar because it may be moved by users. Omitting the priority attribute has the same effect as setting it to 0. However, if the same window has several toolbars, you can assign their starting positions by setting their priorities.

   3. Set the type attribute to Toolbar.

   4. 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.

      If you want to add command flags, add a CommandFlag element for each one.

      For descriptions of command flag values, see Command Flag Element.

   The following example defines a toolbar.

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

   Note

   You do not have to define a parent for a menu of type Toolbar because it is automatically put in the IDE. Any setting for parent is ignored.

6. In the section that is formed by 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.

   <Group guid="guidIDEToolbarCmdSet" id="ToolbarGroup"
         priority="0x0000">
     <Parent guid="guidIDEToolbarCmdSet" id="Toolbar"/>
   </Group>
   

7. Add commands to the toolbar by creating command entries in the section that is formed by the Buttons section. Set the parent of each command entry to the GUID:ID of your group. Every Button element must have a GUID:ID that corresponds to an entry in the Symbols section.

   Use the priority attribute of each button entry to specify where the command will appear in the group.

   The following example defines a button that will appear on the toolbar.

   <Button guid="guidIDEToolbarCmdSet" id="cmdidTestCmd" priority="0x0100" type="Button">
     <Parent guid="guidIDEToolbarCmdSet" id="ToolbarGroup" />
     <Icon guid="guidImages" id="bmpPic1" />
     <Strings>
       <CommandName>cmdidTestCmd</CommandName>
       <ButtonText>Toolbar Test Command</ButtonText>
     </Strings>
   </Button>
   

   For more information about buttons and menu items, see Button Element.

See Also

Tasks

How to: Create Toolbars for Tool Windows

Walkthrough: Adding a Toolbar to the IDE

Walkthrough: Adding a Toolbar to a Tool Window

Concepts

VSCT XML Schema Reference

Other Resources

Common Tasks with Commands, Menus, and Toolbars