Windows2.CreateToolWindow2 Method

  • Article

Creates a new tool window and hosts a user-defined, .NET control in it.

Namespace:  EnvDTE80
Assembly:  EnvDTE80 (in EnvDTE80.dll)

Syntax

'Declaration
Function CreateToolWindow2 ( _
    Addin As AddIn, _
    Assembly As String, _
    Class As String, _
    Caption As String, _
    GuidPosition As String, _
    <OutAttribute> ByRef ControlObject As Object _
) As Window

Window CreateToolWindow2(
    AddIn Addin,
    string Assembly,
    string Class,
    string Caption,
    string GuidPosition,
    out Object ControlObject
)

Window^ CreateToolWindow2(
    AddIn^ Addin, 
    String^ Assembly, 
    String^ Class, 
    String^ Caption, 
    String^ GuidPosition, 
    [InAttribute] [OutAttribute] Object^% ControlObject
)

abstract CreateToolWindow2 : 
        Addin:AddIn * 
        Assembly:string * 
        Class:string * 
        Caption:string * 
        GuidPosition:string * 
        ControlObject:Object byref -> Window

function CreateToolWindow2(
    Addin : AddIn, 
    Assembly : String, 
    Class : String, 
    Caption : String, 
    GuidPosition : String, 
    ControlObject : Object
) : Window

Parameters

  • Addin
    Type: EnvDTE.AddIn

    An instance of the Add-in creating the tool window.

  • Assembly
    Type: String

    The full name or file path of the assembly containing the User control.

  • Class
    Type: String

    The full name of the class implementing the User control.

  • Caption
    Type: String

    The caption to display in the new tool window.

  • GuidPosition
    Type: String

    A unique identifier for the new window. (This can be used to locate the window in the Windows collection.)

  • ControlObject
    Type: Object%

    The User control to be hosted in the new tool window.

Return Value

Type: EnvDTE.Window
A Window object.

Remarks

Before invoking CreateToolWindow2 to create a new tool window, you should either move the User control (ControlObject) into the same assembly as the add-in, or set all of the attributes on the User control to make it fully visible to COM. (For example, checking the Register for COM interop option in the project's compile options.) If you do not do this, then the control will not marshal correctly and CreateToolWindow2 will return a null value.

If you attempt to set visibility states of the new tool window — such as height, width, or position — before the tool window is visible, you get an error. Make sure that the window is visible before attempting to set any such properties.

For more examples of how to use this method, see the ToolWindow sample on the Visual Studio Automation Samples Web page: https://www.microsoft.com/downloads/details.aspx?familyid=3ff9c915-30e5-430e-95b3-621dccd25150&displaylang=en. For information about creating ActiveX controls, see Creating an MFC ActiveX Control.

Examples

The following example requires that you first create a User control by building a Windows Control Library project. Note the name of the control's project and class for use in the following code. Change the assemblypath string to the directory of the User control's DLL file. Also, the code is designed to replace the OnConnection method of an add-in project.

[C#]

public void OnConnection(object application, ext_ConnectMode 
  connectMode, object addInInst, ref Array custom)
{
    _applicationObject = (DTE2)application;
    _addInInstance = (AddIn)addInInst;
    EnvDTE80.Windows2 wins2obj;
    AddIn addinobj;
    object ctlobj = null;
    Window newWinobj;

    // A toolwindow must be connected to an add-in, so this line 
    // references one.
    addinobj = _applicationObject.AddIns.Item(1);
    wins2obj = (Windows2)_applicationObject.Windows;

    // This section specifies the path and class name of the windows 
    // control that you want to host in the new tool window, as well as 
    // its caption and a unique GUID.
    string assemblypath = "C:\\temp\\WindowsControlLibrary1.dll";
    string classname = "WindowsControlLibrary1.UserControl1";
    string guidpos = "{426E8D27-3D33-4FC8-B3E9-9883AADC679F}";
    string caption = "CreateToolWindow2 Test";

    // Create the new tool window and insert the user control in it.
    newWinobj = wins2obj.CreateToolWindow2(addinobj, assemblypath, 
      classname, caption, guidpos, ref ctlobj);
    newWinobj.Visible = true;
}

.NET Framework Security

See Also

Reference

Windows2 Interface

EnvDTE80 Namespace

Other Resources

How to: Create and Control Tool Windows

How to: Compile and Run the Automation Object Model Code Examples