Walkthrough: Creating a Tool Window

Article
04/21/2015

Tool windows are common Visual Studio, for example the Solution Explorer, Task List, Error List, and Output windows. All tool windows have some features in common: they can all be docked in the IDE in the same manner. Predictable docking lets users manage their tasks and information efficiently.

This walkthrough shows how to create a tool window in the Visual Studio IDE by using the following steps:

Create a tool window.
Add a control to the tool window.
Add a toolbar to a tool window.
Add a command to the toolbar.
Implement the commands.
Set the default position for the tool window.

This walkthrough is part of a series that shows how to extend Visual Studio. For more information, see Walkthroughs for Customizing Visual Studio By Using VSPackages.

Prerequisites

To follow this walkthrough, you must install the Visual Studio 2013 SDK at Microsoft Download Center. For more information, see Extending Visual Studio Overview.

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

Create a Tool Window

To create a tool window

Create a VSPackage named FirstToolWin in Visual C#.

Note

For more information about creating a VSPackage project, see Walkthrough: Creating a VSPackage.
On the Select VSPackage Options page, select Tool Window.
On the Tool Window Options page, in the Window name box, type Windows Media Player. In the Command ID field, type cmdidWindowsMediaWin.
On the Select Test Project Options page, click Finish.

Add a Control to the Tool Window

Next, add the Windows Media Player control to the tool window.

To add a control to the tool window

First, remove the default control. Open MyControl.xaml and delete the Click Me! button.
In the Toolbox, expand the All WPF Controls section and drag the Media Element control to the MyControl form. Select the control, and in the Properties window, name this element mediaElement1.
On the File menu, click Save All.

By adding a toolbar in the following manner, you guarantee that its gradients and colors are consistent with the rest of the IDE.

In Solution Explorer, open FirstToolWin.vsct. The .vsct file defines the graphical user interface (GUI) elements in your tool window by using XML.
In the <Symbols> section, find the <GuidSymbol> node whose name attribute is guidFirstToolWinCmdSet. Add the following two <IDSymbol> elements to the list of <IDSymbol> elements in this node to define a toolbar and a toolbar group.
```
<IDSymbol name="ToolbarID" value="0x1000" />
<IDSymbol name="ToolbarGroupID" value="0x1001" />
```
Just above the <Groups> section, create a <Menus> section that resembles this:
```
<Menus>
    <Menu guid="guidFirstToolWinCmdSet" id="ToolbarID" priority="0x0000" type="ToolWindowToolbar">
        <Parent guid="guidFirstToolWinCmdSet" id="ToolbarID" />
        <Strings>
            <ButtonText>Tool Window Toolbar</ButtonText>
            <CommandName>Tool Window Toolbar</CommandName>
        </Strings>
    </Menu>
</Menus>
```
There are several different kinds of menu. This menu is a toolbar in a tool window, defined by its type attribute. The guid and id settings make up the fully qualified ID of the toolbar. Typically, the <Parent> of a menu is the containing group. However, a toolbar is defined as its own parent. Therefore, the same identifier is used for the <Menu> and <Parent> elements. The priority attribute is just '0'.
Toolbars resemble menus in many ways. For example, just as a menu may have groups of commands, toolbars may also have groups. (On menus, the command groups are separated by horizontal lines. On toolbars, the groups are not separated by visual dividers.)

Add a new <Group> element to the <Groups> section to define the group that you declared in the <Symbols> section.
```
<Group guid="guidFirstToolWinCmdSet" id="ToolbarGroupID" priority="0x0000">
    <Parent guid="guidFirstToolWinCmdSet" id="ToolbarID" />
</Group>
```
By setting the parent GUID and ID to the GUID and ID of the toolbar, you add the group to the toolbar.
Save the file.

Next, add a command to the toolbar, which is displayed as a button.

In FirstToolWin.vsct, in the <Symbols> section, declare the following IDSymbol elements just after the toolbar and toolbar group declarations.
```
<IDSymbol name="cmdidWindowsMedia" value="0x0100" />
<IDSymbol name="cmdidWindowsMediaOpen" value="0x132" />
```

Add a Button element inside the <Buttons> section. This element will appear on the toolbar in the tool window, with a Search (magnifying glass) icon.

<Button guid="guidFirstToolWinCmdSet" id="cmdidWindowsMediaOpen" priority="0x0101" type="Button">
    <Parent guid="guidFirstToolWinCmdSet" id="ToolbarGroupID"/>
    <Icon guid="guidImages" id="bmpPicSearch" />
    <Strings>
        <CommandName>cmdidWindowsMediaOpen</CommandName>
        <ButtonText>Load File</ButtonText>
    </Strings>
</Button>

Save and close FirstToolWin.vsct.

Open PkgCmdID.cs and add the following lines in the class just after the existing members.

public const uint cmdidWindowsMedia =        0x100; 
public const int cmdidWindowsMediaOpen = 0x132;
public const int ToolbarID = 0x1000;

Doing this makes your commands available in code.

Save and close the file.

Add a MediaPlayer Property to MyControl

From the event handlers for the toolbar controls, your code must be able to access the Media Player control, which is a child of the MyControl class.

In Solution Explorer, right-click MyControl.xaml, click View Code, and add the following code to the MyControl Class.

public System.Windows.Controls.MediaElement MediaPlayer
{
    get { return mediaElement1; }
}

Add a toolbar and a menu command that invokes the Open File dialog and plays the selected media file.

Open MyToolWindow.cs and add the following using statements.

using System.ComponentModel.Design;
using System.Windows.Forms;

Inside the MyToolWindow class, add a reference to the MyControl control.
```
public MyControl control;
```
At the end of the constructor, set this control variable to the newly-created control.
```
control = new MyControl(); 
base.Content = control;
```

