This documentation is archived and is not being maintained.

How to: Create a Multi-Instance Tool Window

Updated: July 2008

By default, tool windows are single-instance. A single-instance tool window can be opened only when no other instances of the same tool window are open. However, you can create multi-instance tool windows, which can have multiple instances open at the same time.

A multi-instance tool window lets users keep several similar sources of information available at the same time. For example, you could put a multi-line TextBox control in a multi-instance tool window so that users can keep several code snippets available for re-use 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 users can track several real-time data sources at the same time.

To create a multi-instance tool window.

  1. Create a tool window by using the Visual Studio Integration Package Wizard. For more information, see, How to: Create a Tool Window (C#).

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

  3. Just above the class definition, find the ProvideToolWindow attribute and the parameter MultiInstances=true, 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 to iterate through existing tool window instances until an available id is found.

  5. Call the FindToolWindow method and set its id to an available value and its create flag to true to create the new tool window instance.

    By default, FindToolWindow is called by using an id of 0 for 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.

By default, the ShowToolWindow method that is created by the package wizard 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 = 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;
        }
    }
}

Date

History

Reason

July 2008

Added topic.

Information enhancement.

Show: