IVsUIShell.CreateToolWindow Method

Article
04/29/2015

This method creates a tool window containing the embedding indicated by punkDocView, or the clsidDocView parameter, if the punkDocView parameter is nulla null reference (Nothing in Visual Basic).

Namespace: Microsoft.VisualStudio.Shell.Interop
Assembly: Microsoft.VisualStudio.Shell.Interop (in Microsoft.VisualStudio.Shell.Interop.dll)

Syntax

'Declaration
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, _
    <OutAttribute> pfDefaultPosition As Integer(), _
    <OutAttribute> ByRef ppWindowFrame As IVsWindowFrame _
) As Integer

int CreateToolWindow(
    uint grfCTW,
    uint dwToolWindowId,
    Object punkTool,
    ref Guid rclsidTool,
    ref Guid rguidPersistenceSlot,
    ref Guid rguidAutoActivate,
    IServiceProvider psp,
    string pszCaption,
    int[] pfDefaultPosition,
    out IVsWindowFrame ppWindowFrame
)

int CreateToolWindow(
    [InAttribute] unsigned int grfCTW, 
    [InAttribute] unsigned int dwToolWindowId, 
    [InAttribute] Object^ punkTool, 
    [InAttribute] Guid% rclsidTool, 
    [InAttribute] Guid% rguidPersistenceSlot, 
    [InAttribute] Guid% rguidAutoActivate, 
    [InAttribute] IServiceProvider^ psp, 
    [InAttribute] String^ pszCaption, 
    [OutAttribute] array<int>^ pfDefaultPosition, 
    [OutAttribute] IVsWindowFrame^% ppWindowFrame
)

abstract CreateToolWindow : 
        grfCTW:uint32 * 
        dwToolWindowId:uint32 * 
        punkTool:Object * 
        rclsidTool:Guid byref * 
        rguidPersistenceSlot:Guid byref * 
        rguidAutoActivate:Guid byref * 
        psp:IServiceProvider * 
        pszCaption:string * 
        pfDefaultPosition:int[] byref * 
        ppWindowFrame:IVsWindowFrame byref -> int

function CreateToolWindow(
    grfCTW : uint, 
    dwToolWindowId : uint, 
    punkTool : Object, 
    rclsidTool : Guid, 
    rguidPersistenceSlot : Guid, 
    rguidAutoActivate : Guid, 
    psp : IServiceProvider, 
    pszCaption : String, 
    pfDefaultPosition : int[], 
    ppWindowFrame : IVsWindowFrame
) : int

Parameters

grfCTW
Type: UInt32

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

dwToolWindowId
Type: 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
Type: 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 nulla null reference (Nothing in Visual Basic) if a value is provided for rclsidTool.

rclsidTool
Type: Guid%

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

rguidPersistenceSlot
Type: 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
Type: Guid%

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

psp
Type: Microsoft.VisualStudio.OLE.Interop.IServiceProvider

[in] Pointer to the IServiceProvider interface. Can be nulla null reference (Nothing in Visual Basic). 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
Type: String

[in] Tool window caption.

pfDefaultPosition
Type: array<Int32[]

[out] Pointer to the default position of the tool window. Can be nulla null reference (Nothing in Visual Basic), 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
Type: Microsoft.VisualStudio.Shell.Interop.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.

Return Value

Type: 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.

.NET Framework Security

Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.

Partager via