Walkthrough: Adding a Toolbar to a Tool Window (C#)

This walkthrough shows how to add a toolbar to a tool window. Create a toolbar if you want to 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 menus and command table configuration files, see Menus and Toolbars.

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

Prerequisites

Because the product of this walkthrough writes information to the experimental registry hive, the Visual Studio SDK must be installed.

Creating a VSPackage for a Tool Window

This section demonstrates how to use the Visual Studio Integration Package wizard to create a tool-window VSPackage that supports a single menu command.

To create the TWToolbar VSPackage

1. Create a VSPackage named TWToolbar. For more information, see How to: Create VSPackages (C# and Visual Basic).

2. In the Visual Studio Integration Package Wizard, set the programming language to 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 will reside 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 there is no need to assign a parent. Likewise, it is not necessary to set a priority, since toolbars are movable by the user. 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="cmdidTWTestCmd" 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.cs in the text editor.

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

   public const int TWToolbar = 0x1000;
   

3. Open MyToolWindow.cs in the text editor.

4. At the top of the file, after the other 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.

7. Correct any errors that occur.

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 MyToolWindow 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

Menu and Toolbar Command Walkthroughs

Menus and Toolbars