How to: Create and Control Tool Windows

  • Article

Windows in Visual Studio fall into either of two categories: document windows or tool windows. A document window is one whose content is editable by the Code Editor, such as a text file, HTML, or code inside a class. A tool window contains one or more controls, such as buttons, text, combo boxes, and so forth. The Visual Studio integrated development environment (IDE) uses controls to perform tasks such as setting options, viewing errors, or editing project elements. Some examples of these are the Output window, the Task List, and the Toolbox. The Toolbox can be moved around the IDE freely or docked with other tool windows, and you can use the LinkedWindows collection to programmatically link or unlink tool windows in the IDE. For more information, see How to: Change Window Characteristics.

In addition to using automation to manipulate existing tool windows, you can also create your own custom tool windows by using the CreateToolWindow2 method of the Windows2 collection.

By creating your own custom tool window you can fill it with useful controls to perform tasks. You might, for example, use a custom tool window to display specialized tools to help you format your code, track and change variable settings, or perform advanced debugging tasks or source profiling.

The procedure for creating a custom tool window is:

  • Create a User control (using a Windows Control Library project)

  • Add desired controls on a form (buttons, textboxes, and so on) and code.

  • Compile the project into a DLL.

  • Create a new Visual Studio add-in project (or other project, such as a Windows Application project).

  • Use the CreateToolWindow2 method to create a tool window to host the new User control.

