Export (0) Print
Expand All

ToolboxItem Class

Provides a base implementation of a toolbox item.

Namespace:  System.Drawing.Design
Assembly:  System.Drawing (in System.Drawing.dll)

'Declaration
<SerializableAttribute> _
<PermissionSetAttribute(SecurityAction.InheritanceDemand, Name := "FullTrust")> _
<PermissionSetAttribute(SecurityAction.LinkDemand, Name := "FullTrust")> _
Public Class ToolboxItem _
	Implements ISerializable
'Usage
Dim instance As ToolboxItem

ToolboxItem is a base class for toolbox items that can be displayed in the toolbox of a design-time environment. A toolbox item typically represents a component to create when invoked on a design mode document. The ToolboxItem class provides the methods and properties needed to provide the toolbox with the display properties for the toolbox item, to create a component or components when used, and to serialize and deserialize itself for persistence within the toolbox database.

An instance of the ToolboxItem class can be configured with a name, bitmap, and type to create, without creating a class that derives from ToolboxItem. The ToolboxItem class also provides a base class for custom toolbox item implementations. A custom ToolboxItem can create multiple components. To implement a custom toolbox item, you must derive from ToolboxItem and override the CreateComponentsCore, Serialize, and Deserialize methods.

The following properties and methods must be configured for a ToolboxItem to function correctly:

  • The DisplayName property specifies the label for the toolbox item when displayed in a toolbox.

  • The TypeName property specifies the fully qualified name of the type of the component that the item creates. If a derived class creates multiple components, the TypeName property may or may not be used, contingent on whether a CreateComponentsCore method override depends on the value of this property.

  • The AssemblyName property specifies the assembly that contains the type of a component that the item creates.

  • The Bitmap property optionally specifies a bitmap image to display next to the display name for the toolbox item in the toolbox.

  • The Filter property optionally contains any ToolboxItemFilterAttribute objects that determine whether the toolbox item can be used on a particular component.

  • The CreateComponentsCore method returns the component instance or instances to insert where this tool is used.

  • The Serialize method saves the toolbox item to a specified SerializationInfo.

  • The Deserialize method configures the toolbox item from the state information contained in the specified SerializationInfo.

  • The Initialize method configures the toolbox item to create the specified type of component, if the CreateComponentsCore method has not been overridden to behave differently.

  • The Locked property indicates whether the properties of the toolbox item can be changed. A toolbox item is typically locked after it is added to a toolbox.

  • The Lock method locks a toolbox item.

  • The CheckUnlocked method throws an exception if the Locked property is true.

The following code example provides a component that uses the IToolboxService interface to add a text data format handler, or ToolboxItemCreatorCallback, to the toolbox. The data creator callback delegate passes any text data pasted to the toolbox and dragged onto a form to a custom ToolboxItem that creates a TextBox containing the text.

Imports System
Imports System.ComponentModel
Imports System.ComponentModel.Design
Imports System.Drawing
Imports System.Drawing.Design
Imports System.Security.Permissions
Imports System.Windows.Forms

