How to: Create a Multi-Instance Tool Window

You can program a tool window so that multiple instances of it can be open simultaneously. By default, tool windows can have only one instance open.

By using a multi-instance tool window, you can show several related sources of information at the same time. For example, you could put a multi-line TextBox control in a multi-instance tool window so that several code snippets are simultaneously available during a programming session. Also for example, you could put a DataGrid control and a drop-down list box in a multi-instance tool window so that several real-time data sources can be tracked simultaneously.

To create a multi-instance tool window

1. Create a tool window by using the Visual Studio Package Template. For more information, see How to: Create a Tool Window.

2. Open the package file (ProjectNamePackage.cs or ProjectNamePackage.vb).

3. Just above the class definition, find the ProvideToolWindow attribute and the MultiInstances=true parameter, as shown in the following example.

   [ProvideToolWindow(typeof(MyToolWindow), MultiInstances = true)]
   

   This creates a registry entry that enables multiple instances of the tool window to coexist.

4. Call the FindToolWindow method and set its create flag to false so that it will iterate through existing tool window instances until an available id is found.

5. To create a tool window instance, call the FindToolWindow method and set its id to an available value and its create flag to true.

   By default, the value of the id parameter of the FindToolWindow method is 0. This makes a single-instance tool window. For more than one instance to be hosted, every instance must have its own unique id.

6. Call the Show method on the IVsWindowFrame object that is returned by the Frame property of the tool window instance.

   This displays the tool window.

Example

By default, the ShowToolWindow method that is created by the package template supports a single-instance tool window. The following example shows how to modify the ShowToolWindow method to support multiple instances.

private void ShowToolWindow(object sender, EventArgs e)
{
    for (int i = 0; ; i++)
    {
        // Find existing windows.
        var currentWindow = this.FindToolWindow(
            typeof(MyToolWindow), i, false);
        if (currentWindow == null)
        {
            // Create the window with the first free ID.
            var window = (ToolWindowPane)this.CreateToolWindow(typeof(MyToolWindow), i);

            if ((null == window) || (null == window.Frame))
            {
                throw new NotSupportedException(
                    Resources.CanNotCreateWindow);
            }
            IVsWindowFrame windowFrame = (IVsWindowFrame)window.Frame;

            // Display the window.
            Microsoft.VisualStudio.ErrorHandler.ThrowOnFailure(
                windowFrame.Show());
            break;
        }
    }
}

See Also

Tasks

How to: Open a Tool Window Programmatically

Reference

FindToolWindow

Other Resources

Tool Windows