Before invoking CreateToolWindow2 to create a new tool window, you should either move the User control (ControlObject) into the same assembly as the add-in, or set all of the attributes on the User control to make it fully visible to COM. (For example, checking the Register for COM interop option in the project's compile options.) If you do not do this, then the control will not marshal correctly and CreateToolWindow2 will return a null value.

In addition to the examples below, additional tool window samples for each language, as well as other code examples, are on the Automation Samples for Visual Studio Web site.

Note

If you attempt to set any of the visibility states of the new tool window — such as height, width, or position — before the tool window is visible, you will get an error. Make sure that the window is visible before attempting to set such properties.

Note

The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. These procedures were developed with the General Development Settings active. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Visual Studio Settings.

Creating a Custom Tool Window

The following example demonstrates how to create a tool window in Visual Basic and Visual C#.

Note

The following code must be executed in an Add-in; it cannot be executed in a macro.

To create a custom tool window

  • Create a user control in a Windows Control Library project. Accept the default name of "WindowsControlLibrary1", or make sure you change the name of the asmPath parameter in the code below to match the name of your Windows Control Library project.

    Alternatively, in your code, you can refer to an existing user control.

Note

Your user control class must have a System.Runtime.InteropServices.GuidAttribute attached to the class definition.

  1. Create a new Add-in project.

    For information, see How to: Create an Add-In.

  2. Replace the OnConnection method of the add-in with the following:

    Public Sub OnConnection(ByVal application As Object, ByVal _
connectMode As ext_ConnectMode, ByVal addInInst As Object, _
ByRef custom As Array) Implements IDTExtensibility2.OnConnection
    Try
        ' ctlProgID - the ProgID for your user control.
        ' asmPath - the path to your user control DLL.
        ' guidStr - a unique GUID for the user control.
        Dim ctlProgID, asmPath, guidStr As String
        ' Variables for the new tool window that will hold
        ' your user control.
        Dim toolWins As EnvDTE80.Windows2
        Dim toolWin As EnvDTE.Window
        Dim objTemp As Object = Nothing

        _applicationObject = CType(application, DTE2)
        _addInInstance = CType(addInInst, AddIn)
        ctlProgID = "WindowsControlLibrary2.UserControl1"
        ' Replace the <Path to VS Project> with the path to
        ' the folder where you created the WindowsCotrolLibrary.
        ' Remove the line returns from the path before 
        ' running the add-in.
        asmPath = "<Path to VS Project>\My _
          Documents\Visual Studio 2005\Projects\ _
          WindowsControlLibrary2\WindowsControlLibrary2\_
          bin\Debug\WindowsControlLibrary2.dll"
        guidStr = "{E9C60F2B-F01B-4e3e-A551-C09C62E5F584}"

        toolWins = CType(_applicationObject.Windows, Windows2)
        ' Create the new tool window, adding your user control.
        toolWin = toolWins.CreateToolWindow2(_addInInstance, _
          asmPath, ctlProgID, "MyNewToolwindow", guidStr, objTemp)
        ' The tool window must be visible before you do anything 
        ' with it, or you will get an error.
        If Not toolWin Is Nothing Then
            toolWin.Visible = True
        End If
           ' Uncomment the code below to set the new tool window's
           ' height and width, and to close it.
        ' MsgBox("Setting the height to 500 and width to 400...")
        ' toolWin.Height = 500
        ' toolWin.Width = 400
        ' MsgBox("Closing the tool window...")
        ' toolWin.Close(vsSaveChanges.vsSaveChangesNo)

    Catch ex As Exception
        MsgBox("Exception: " & ex.ToString)
    End Try
End Sub

    // Before running, add a reference to System.Windows.Forms, 
// using System.Windows.Forms, to the top of the class.
public void OnConnection(object application, 
ext_ConnectMode connectMode, object addInInst, ref Array custom)
{
    try
    {
        // ctlProgID - the ProgID for your user control.
        // asmPath - the path to your user control DLL.
        // guidStr - a unique GUID for the user control.
        string ctlProgID, asmPath, guidStr;
        // Variables for the new tool window that will hold
        // your user control.
        EnvDTE80.Windows2 toolWins;
        EnvDTE.Window toolWin;
        object objTemp = null;

        _applicationObject = (DTE2)application;
        _addInInstance = (AddIn)addInInst;
        ctlProgID = "WindowsControlLibrary2.UserControl1";
        // Replace the <Path to VS Project> with the path to
        // the folder where you created the WindowsCotrolLibrary.
        // Remove the line returns from the path before 
        // running the add-in.
        asmPath = @"c:\My Documents\Visual Studio 2005\Projects\
          WindowsControlLibrary2\WindowsControlLibrary2\bin\
          Debug\WindowsControlLibrary2.dll";
        guidStr = "{E9C60F2B-F01B-4e3e-A551-C09C62E5F584}";

        toolWins = (Windows2)_applicationObject.Windows;
        // Create the new tool window, adding your user control.
        toolWin = toolWins.CreateToolWindow2(_addInInstance, 
          asmPath, ctlProgID, "MyNewToolwindow", guidStr, 
          ref objTemp);
        // The tool window must be visible before you do anything 
        // with it, or you will get an error.
        if (toolWin != null)
        {
            toolWin.Visible = true;
        }
        // Set the new tool window's height and width, 
        // and then close it.
        System.Windows.Forms.MessageBox.Show("Setting the height 
        to 500 and width to 400...");
        toolWin.Height = 500;
        toolWin.Width = 400;
        System.Windows.Forms.MessageBox.Show
          ("Closing the tool window...");
        toolWin.Close(vsSaveChanges.vsSaveChangesNo);
    }
    catch (Exception ex)
    {
        System.Windows.Forms.MessageBox.Show("Exception: " 
          + ex.Message);
    }
}

    Note   The preceding code requires a reference to the System.Windows.Forms namespace.

  3. Change the values of the ctlProgID, asmPath, and guidStr variables to reflect your user control.

  4. Build and run the project.

  5. On the Tools menu, click Add-In Manager to activate the add-in.

You see your new tool window floating in the IDE. You can move it anywhere you like or dock it with other tool windows.

See Also

Tasks

How to: Change Window Characteristics

How to: Create an Add-In

Walkthrough: Creating a Wizard

Concepts

Controlling Options Settings

Automation Object Model Chart

Other Resources

Creating and Controlling Environment Windows

Creating Add-ins and Wizards

Automation and Extensibility Reference