ToolBoxItems.Add(String, Object, vsToolBoxItemFormat) Method

Definition

Namespace:

EnvDTE

Assembly:

Microsoft.VisualStudio.Interop.dll

Package:

Microsoft.VisualStudio.Interop v17.12.40391

Creates a new item and adds it to the ToolBox.

EnvDTE::ToolBoxItem Add(std::wstring const & Name, winrt::Windows::Foundation::IInspectable const & Data, EnvDTE::vsToolBoxItemFormat Format = EnvDTE.vsToolBoxItemFormat.vsToolBoxItemFormatText);

[System.Runtime.InteropServices.DispId(4)]
public EnvDTE.ToolBoxItem Add (string Name, object Data, EnvDTE.vsToolBoxItemFormat Format = EnvDTE.vsToolBoxItemFormat.vsToolBoxItemFormatText);

[<System.Runtime.InteropServices.DispId(4)>]
abstract member Add : string * obj * EnvDTE.vsToolBoxItemFormat -> EnvDTE.ToolBoxItem

Public Function Add (Name As String, Data As Object, Optional Format As vsToolBoxItemFormat = EnvDTE.vsToolBoxItemFormat.vsToolBoxItemFormatText) As ToolBoxItem

Parameters

Name

String

Required. A string representing the caption of the new item.

Data

Object

Required. A variant representing the string, control, or other item to be added to the ToolBox.

Format

vsToolBoxItemFormat

Optional. A vsToolBoxItemFormat constant indicating the format of the new item.

Returns

ToolBoxItem

A ToolBoxItem object.

Attributes

DispIdAttribute

Examples

The following example demonstrates how to add a text document to the ToolBox:

Sub ToolBoxAddExample1()  
    ' This adds a Text item to the first tab of the ToolBox.  
    ' Define the variables and create an object reference to the IDE's    
    ' ToolBox object.  
    Dim win As Window = DTE.Windows.Item(Constants.vsWindowKindToolbox)  
    Dim tlbox As ToolBox = win.Object  
    Dim tbxTabs As ToolBoxTabs  

    ' Create an object reference to the ToolBoxTabs object.  
    tbxTabs = tlbox.ToolBoxTabs  

    ' Add a new Text item to the first tab in the ToolBox.  
    tbxTabs.Item(1).ToolBoxItems.Add("New Text Item", "Some text to _  
    add to the document.", vsToolBoxItemFormat.vsToolBoxItemFormatText)  
End Sub  

The following example demonstrates how to add a .NET component to the ToolBox by using a path to the file. The component to be added must be a .NET control, such as a Visual Basic Windows Control Library component.

Sub ToolBoxItemAddExample2()  
    Try  
        Dim tlBox As ToolBox  
        tlBox = CType(DTE.Windows.Item(Constants. _  
        vsWindowKindToolbox).Object, EnvDTE.ToolBox)  
        ' Create a new tab called "My Controls."  
        Dim tlBoxTab As ToolBoxTab = tlBox.ToolBoxTabs. _  
        Add("My Controls")  
        ' Set focus to the new Toolbox tab.  
        tlBoxTab.Activate()  
        ' Add a .NET control as a new control in the new ToolBox tab.   
        ' The constant "vsToolBoxItemFormatDotNETComponent" alerts the   
        ' ToolBox to the type of control you are adding.  
        tlBoxTab.ToolBoxItems.Add("MyDotNetControl", _  
        "C:\Libraries\ADotNetControl.dll", _  
        vsToolBoxItemFormat.vsToolBoxItemFormatDotNETComponent)  
    Catch ex As System.Exception  
        ' Display any errors that occur.  
        MsgBox("ERROR: " & ex.Message)  
    End Try  
End Sub  

Remarks

This method fails if the ToolBoxItems collection belongs to a ToolBoxTab object that has been deleted, or if you attempt to add a tab with a name that already exists.

For the Data argument, Visual C++ users can pass the IUnknown of the IDataObject.

When adding an assembly of Format type vsToolBoxItemFormatDotNETComponent, the value passed to the Data parameter can be in either of the following formats:

• <AssemblyPath>—Where "<AssemblyPath>" is a path and file name pointing to a managed assembly, such as C:\Libraries\MyAssembly.dll. When you use this format, all classes within the .DLL are added to the ToolBox.

• <AssemblyNameInTheGAC>—A single class listed as an assembly-qualified reference. Single classes can be added as controls, provided they are references to an assembly that is in the global assembly cache (GAC), such as: WindowControlLibrary1.UserControl1, WindowControlLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=<Your Token>. (You would replace <Your Token> with your public key token, which is required to add your assembly to the GAC.)