ToolboxItem Class

Provides a base implementation of a toolbox item.

For a list of all members of this type, see ToolboxItem Members.

System.Object
System.Drawing.Design.ToolboxItem
System.Web.UI.Design.WebControlToolboxItem

[Visual Basic]
<Serializable>
Public Class ToolboxItem
   Implements ISerializable
[C#]
[Serializable]
public class ToolboxItem : ISerializable
[C++]
[Serializable]
public __gc class ToolboxItem : public ISerializable
[JScript]
public
   Serializable
class ToolboxItem implements ISerializable

Thread Safety

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

Remarks

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, depending 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.

Example

[Visual Basic, C#, C++] The following example provides a component that uses the IToolboxService 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 System.Windows.Forms.TextBox containing the text.

[Visual Basic] 
Imports System
Imports System.ComponentModel
Imports System.ComponentModel.Design
Imports System.Drawing
Imports System.Drawing.Design
Imports System.Windows.Forms

' Component that adds a "Text" data format ToolboxItemCreatorCallback 
' to the Toolbox that creates a custom ToolboxItem that 
' creates a TextBox containing the text data.
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 Not (Value Is 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 Not (ts Is 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 Not (ts Is 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 formats As String() = CType(serializedObject, System.Windows.Forms.DataObject).GetFormats()
        If CType(serializedObject, System.Windows.Forms.DataObject).GetDataPresent("System.String", True) Then
            Return New TextToolboxItem(CStr(CType(serializedObject, System.Windows.Forms.DataObject).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.
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.
    <System.Security.Permissions.PermissionSetAttribute(System.Security.Permissions.SecurityAction.Demand, Name:="FullTrust")> _
    Protected Overrides Function CreateComponentsCore(ByVal host As System.ComponentModel.Design.IDesignerHost) As System.ComponentModel.IComponent()
        Dim textbox As System.Windows.Forms.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

[C#] 
using System;
using System.ComponentModel;
using System.ComponentModel.Design;
using System.Drawing;
using System.Drawing.Design;
using System.Windows.Forms;

namespace TextDataTextBoxComponent
{
    // Component that adds a "Text" data format ToolboxItemCreatorCallback 
    // to the Toolbox that creates a custom ToolboxItem that 
    // creates a TextBox containing the text data.
    public class TextDataTextBoxComponent : System.ComponentModel.Component
    {
        private bool creatorAdded = false;
        private IToolboxService ts;

        public TextDataTextBoxComponent()
        {                     
        }

        // ISite override to register TextBox creator
        public override System.ComponentModel.ISite Site
        {
            get
            {
                return base.Site;
            }
            set
            {
                if( value != null )
                {                    
                    base.Site = value;
                    if( !creatorAdded )
                        AddTextTextBoxCreator();                    
                }
                else
                {
                    if( creatorAdded )
                        RemoveTextTextBoxCreator();
                    base.Site = value;             
                }
            }
        }

        // Adds a "Text" data format creator to the toolbox that creates 
        // a textbox from a text fragment pasted to the toolbox.
        private void AddTextTextBoxCreator()
        {
            ts = (IToolboxService)GetService(typeof(IToolboxService));
            if (ts != null) 
            {
                ToolboxItemCreatorCallback textCreator = new ToolboxItemCreatorCallback(this.CreateTextBoxForText);
                try
                {
                    ts.AddCreator(textCreator, "Text", (IDesignerHost)GetService(typeof(IDesignerHost)));
                    creatorAdded = true;
                }
                catch(Exception ex)
                {
                    MessageBox.Show(ex.ToString(), "Exception Information");
                }                
            }
        }

        // Removes any "Text" data format creator from the toolbox.
        private void RemoveTextTextBoxCreator()
        {
            if (ts != null)             
            {
                ts.RemoveCreator("Text", (IDesignerHost)GetService(typeof(IDesignerHost)));            
                creatorAdded = false;
            }
        }

        // ToolboxItemCreatorCallback delegate format method to create 
        // the toolbox item.
        private ToolboxItem CreateTextBoxForText(object serializedObject, string format)
        {
            string[] formats = ((System.Windows.Forms.DataObject)serializedObject).GetFormats();
            if( ((System.Windows.Forms.DataObject)serializedObject).GetDataPresent("System.String", true) )           
                return new TextToolboxItem( (string)((System.Windows.Forms.DataObject)serializedObject).GetData("System.String", true) );            
            return null;
        }

        protected override void Dispose(bool disposing)
        {
            if( creatorAdded )
                RemoveTextTextBoxCreator();
        }        
    }

    // Custom toolbox item creates a TextBox and sets its Text property
    // to the constructor-specified text.
    public class TextToolboxItem : System.Drawing.Design.ToolboxItem
    {
        private string text;
        private delegate void SetTextMethodHandler(Control c, string text);

        public TextToolboxItem(string text) : base()
        {
            this.text = text;
        }

        // ToolboxItem.CreateComponentsCore override to create the TextBox 
        // and link a method to set its Text property.
        [System.Security.Permissions.PermissionSet(System.Security.Permissions.SecurityAction.Demand, Name="FullTrust")] 
        protected override System.ComponentModel.IComponent[] CreateComponentsCore(System.ComponentModel.Design.IDesignerHost host)
        {
            System.Windows.Forms.TextBox textbox = (TextBox)host.CreateComponent(typeof(TextBox));
                
            // Because the designer resets the text of the textbox, use 
            // a SetTextMethodHandler to set the text to the value of 
            // the text data.
            Control c = host.RootComponent as Control;
            c.BeginInvoke(new SetTextMethodHandler(OnSetText), new object[] {textbox, text});
           
            return new System.ComponentModel.IComponent[] { textbox };
        }        

        // Method to set the text property of a TextBox after it is initialized.
        private void OnSetText(Control c, string text) 
        {
            c.Text = text;
        }
    }
}

[C++] 
#using <mscorlib.dll>
#using <System.Windows.Forms.dll>
#using <System.Drawing.dll>
#using <System.dll>

using namespace System;
using namespace System::ComponentModel;
using namespace System::ComponentModel::Design;
using namespace System::Drawing;
using namespace System::Drawing::Design;
using namespace System::Windows::Forms;

namespace TextDataTextBoxComponent {

   // Custom toolbox item creates a TextBox and sets its Text property
   // to the constructor-specified text.
public __gc class TextToolboxItem : public System::Drawing::Design::ToolboxItem {
private:
   String*  text;
   __delegate void SetTextMethodHandler(Control* c, String*  text);

public:
   TextToolboxItem(String* text) : ToolboxItem() {
      this->text = text;
   }

   // ToolboxItem::CreateComponentsCore  to create the TextBox
   // and link a method to set its Text property.
protected:
   [System::Security::Permissions::PermissionSet(System::Security::Permissions::SecurityAction::Demand, Name="FullTrust")]
   System::ComponentModel::IComponent* CreateComponentsCore(System::ComponentModel::Design::IDesignerHost* host)[] {
      System::Windows::Forms::TextBox* textbox = dynamic_cast<TextBox*>(host->CreateComponent(__typeof(TextBox)));

      // Because the designer resets the text of the textbox, use
      // a SetTextMethodHandler to set the text to the value of
      // the text data.
      Control* c = dynamic_cast<Control*>(host->RootComponent);

      Object* temp0 [] = {textbox, text};
      c->BeginInvoke(new SetTextMethodHandler(this, OnSetText), temp0);

      System::ComponentModel::IComponent* temp1 [] = {textbox};
      return temp1;
   }

   // Method to set the text property of a TextBox after it is initialized.
private:
   void OnSetText(Control* c, String* text) {
      c->Text = text;
   }
};

// Component that adds a S"Text" data format ToolboxItemCreatorCallback
// to the Toolbox that creates a custom ToolboxItem that
// creates a TextBox containing the text data.
public __gc class TextDataTextBoxComponent : public System::ComponentModel::Component {
private:
   bool  creatorAdded;
   IToolboxService*  ts;

public:
   TextDataTextBoxComponent() {
      creatorAdded = false;
   }

   // ISite*  to register TextBox creator
   __property System::ComponentModel::ISite* get_Site() {
      return Component::get_Site();
   }
   __property void set_Site(System::ComponentModel::ISite* value) {
      if (value != 0) {
         Component::set_Site(value);
         if (!creatorAdded)
            AddTextTextBoxCreator();
      } else {
         if (creatorAdded)
            RemoveTextTextBoxCreator();
         Component::set_Site(value);
      }
   }

   // Adds a "Text" data format creator to the toolbox that creates
   // a textbox from a text fragment pasted to the toolbox.
private:
   void AddTextTextBoxCreator() {
      ts = dynamic_cast<IToolboxService*>(GetService(__typeof(IToolboxService)));
      if (ts != 0) {
         ToolboxItemCreatorCallback* textCreator = new ToolboxItemCreatorCallback(this, CreateTextBoxForText);
         try {
            ts->AddCreator(textCreator, S"Text", dynamic_cast<IDesignerHost*>(GetService(__typeof(IDesignerHost))));
            creatorAdded = true;
         } catch (Exception* ex) {
            MessageBox::Show(ex->ToString(), S"Exception Information");
         }
      }
   }

   // Removes any "Text" data format creator from the toolbox.
   void RemoveTextTextBoxCreator() {
      if (ts != 0) {
         ts->RemoveCreator(S"Text", dynamic_cast<IDesignerHost*>(GetService(__typeof(IDesignerHost))));
         creatorAdded = false;
      }
   }

   // ToolboxItemCreatorCallback delegate format method to create
   // the toolbox item.
   ToolboxItem* CreateTextBoxForText(Object* serializedObject, String* format) {
      String* formats[] = (dynamic_cast<System::Windows::Forms::DataObject*>(serializedObject))->GetFormats();
      if ((dynamic_cast<System::Windows::Forms::DataObject*>(serializedObject))->GetDataPresent(S"System::String", true))
         return new TextToolboxItem(dynamic_cast<String*>((dynamic_cast<System::Windows::Forms::DataObject*>(serializedObject))->GetData(S"System::String", true)));
      return 0;
   }

protected:
   void Dispose(bool disposing) {
      if (creatorAdded)
         RemoveTextTextBoxCreator();
   }
};

}

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button in the upper-left corner of the page.

Requirements

Namespace: System.Drawing.Design

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family

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

ToolboxItem Class

Thread Safety

Remarks

Example

Requirements

See Also