IVsUIShell.CreateToolWindow Method

Reference

Definition

Namespace:: Microsoft.VisualStudio.Shell.Interop

Assembly:: Microsoft.VisualStudio.Shell.Interop.dll

Assembly:: Microsoft.VisualStudio.Interop.dll

Package:: Microsoft.VisualStudio.Interop v17.12.40391

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

This method creates a tool window containing the embedding indicated by punkDocView, or the clsidDocView parameter, if the punkDocView parameter is null.

public:
 int CreateToolWindow(System::UInt32 grfCTW, System::UInt32 dwToolWindowId, System::Object ^ punkTool, Guid % rclsidTool, Guid % rguidPersistenceSlot, Guid % rguidAutoActivate, Microsoft::VisualStudio::OLE::Interop::IServiceProvider ^ psp, System::String ^ pszCaption, cli::array <int> ^ pfDefaultPosition, [Runtime::InteropServices::Out] Microsoft::VisualStudio::Shell::Interop::IVsWindowFrame ^ % ppWindowFrame);

public int CreateToolWindow (uint grfCTW, uint dwToolWindowId, object punkTool, ref Guid rclsidTool, ref Guid rguidPersistenceSlot, ref Guid rguidAutoActivate, Microsoft.VisualStudio.OLE.Interop.IServiceProvider psp, string pszCaption, int[] pfDefaultPosition, out Microsoft.VisualStudio.Shell.Interop.IVsWindowFrame ppWindowFrame);

abstract member CreateToolWindow : uint32 * uint32 * obj * Guid * Guid * Guid * Microsoft.VisualStudio.OLE.Interop.IServiceProvider * string * int[] * IVsWindowFrame -> int

Public Function CreateToolWindow (grfCTW As UInteger, dwToolWindowId As UInteger, punkTool As Object, ByRef rclsidTool As Guid, ByRef rguidPersistenceSlot As Guid, ByRef rguidAutoActivate As Guid, psp As IServiceProvider, pszCaption As String, pfDefaultPosition As Integer(), ByRef ppWindowFrame As IVsWindowFrame) As Integer

Parameters

grfCTW: UInt32

[in] Specifies how a new tool window is created. For more information, see __VSCREATETOOLWIN.

dwToolWindowId: UInt32

[in] Tool window instance ID. If you are creating a single-instance tool window, then pass in a pass of zero for this parameter. If you are creating a multi-instance tool window, then pass in the identifier for the next available tool window.

punkTool: Object

[in] View object to be displayed in the client area of the tool window. This object can be an Active X control (such as, IOleInPlaceActiveObject, IOleControl), an Active X document (such as IOleView, IOleDocument), or a simple environment embedding (IVsWindowPane). Can be null if a value is provided for rclsidTool.

rclsidTool: Guid

[in] Tool to create class ID for the type of tool window. The indicated class is created using CreateInstance(Guid, Object, Guid, UInt32, IntPtr) (clsidTool). This functionality is a convenience for the caller. Can be GUID_NULL if a value is provided for punkTool.

rguidPersistenceSlot: Guid

[in] Unique identifier for this tool window so the environment can retain information (for example, window position, docking status, and so on) about this tool window across sessions. No two tool windows can share the same GUID. If so, the second tool window would fail in creation.

rguidAutoActivate: Guid

[in] Must be GUID_NULL. Do not use. For more information about how tool window visibility is controlled, see Tool Window Overview.

psp: IServiceProvider

[in] Pointer to the IServiceProvider interface. Can be null. This parameter allows the caller to specify an additional service provider provided for the tool window, and thus provide extra context to the tool window through the service. When the embedding makes a service request, the frame attempts to satisfy this request. If the service is not provided by the frame, then the service specified in the psp parameter is queried. If the service is not found there, then the environment's global service provider is queried.

pszCaption: String

[in] Tool window caption.

pfDefaultPosition: Int32[]

[out] Pointer to the default position of the tool window. Can be null, if the caller does not desire this information. If false, then the environment did not have any information saved about the last position of this tool window (that is, guidPersistenceSlot was not found), and the tool window is placed in some default location on the screen. If set to true, then the window is placed where the user last located and sized it.

ppWindowFrame: IVsWindowFrame

[out] Pointer to the window frame containing the tool window. Use this pointer to manipulate the location, size, caption, and so on of the tool window and to get the IUnknown interface pointer of the embedding.

Returns

Int32

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

COM Signature

From vsshell.idl:

HRESULT IVsUIShell::CreateToolWindow(  
   [in] VSCREATETOOLWIN grfCTW,  
   [in] DWORD dwToolWindowId,  
   [in] IUnknown *punkTool,  
   [in] REFCLSID rclsidTool,  
   [in] REFGUID rguidPersistenceSlot,  
   [in] REFGUID rguidAutoActivate,  
   [in] IServiceProvider *pSP,  
   [in] LPCOLESTR pszCaption,  
   [out] BOOL *pfDefaultPosition,  
   [out] IVsWindowFrame **ppWindowFrame  
);

Pass a value for either the punkTool parameter or for the rclsidTool parameter. If you pass a value for rclsidTool, then the environment creates the object for you using rclsidTool. The indicated class is created using CreateInstance (clsidTool).

The environment-implemented ToolFrame object is returned from which one can get the punkDocView, caption, position, and so on. For a full list of the properties that can be accessed, see __VSFPROPID.

Tool windows are created in the invisible state. Use Show or ShowNoActivate to make a tool window visible.

An instance of the UI hierarchy window is created by calling IVsUIShell::CreateToolWindow (CLSID_VsUIHierarchyWindow). The caller can use the returned pointer to the window frame to get the ppunkDocView, on which QueryInterface can be called for a pointer to the IVsUIHierarchyWindow interface.

Applies to

Compartilhar via