Walkthrough: Adding a Toolbar to a Tool Window
This walkthrough guides you through the steps of adding a toolbar to a tool window. Create a toolbar for your tool window if you want to provide quick access to tool window commands for users of your VSPackage.
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. Unlike toolbars in the integrated development environment (IDE), a toolbar in a tool window must be docked and cannot be moved or customized. In managed code, the toolbar in a tool window is always docked to the upper edge of the window. In umanaged code, however, it can be docked on any edge. This is explained further in the procedures below.
Toolbars in tool windows are not created automatically by the IDE. They must be added programmatically by the VSPackage that creates the tool window. The process for doing this in managed code, such as Visual C#, is different from the process in unmanaged code, such as Visual C++. Both procedures are described in this walkthrough.
For more information on menus and the .ctc file, see Menus and Toolbars.
For a walkthrough on adding a toolbar to the IDE, see Walkthrough: Adding a Toolbar to the IDE.
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 MyTWToolbarPackage VSPackage
-
Open Visual Studio. On the File menu, point to New, and then click Project.
-
In the Project types pane of the New Project dialog box, expand the Other Project Types node, and then click Extensibility.
-
In the Templates pane, select Visual Studio Integration Package.
-
In the Name box, type MyTWToolbarPackage. Select a destination folder for the project.
-
Click OK to open the Visual Studio Integration Package Wizard.
-
Read the Welcome to the Visual Studio Integration Package Wizard page.
-
On the Select a Programming Language page, select Visual C# or Visual C++, depending on which language you want to use.
You can use either Visual C# or Visual C++ as the language for your VSPackage. However, the process for adding a toolbar to a Visual C++ VSPackage tool window is different than that for adding a toolbar to a Visual C# VSPackage tool window. Therefore, two procedures are given below for adding a toolbar: one for Visual C# and the other for Visual C++. The only common element between the two procedures is the modification of the .ctc file.
Accept the default for the key file.
-
On the Basic VSPackage Information page, accept the defaults.
-
On the Select VSPackage Options page, select the Menu Command check box and the Tool Window check box.
-
On the Command Options page, set the Command Name to My TW Toolbar Test Command and set the Command ID to cmdidMyTestCmd.
Click Finish. After the wizard finishes building the project, the status bar displays that the MyTWToolbarPackage solution has built successfully.
To create a toolbar for a tool window
-
In Solution Explorer, expand the CtcComponents folder in the MyTWToolbarPackage project, right-click CommandIds.h, and then click Open to open it in a text editor.
-
In the Menu IDs section, add a definition for MyToolbar:
#define MyToolbar 0x1000
-
In the Menu Group IDs section, add a definition for MyToolbarGroup:
#define MyToolbarGroup 0x1050
-
In the CtcComponents folder, right-click MyTWToolbarPackage.ctc, and then click Open to open it in a text editor.
-
In the MENUS_BEGIN section, add the following lines to define the toolbar:
guidMyTWToolbarPackageCmdSet:MyToolbar, // Menu ID guidMyTWToolbarPackageCmdSet:MyToolbar, // Parent Group 0x0000, // Priority TOOLWINDOWTOOLBAR, // Type and Flags "My Toolbar"; // Toolbar NameToolbars cannot be nested like submenus, so the parent group of a toolbar is, by convention, set to the same GUID:ID pair as the toolbar itself. A toolbar in a tool window always must be positioned programmatically.
-
In the NEWGROUPS_BEGIN section, after the existing group entry, add the following lines to define the group that contains the commands for the toolbar:
// Any command added to this group appears on the toolbar. guidMyTWToolbarPackageCmdSet:MyToolbarGroup, // Group ID guidMyTWToolbarPackageCmdSet:MyToolbar, // Menu ID 0x0000; // Priority -
In the CMDPLACEMENT_SECTION section, type the following line to add the existing command to the toolbar group so the toolbar will be displayed (by default, if a toolbar has no commands, it does not appear):
guidMyTWToolbarPackageCmdSet:cmdidMyTestCmd, // Command ID guidMyTWToolbarPackageCmdSet:MyToolbarGroup, // Parent ID 0x0000; // Priority -
In Solution Explorer, right-click the MyTWToolbarPackage project, and then click Rebuild.
This rebuilds the .ctc file with the changes. Correct any errors that occur during building. (Wrong case for a GUID label or a command ID is the most common error. GUID labels and command IDs always are case-sensitive.)
Because the new toolbar is not added automatically to the tool window by the Visual Studio shell, the toolbar must be added programmatically by the VSPackage itself. This is discussed in the next section, Adding a Toolbar to the Tool Window.
The following procedure assumes that you created the VSPackage in Visual C#. For a VSPackage created in Visual C++, see the next procedure, To add a toolbar to a tool window in unmanaged code.
To add a toolbar to a tool window in managed code
-
In Solution Explorer, expand the MyTWToolbarPackage project, right-click PkgCmdID.cs, and then click Open to open it in a text editor.
-
After the existing command IDs in the PkgCmdID.cs file, add the following command ID:
public const int MyToolbar = 0x1000;
-
In Solution Explorer, right-click MyToolWindow.cs, and then click Open to open it in a text editor.
-
At the top of the file, after the other using statements, add the following line:
using System.ComponentModel.Design; // for CommandID
-
In the MyToolWindow class constructor, at the beginning of the constructor, just before the comment //set the window title reading it from the resources, add the following line.
this.ToolBar = new CommandID(GuidList.guidMyTWToolbarPackageCmdSet, PkgCmdIDList.MyToolbar);
This code notifies 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 per tool window.
-
On the Build menu, click Build Solution to build the solution.
Correct any errors that occur.
-
To test the toolbar, refer to the section, Testing the Toolbar in a Tool Window.
To add a toolbar to a tool window in unmanaged code
-
In Solution Explorer, expand the Source Files folder in the MyToolbarMenuPackage project, right-click VsPkg.cpp, and then click Open to open it in a text editor.
-
Find the CMyToolbarMenuPackagePackage::CreateTool method. In that method, locate the call to the CreateToolWindow method. Modify the first parameter passed to that method so that it looks like the following:
CTW_fInitNew | CTW_fForceCreate | CTW_fToolbarHost, // dwCTWAdding the CTW_fToolbarHost flag assures that a toolbar host is created when the tool window is created. A toolbar host contains and manages toolbars for a tool window.
-
Also in the CMyToolbarMenuPackagePackage::CreateTool method, find the second call to the SetProperty method, the call that contains the VSFPROPID_BitmapIndex parameter. After that call, add the following lines:
// Add the tool bar CComVariant varToolbarHost; CComPtr<IVsToolWindowToolbarHost> srpToolbarHost; HRESULT hr = m_srpToolWinFrame-> GetProperty(VSFPROPID_ToolbarHost,&varToolbarHost); if (VT_UNKNOWN == varToolbarHost.vt && NULL != varToolbarHost.punkVal) { varToolbarHost.punkVal-> QueryInterface(IID_IVsToolWindowToolbarHost, (void **)&srpToolbarHost); if (NULL != srpToolbarHost) { srpToolbarHost->AddToolbar(VSTWT_TOP, &guidMyTWToolbarPackageCmdSet, MyToolbar); } }
Note Using unmanaged code, it is possible to add multiple toolbars to a tool window. Create each toolbar as described in the procedure above, and then call the AddToolbar method in the IVsToolWindowToolbarHost interface once for each toolbar. Each toolbar can be docked at the top, bottom, left or right edges of the tool window. If all the toolbars are docked at the same edge of the tool window, then the order in which they are added determines the order in which the they appear in the tool window, with the first toolbar added appearing nearest to the edge.
-
On the Build menu, click Build Solution to build the solution.
Correct any errors that occur.
-
To test the toolbar, refer to the section, Testing the Toolbar in a Tool Window.
To test the toolbar in a tool window
-
Open an instance of the experimental Visual Studio by doing any one of the following:
-
At a Visual Studio command prompt, type devenv /rootsuffix exp.
-
On the Start Menu, click the experimental Visual Studio shortcut; for example, Microsoft Visual Studio 2005 Experimental.
This shortcut is added when the Visual Studio SDK is installed.
-
Press F5 or select Start on the Debug menu.
This runs the experimental Visual Studio under the debugger and allows debugging of your VSPackage).
-
-
On the View menu, point to Other Windows and then click MyToolWindow to display the tool window.
Notice that a toolbar displays just below the title of the tool window.
-
On the tool window's toolbar, click the icon to display a message.
-
For managed code: "Inside Company.MyTWToolbarPackage.MyTWToolbarPackage.MenuItemCallback()".
-
For unmanaged code: "Inside CMyTWToolbarPackagePackage::Exec".
-