Walkthrough: Adding a Toolbar to a Tool Window

[アーティクル]
09/17/2008

This walkthrough guides you through the steps for adding 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 that are 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. The process for doing this in managed code, such as Visual C#, differs from the process in unmanaged code, such as Visual C++. Both procedures are described in this walkthrough.

Unlike toolbars in the IDE, a toolbar in a tool window must be docked and cannot be moved or customized. If the VSPackage is written in managed code, the toolbar in a tool window 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.

注意

Beginning with Visual Studio 2008 SDK, use XML Command Table (.vsct) files instead of command table configuration (.ctc) files to define how menus and commands appear in your VSPackages. For more information, see Visual Studio Command Table (.Vsct) Files.

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 this walkthrough writes information to the experimental registry hive, the Visual Studio SDK must be installed.

Creating a VSPackage

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 Other Project Types 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, adding a toolbar to a Visual C++ VSPackage tool window differs from adding a toolbar to a Visual C# VSPackage tool window. Therefore, two procedures for adding a toolbar are given in this walkthrough, one for Visual C# and the other for Visual C++. The only common element in 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 Menu Command and Tool Window.
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 been built successfully.

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 the following 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 Name
```
Toolbars cannot be nested like submenus. Therefore, 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 must always 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 that the toolbar will be displayed.
```
guidMyTWToolbarPackageCmdSet:cmdidMyTestCmd,     // Command ID
    guidMyTWToolbarPackageCmdSet:MyToolbarGroup, // Parent ID
    0x0000;                                      // Priority
```
By default, if a toolbar has no commands, it does not appear.
In Solution Explorer, right-click the MyTWToolbarPackage project, and then click Rebuild.

Doing 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 are always case-sensitive.)

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

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

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.

注意

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, see "Testing the Toolbar in a Tool Window."

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 resembles the following.
```
CTW_fInitNew | CTW_fForceCreate | CTW_fToolbarHost, // dwCTW
```
Adding the CTW_fToolbarHost flag guarantees 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);
        }
    }
```
注意

In unmanaged code, you can add multiple toolbars to a tool window. Create each toolbar as described in the procedure, and then call the AddToolbar method in the IVsToolWindowToolbarHost interface one time 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 nearest to the edge.
On the Build menu, click Build Solution to build the solution.

Correct any errors that occur.
To test the toolbar, see "Testing the Toolbar in a Tool Window."

Press F5 to open an instance of the experimental Visual Studio in debug mode.
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.
On the tool window toolbar, click the icon to display a message, as follows:
- For managed code, "Inside Company.MyTWToolbarPackage.MyTWToolbarPackage.MenuItemCallback()".
- For unmanaged code, "Inside CMyTWToolbarPackagePackage::Exec".

次の方法で共有

Prerequisites

Creating a VSPackage

To create the MyTWToolbarPackage VSPackage

See Also

Concepts

その他のリソース

次の方法で共有

Walkthrough: Adding a Toolbar to a Tool Window

Prerequisites

Creating a VSPackage

To create the MyTWToolbarPackage VSPackage

Creating a Toolbar for a Tool Window

To create a toolbar for a tool window

Adding a Toolbar to the Tool Window

To add a toolbar to a tool window in managed code

To add a toolbar to a tool window in unmanaged code

Testing the Toolbar in a Tool Window

To test the toolbar in a tool window

See Also

Concepts

その他のリソース