Walkthrough: Adding a Toolbar to a Tool Window

This walkthrough shows how to add a toolbar to a tool window. Toolbars provide quick access to the commands in the tool window.

A toolbar is a horizontal or vertical strip that contains buttons bound to commands. The length of a toolbar in a tool window is always the same as the width or height of the tool window, depending on where the toolbar is docked.

Toolbars in tool windows are not created automatically by the integrated development environment (IDE). They must be added programmatically by the VSPackage that creates the tool window.

Unlike toolbars in the IDE, a toolbar in a tool window must be docked and cannot be moved or customized. If the tool-window VSPackage is written in managed code, the toolbar is always docked on the upper edge of the window. However, if the VSPackage is written in umanaged code, the toolbar can be docked on any edge.

For more information about how to add a toolbar to the IDE, see Walkthrough: Adding a Toolbar to the IDE.

Prerequisites

To complete this walkthrough, you must install the Visual Studio 2010 SDK.

Locations for the Visual Studio Package Project Template

The Visual Studio Package project template is available in three locations in the New Project dialog box:

• Under Visual Basic Extensibility. The default language of the project is Visual Basic.

• Under C# Extensibility. The default language of the project is C#.

• Under Other Project Types Extensibility. The default language of the project is C++.

Creating a VSPackage for a Tool Window

This section demonstrates how to use the Visual Studio Package project template to create a tool-window VSPackage that supports just one menu command.

To create the TWToolbar VSPackage

1. Create a VSPackage named TWToolbar. For more information, see Walkthrough: Creating a Menu Command By Using the Visual Studio Package Template.

2. Set the programming language to Visual Basic or Visual C#, and select the Menu Command and Tool Window options.

3. Under Command Options, set the command name to TWTest Command, and command ID to cmdidTWTestCmd.

4. Under Tool Window Options, set the window name to Test Tool Window, and command ID to cmdidTestTool.

Creating a Toolbar for a Tool Window

To create a toolbar for the tool window

1. Open TWToolbar.vsct in the text editor.

2. In the Symbols section, in the GuidSymbol node named "guidTWToolbarCmdSet", declare a toolbar and a toolbar group, as follows.

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

3. At the top of the Commands section, create a Menus section.

   <Menus></Menus>
   

   The toolbar definition is located here because the VSCT parser does not distinguish between menus and toolbars at this level.

4. Add a Menu element to the Menus section to define the toolbar.

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

   Toolbars cannot be nested like submenus. Therefore, you do not have to assign a parent. Also, you do not have to set a priority, because the user can move toolbars. Typically, initial placement of a toolbar is defined programmatically, but subsequent changes by the user are persisted.

5. In the Groups section, after the existing group entry, define a group to contain the commands for the toolbar.

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

6. In the Buttons section, change the parent of the existing Button element to the toolbar group so that the toolbar will be displayed.

   <Button guid="guidTWToolbarCmdSet" id="cmdidTWTestCommand" priority="0x0100" type="Button">
     <Parent guid="guidTWToolbarCmdSet" id="TWToolbarGroup"/>
     <Icon guid="guidImages" id="bmpPic1" />
     <Strings>
       <CommandName>cmdidTWTestCmd</CommandName>
       <ButtonText>TWTest Command</ButtonText>
     </Strings>
   </Button>
   

   By default, if a toolbar has no commands, it does not appear.

   Because the new toolbar is not added automatically to the tool window by the Visual Studio IDE, the toolbar must be added programmatically by the VSPackage itself. This is discussed in the next section, "Adding a Toolbar to the Tool Window."

Adding the Toolbar to the Tool Window

To add the toolbar to the tool window

1. In the TWToolbar project, open PkgCmdID.vb or PkgCmdID.cs in the text editor.

2. After the existing command IDs in the PkgCmdID file, add the following command ID.

   public const int TWToolbar = 0x1000;
   

3. Open MyToolWindow.vb or MyToolWindow.cs in the text editor.

4. At the top of the file, after the other Imports or using statements, add the following line.

   using System.ComponentModel.Design; // for CommandID
   

5. In the MyToolWindow class constructor, at the beginning of the constructor, add the following line.

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

   This code tells the managed package framework (MPF) which toolbar to create when the tool window is created.

   Note

   In managed code, only one toolbar can be added to a tool window.

6. On the Build menu, click Build Solution to build the solution.

Testing the Toolbar in the Tool Window

To test the toolbar in the tool window

1. Press F5 to open an instance of the experimental Visual Studio in debug mode.

2. On the View menu, point to Other Windows and then click Test Tool Window to display the tool window.

   Notice that a toolbar is displayed just under the title of the tool window.

3. On the tool window toolbar, click the icon to display the message "Inside Company.TWToolbar.TWToolbarPackage.MenuItemCallback()".

See Also

Tasks

Walkthrough: Adding a Toolbar to the IDE

Other Resources

Walkthroughs for Commands, Menus, and Toolbars

Commands, Menus, and Toolbars