' Component that adds a "Text" data format ToolboxItemCreatorCallback  
' to the Toolbox. This component uses a custom ToolboxItem that  
' creates a TextBox containing the text data.
<PermissionSetAttribute(SecurityAction.Demand, Name:="FullTrust")> _
Public Class TextDataTextBoxComponent
    Inherits System.ComponentModel.Component

    Private creatorAdded As Boolean = False 
    Private ts As IToolboxService

    Public Sub New()
    End Sub 

    ' ISite override to register TextBox creator 
    Public Overrides Property Site() As System.ComponentModel.ISite
        Get 
            Return MyBase.Site
        End Get 
        Set(ByVal Value As System.ComponentModel.ISite)
            If (Value IsNot Nothing) Then 
                MyBase.Site = Value
                If Not creatorAdded Then
                    AddTextTextBoxCreator()
                End If 
            Else 
                If creatorAdded Then
                    RemoveTextTextBoxCreator()
                End If 
                MyBase.Site = Value
            End If 
        End Set 
    End Property 

    ' Adds a "Text" data format creator to the toolbox that creates  
    ' a textbox from a text fragment pasted to the toolbox. 
    Private Sub AddTextTextBoxCreator()
        ts = CType(GetService(GetType(IToolboxService)), IToolboxService)
        If (ts IsNot Nothing) Then 
            Dim textCreator As _
            New ToolboxItemCreatorCallback(AddressOf Me.CreateTextBoxForText)
            Try
                ts.AddCreator( _
                textCreator, _
                "Text", _
                CType(GetService(GetType(IDesignerHost)), IDesignerHost))

                creatorAdded = True 
            Catch ex As Exception
                MessageBox.Show(ex.ToString(), "Exception Information")
            End Try 
        End If 
    End Sub 

    ' Removes any "Text" data format creator from the toolbox. 
    Private Sub RemoveTextTextBoxCreator()
        If (ts IsNot Nothing) Then
            ts.RemoveCreator( _
            "Text", _
            CType(GetService(GetType(IDesignerHost)), IDesignerHost))
            creatorAdded = False 
        End If 
    End Sub 

    ' ToolboxItemCreatorCallback delegate format method to create  
    ' the toolbox item. 
    Private Function CreateTextBoxForText( _
    ByVal serializedObject As Object, _
    ByVal format As String) As ToolboxItem

        Dim o As New DataObject(CType(serializedObject, IDataObject))

        Dim formats As String() = o.GetFormats()

        If o.GetDataPresent("System.String", True) Then 

            Return New TextToolboxItem(CStr(o.GetData("System.String", True)))

        End If 

        Return Nothing 
    End Function 

    Protected Overloads Overrides Sub Dispose(ByVal disposing As Boolean)
        If creatorAdded Then
            RemoveTextTextBoxCreator()
        End If 
    End Sub 

End Class 

' Custom toolbox item creates a TextBox and sets its Text property 
' to the constructor-specified text.
<PermissionSetAttribute(SecurityAction.Demand, Name:="FullTrust")> _
Public Class TextToolboxItem
    Inherits System.Drawing.Design.ToolboxItem

    Private [text] As String 

    Delegate Sub SetTextMethodHandler( _
    ByVal c As Control, _
    ByVal [text] As String)

    Public Sub New(ByVal [text] As String)
        Me.text = [text]
    End Sub 

    ' ToolboxItem.CreateComponentsCore override to create the TextBox  
    ' and link a method to set its Text property.
    <PermissionSetAttribute(SecurityAction.Demand, Name:="FullTrust")> _
    Protected Overrides Function CreateComponentsCore(ByVal host As IDesignerHost) As IComponent()
        Dim textbox As TextBox = CType(host.CreateComponent(GetType(TextBox)), TextBox)

        ' Because the designer resets the text of the textbox, use  
        ' a SetTextMethodHandler to set the text to the value of  
        ' the text data. 
        Dim c As Control = host.RootComponent

        c.BeginInvoke( _
        New SetTextMethodHandler(AddressOf OnSetText), _
        New Object() {textbox, [text]})

        Return New System.ComponentModel.IComponent() {textbox}
    End Function 

    ' Method to set the text property of a TextBox after it is initialized. 
    Private Sub OnSetText(ByVal c As Control, ByVal [text] As String)
        c.Text = [text]
    End Sub 

End Class

The following code example demonstrates the use of the ToolboxItem class as a base class for a custom toolbox item implementation.

Imports System
Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.Drawing
Imports System.Drawing.Design
Imports System.Runtime.Serialization
Imports System.Text
Imports System.Windows.Forms



