How to: Open a Dynamic Tool Window

Tool windows are typically opened from a command on a menu, or an equivalent keyboard shortcut. At times, however, you might need a tool window that opens whenever a particular user interface (UI) context applies, and closes when the UI context no longer applies. Tool windows like these are called dynamic or auto-visible.

Note

For a list of predefined UI contexts, see VSConstants and look for fields that begin with UICONTEXT_.

If you want to open a dynamic tool window at startup, and it is possible for the creation to fail, you must implement the IVsPackageDynamicToolOwnerEx interface and test the failure conditions in the QueryShowTool method. In order for the shell to know that you have a dynamic tool window that should be opened at startup, you must add the SupportsDynamicToolOwner value (set to 1) to your package registration. This value is not part of the standard PackageRegistrationAttribute, so you must create a custom attribute to add it. For more information about custom attributes, see Using a Custom Registration Attribute to Register an Extension.

Use FindToolWindow to open a tool window. The tool window is created as needed.

Note

A dynamic tool window can be closed by the user. If you want to create a menu command so the user can reopen the tool window, the menu command should be enabled in the same UI context that opens the tool window, and disabled otherwise.

To open a dynamic tool window

1. Create the tool window pane, frame, and the VSPackage that implements them. For more information, see How to: Create a Tool Window.

2. Register the tool window with Visual Studio by adding the ProvideToolWindowAttribute and ProvideToolWindowVisibilityAttribute to the VSPackage that provides it.

   <ProvideToolWindow(GetType(DynamicWindowPane), PositionX:=250, PositionY:=250, Width:=160, Height:=180, Transient:=True), _
    ProvideToolWindowVisibility(GetType(DynamicWindowPane), "f1536ef8-92ec-443c-9ed7-fdadf150da82"), _
    ProvideMenuResource(1000, 1), _
    DefaultRegistryRoot("Software\Microsoft\VisualStudio\8.0Exp"), _
    PackageRegistration(UseManagedResourcesOnly:=True), _
    Guid("01069CDD-95CE-4620-AC21-DDFF6C57F012")> _
   Public Class PackageToolWindow
       Inherits Package
   

   [ProvideToolWindow(typeof(DynamicWindowPane), PositionX = 250, PositionY = 250, Width = 160, Height = 180, Transient = true)]
   [ProvideToolWindowVisibility(typeof(DynamicWindowPane), /*UICONTEXT_SolutionExists*/"f1536ef8-92ec-443c-9ed7-fdadf150da82")]
   [ProvideMenuResource(1000, 1)]
   [DefaultRegistryRoot(@"Software\Microsoft\VisualStudio\8.0Exp")]
   [PackageRegistration(UseManagedResourcesOnly = true)]
   [Guid("01069CDD-95CE-4620-AC21-DDFF6C57F012")]
   public class PackageToolWindow : Package 
   

   This registers the tool window named DynamicWindowPane as a transient window that is not persisted when Visual Studio is closed and reopened. DynamicWindowPane is opened whenever UICONTEXT_SolutionExists applies, and closed otherwise. A default location and size is specified. For more information, see How to: Register a Tool Window.

3. Use FindToolWindow to find the tool window pane or to create it if it does not already exist.

   ' Get the (only) instance.
   ' The last flag is set to true so that if the tool window does not exists it will be created.
   Dim window As ToolWindowPane = Me.FindToolWindow(GetType(DynamicWindowPane), 0, True)
   If (window Is Nothing) Or (window.Frame Is Nothing) Then
       Throw New NotSupportedException(Resources.CanNotCreateWindow)
   End If
   

   // Get the (only) instance of this tool window.
   // The last flag is set to true so that if the tool window does not exists it will be created.
   ToolWindowPane window = this.FindToolWindow(typeof(DynamicWindowPane), 0, true);
   if ((null == window) || (null == window.Frame))
   {
       throw new NotSupportedException(Resources.CanNotCreateWindow);
   }
   

4. Get the tool window frame from the tool window pane.

   Dim windowFrame As IVsWindowFrame = TryCast(window.Frame, IVsWindowFrame)
   

   IVsWindowFrame windowFrame = (IVsWindowFrame)window.Frame;
   

5. Show the tool window.

   Microsoft.VisualStudio.ErrorHandler.ThrowOnFailure(windowFrame.Show())
   

   ErrorHandler.ThrowOnFailure(windowFrame.Show());
   

See Also

Concepts

VSPackage Essentials