IVsUIShell.CreateToolWindow Method

Definition

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

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