Public Class Form1
    Inherits Form
    Private components As System.ComponentModel.IContainer = Nothing 
    Friend WithEvents UserControl11 As UserControl1
    Friend WithEvents label1 As System.Windows.Forms.Label

    Public Sub New() 
        InitializeComponent()
    End Sub 


    Private Sub InitializeComponent() 
        Me.label1 = New System.Windows.Forms.Label
        Me.UserControl11 = New UserControl1
        Me.SuspendLayout()
        
        'label1 
        
        Me.label1.Location = New System.Drawing.Point(15, 16)
        Me.label1.Name = "label1" 
        Me.label1.Size = New System.Drawing.Size(265, 62)
        Me.label1.TabIndex = 0
        Me.label1.Text = "Build the project and drop UserControl1" + _
            " from the toolbox onto the form." 
        
        'UserControl11 
        
        Me.UserControl11.LabelText = "This is a custom user control.  " + _
            "The text you see here is provided by a custom too" + _
            "lbox item when the user control is dropped on the form." 
        Me.UserControl11.Location = New System.Drawing.Point(74, 85)
        Me.UserControl11.Name = "UserControl11" 
        Me.UserControl11.Padding = New System.Windows.Forms.Padding(6)
        Me.UserControl11.TabIndex = 1
        
        'Form1 
        
        Me.ClientSize = New System.Drawing.Size(292, 266)
        Me.Controls.Add(Me.UserControl11)
        Me.Controls.Add(Me.label1)
        Me.Name = "Form1" 
        Me.Text = "Form1" 
        Me.ResumeLayout(False)
    End Sub 


    Protected Overrides Sub Dispose(ByVal disposing As Boolean) 
        If disposing AndAlso (components IsNot Nothing) Then
            components.Dispose()
        End If 
        MyBase.Dispose(disposing)
    End Sub 


    Shared Sub Main() 
        Application.EnableVisualStyles()
        Application.Run(New Form1())
    End Sub 
End Class 

' Configure this user control to have a custom toolbox item.
<ToolboxItem(GetType(MyToolboxItem))> _
Public Class UserControl1
    Inherits UserControl
    Private components As System.ComponentModel.IContainer = Nothing 
    Private label1 As System.Windows.Forms.Label


    Public Sub New()
        InitializeComponent()
    End Sub 


    Public Property LabelText() As String 
        Get 
            Return label1.Text
        End Get 
        Set(ByVal value As String)
            label1.Text = Value
        End Set 
    End Property 


    Private Sub InitializeComponent()
        Me.label1 = New System.Windows.Forms.Label()
        Me.SuspendLayout()
        '  
        ' label1 
        '  
        Me.label1.Dock = System.Windows.Forms.DockStyle.Fill
        Me.label1.Location = New System.Drawing.Point(6, 6)
        Me.label1.Name = "label1" 
        Me.label1.Size = New System.Drawing.Size(138, 138)
        Me.label1.TabIndex = 0
        Me.label1.Text = "This is a custom user control.  " + _
            "The text you see here is provided by a custom toolbox" + _
            " item when the user control is dropped on the form." + _
            vbCr + vbLf
        Me.label1.TextAlign = System.Drawing.ContentAlignment.MiddleCenter
        '  
        ' UserControl1 
        '  
        Me.Controls.Add(label1)
        Me.Name = "UserControl1" 
        Me.Padding = New System.Windows.Forms.Padding(6)
        Me.ResumeLayout(False)
    End Sub 


    Protected Overrides Sub Dispose(ByVal disposing As Boolean)
        If disposing AndAlso (components IsNot Nothing) Then
            components.Dispose()
        End If 
        MyBase.Dispose(disposing)
    End Sub 
End Class 

' Toolbox items must be serializable.
<Serializable()> _
Class MyToolboxItem
    Inherits ToolboxItem

    ' The add components dialog in Visual Studio looks for a public 
    ' constructor that takes a type. 
    Public Sub New(ByVal toolType As Type)
        MyBase.New(toolType)
    End Sub 


    ' And you must provide this special constructor for serialization. 
    ' If you add additional data to MyToolboxItem that you 
    ' want to serialize, you may override Deserialize and 
    ' Serialize methods to add that data.   
    Sub New(ByVal info As SerializationInfo, _
        ByVal context As StreamingContext)
        Deserialize(info, context)
    End Sub 


    ' Let's override the creation code and pop up a dialog. 
    Protected Overrides Function CreateComponentsCore( _
        ByVal host As System.ComponentModel.Design.IDesignerHost, _
        ByVal defaultValues As System.Collections.IDictionary) _
        As IComponent()
        ' Get the string we want to fill in the custom 
        ' user control.  If the user cancels out of the dialog, 
        ' return null or an empty array to signify that the  
        ' tool creation was canceled. 
        Using d As New ToolboxItemDialog()
            If d.ShowDialog() = DialogResult.OK Then 
                Dim [text] As String = d.CreationText
                Dim comps As IComponent() = _
                    MyBase.CreateComponentsCore(host, defaultValues)
                ' comps will have a single component: our data type.
                CType(comps(0), UserControl1).LabelText = [text]
                Return comps
            Else 
                Return Nothing 
            End If 
        End Using 
    End Function 