Instantiate the toolbar inside the constructor.

this.ToolBar = new CommandID(GuidList.guidFirstToolWinCmdSet, PkgCmdIDList.ToolbarID);
this.ToolBarLocation = (int)VSTWT_LOCATION.VSTWT_TOP;

Also inside the contructor, after instantiating the toolbar, add the menu command to the toolbar. The ButtonHandler command will be implemented in the next section.

// Create the handles for the toolbar command. 
var mcs = GetService(typeof(IMenuCommandService))as OleMenuCommandService;
if (null != mcs)
{
    var toolbarbtnCmdID = new CommandID(GuidList.guidFirstToolWinCmdSet,
        PkgCmdIDList.cmdidWindowsMediaOpen);
    var menuItem = new MenuCommand(new EventHandler(
        ButtonHandler), toolbarbtnCmdID);
    mcs.AddCommand(menuItem);
}

At this point the MyToolWindow constructor should look like this:

public MyToolWindow() :
    base(null)
{
    // Set the window title reading it from the resources.
    this.Caption = Resources.ToolWindowTitle;
    // Set the image that will appear on the tab of the window frame
    // when docked with an other window
    // The resource ID correspond to the one defined in the resx file
    // while the Index is the offset in the bitmap strip. Each image in
    // the strip being 16x16.
    this.BitmapResourceID = 301;
    this.BitmapIndex = 1;

    this.ToolBar = new CommandID(GuidList.guidFirstToolWinCmdSet, PkgCmdIDList.ToolbarID);
    this.ToolBarLocation = (int)VSTWT_LOCATION.VSTWT_TOP;

    // Create the handles for the toolbar command. 
    var mcs = GetService(typeof(IMenuCommandService))
        as OleMenuCommandService;
    if (null != mcs)
    {
        var toolbarbtnCmdID = new CommandID(GuidList.guidFirstToolWinCmdSet,
        PkgCmdIDList.cmdidWindowsMediaOpen);
        var menuItem = new MenuCommand(new EventHandler(
             ButtonHandler), toolbarbtnCmdID);
        mcs.AddCommand(menuItem);
    }

    // This is the user control hosted by the tool window; Note that, even if this class implements IDisposable,
    // we are not calling Dispose on this object. This is because ToolWindowPane calls Dispose on 
    // the object returned by the Content property.
    control = new MyControl();  
    base.Content = control;   
}

Add a ButtonHandler method that invokes the Open File dialog. When a file has been selected, it plays the media file.

private void ButtonHandler(object sender, EventArgs arguments)
{
    OpenFileDialog openFileDialog = new OpenFileDialog();
    DialogResult result = openFileDialog.ShowDialog();
    if (result == DialogResult.OK)
    {
        control.MediaPlayer.Source = new System.Uri(openFileDialog.FileName);
    }
}

Set the Default Position for the Tool Window

Next, specify a default location in the IDE for the tool window. Configuration information for the tool window is in the FirstToolWinPackage.cs file.

To set the default position for the tool window

In Solution Explorer, open FirstToolWinPackage.cs or FirstToolWinPackage.vb. In this file, find the ProvideToolWindowAttribute attribute on the FirstToolWinPackage class. This code is passing the MyToolWindow type to the constructor. To specify a default position, you must add more parameters to the constructor following example.
```
[ProvideToolWindow(typeof(MyToolWindow),

    Style = Microsoft.VisualStudio.Shell.VsDockStyle.Tabbed,
    Window = "3ae79031-e1bc-11d0-8f78-00a0c9110057")]
```
The first named parameter is Style and its value is Tabbed, which means that the window will be a tab in an existing window. The docking position is specified by the Window parameter, n this case, the GUID of the Solution Explorer.

Note

For more information about the types of windows in the IDE, see vsWindowType.
Save your work.

Testing the Tool Window

To test the tool window

Press F5 to open a new instance of the Visual Studio experimental build.
On the View menu, point to Other Windows and then click Windows Media Player.

The media player tool window should open in the same position as Solution Explorer.
Click the button (it has the Search icon) in the tool window. Select a supported sound or video file, for example, C:\windows\media\chimes.wav, then press Open.

You should hear the chime sound.

What's Next

For more walkthroughs and information about tool windows, see Tool Windows

In Walkthrough: Integrating into the Properties Window, Task List, Output Window, and Options Dialog Box you can find out how to integrate your tool window with the existing tool windows in Visual Studio, such as the Properties window, the Output window, and the Task List window.

Walkthrough: Creating a Tool Window

Prerequisites

Locations for the Visual Studio Package Project Template

Create a Tool Window

To create a tool window

Add a Control to the Tool Window

To add a control to the tool window

Add a MediaPlayer Property to MyControl

To implement to menu command in the tool window

Set the Default Position for the Tool Window

To set the default position for the tool window

Testing the Tool Window

To test the tool window

What's Next

See Also

Other Resources

Additional resources

Walkthrough: Creating a Tool Window

Prerequisites

Locations for the Visual Studio Package Project Template

Create a Tool Window

To create a tool window

Add a Control to the Tool Window

To add a control to the tool window

Add a Toolbar to the Tool Window

To add a toolbar to the tool window

Add a Command to the Toolbar

To add a command to the toolbar

Add a MediaPlayer Property to MyControl

Instantiate the Tool Window and Toolbar

To instantiate the tool window and toolbar

To implement to menu command in the tool window

Set the Default Position for the Tool Window

To set the default position for the tool window

Testing the Tool Window

To test the tool window

What's Next

See Also

Other Resources

Additional resources