End Class 


Public Class ToolboxItemDialog
    Inherits Form
    Private components As System.ComponentModel.IContainer = Nothing 
    Private label1 As System.Windows.Forms.Label
    Private textBox1 As System.Windows.Forms.TextBox
    Private button1 As System.Windows.Forms.Button
    Private button2 As System.Windows.Forms.Button


    Public Sub New() 
        InitializeComponent()
    End Sub 

    Private Sub InitializeComponent() 
        Me.label1 = New System.Windows.Forms.Label()
        Me.textBox1 = New System.Windows.Forms.TextBox()
        Me.button1 = New System.Windows.Forms.Button()
        Me.button2 = New System.Windows.Forms.Button()
        Me.SuspendLayout()
        '  
        ' label1 
        '  
        Me.label1.Location = New System.Drawing.Point(10, 9)
        Me.label1.Name = "label1" 
        Me.label1.Size = New System.Drawing.Size(273, 43)
        Me.label1.TabIndex = 0
        Me.label1.Text = "Enter the text you would like" + _
            " to have the user control populated with:" 
        '  
        ' textBox1 
        '  
        Me.textBox1.AutoSize = False 
        Me.textBox1.Location = New System.Drawing.Point(10, 58)
        Me.textBox1.Multiline = True 
        Me.textBox1.Name = "textBox1" 
        Me.textBox1.Size = New System.Drawing.Size(270, 67)
        Me.textBox1.TabIndex = 1
        Me.textBox1.Text = "This is a custom user control.  " + _
            "The text you see here is provided by a custom toolbox" + _
            " item when the user control is dropped on the form." 
        '  
        ' button1 
        '  
        Me.button1.DialogResult = System.Windows.Forms.DialogResult.OK
        Me.button1.Location = New System.Drawing.Point(124, 131)
        Me.button1.Name = "button1" 
        Me.button1.TabIndex = 2
        Me.button1.Text = "OK" 
        '  
        ' button2 
        '  
        Me.button2.DialogResult = System.Windows.Forms.DialogResult.Cancel
        Me.button2.Location = New System.Drawing.Point(205, 131)
        Me.button2.Name = "button2" 
        Me.button2.TabIndex = 3
        Me.button2.Text = "Cancel" 
        '  
        ' ToolboxItemDialog 
        '  
        Me.AcceptButton = Me.button1
        Me.CancelButton = Me.button2
        Me.ClientSize = New System.Drawing.Size(292, 162)
        Me.ControlBox = False 
        Me.Controls.Add(button2)
        Me.Controls.Add(button1)
        Me.Controls.Add(textBox1)
        Me.Controls.Add(label1)
        Me.FormBorderStyle = _
            System.Windows.Forms.FormBorderStyle.FixedDialog
        Me.Name = "ToolboxItemDialog" 
        Me.Text = "ToolboxItemDialog" 
        Me.ResumeLayout(False)

    End Sub 

    Public ReadOnly Property CreationText() As String  
        Get 
            Return textBox1.Text
        End Get 
    End Property 


    Protected Overrides Sub Dispose(ByVal disposing As Boolean) 
        If disposing AndAlso (components IsNot Nothing) Then
            components.Dispose()
        End If 
        MyBase.Dispose(disposing)

    End Sub 
End Class

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0

Community Additions

ADD
Show:
© 2014 Microsoft