This documentation is archived and is not being maintained.

ToolboxItem Class

Provides a base implementation of a toolbox item.

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

[SerializableAttribute]
[PermissionSetAttribute(SecurityAction::InheritanceDemand, Name = L"FullTrust")]
[PermissionSetAttribute(SecurityAction::LinkDemand, Name = L"FullTrust")]
public ref class ToolboxItem : ISerializable

The ToolboxItem type exposes the following members.

  NameDescription
Public methodToolboxItem()Initializes a new instance of the ToolboxItem class.
Public methodToolboxItem(Type)Initializes a new instance of the ToolboxItem class that creates the specified type of component.
Top

  NameDescription
Public propertyAssemblyNameGets or sets the name of the assembly that contains the type or types that the toolbox item creates.
Public propertyBitmapGets or sets a bitmap to represent the toolbox item in the toolbox.
Public propertyCompanyGets or sets the company name for this ToolboxItem.
Public propertyComponentTypeGets the component type for this ToolboxItem.
Public propertyDependentAssembliesGets or sets the AssemblyName for the toolbox item.
Public propertyDescriptionGets or sets the description for this ToolboxItem.
Public propertyDisplayNameGets or sets the display name for the toolbox item.
Public propertyFilterGets or sets the filter that determines whether the toolbox item can be used on a destination component.
Public propertyIsTransientGets a value indicating whether the toolbox item is transient.
Public propertyLockedGets a value indicating whether the ToolboxItem is currently locked.
Public propertyPropertiesGets a dictionary of properties.
Public propertyTypeNameGets or sets the fully qualified name of the type of IComponent that the toolbox item creates when invoked.
Public propertyVersionGets the version for this ToolboxItem.
Top

  NameDescription
Protected methodCheckUnlockedThrows an exception if the toolbox item is currently locked.
Public methodCreateComponents()Creates the components that the toolbox item is configured to create.
Public methodCreateComponents(IDesignerHost)Creates the components that the toolbox item is configured to create, using the specified designer host.
Public methodCreateComponents(IDesignerHost, IDictionary)Creates the components that the toolbox item is configured to create, using the specified designer host and default values.
Protected methodCreateComponentsCore(IDesignerHost)Creates a component or an array of components when the toolbox item is invoked.
Protected methodCreateComponentsCore(IDesignerHost, IDictionary)Creates an array of components when the toolbox item is invoked.
Protected methodDeserializeLoads the state of the toolbox item from the specified serialization information object.
Public methodEqualsDetermines whether two ToolboxItem instances are equal. (Overrides Object::Equals(Object).)
Protected methodFilterPropertyValueFilters a property value before returning it.
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetHashCodeReturns the hash code for this instance. (Overrides Object::GetHashCode().)
Public methodGetType()Gets the Type of the current instance. (Inherited from Object.)
Public methodGetType(IDesignerHost)Enables access to the type associated with the toolbox item.
Protected methodGetType(IDesignerHost, AssemblyName, String, Boolean)Creates an instance of the specified type, optionally using a specified designer host and assembly name.
Public methodInitializeInitializes the current toolbox item with the specified type to create.
Public methodLockLocks the toolbox item and prevents changes to its properties.
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Protected methodOnComponentsCreatedRaises the ComponentsCreated event.
Protected methodOnComponentsCreatingRaises the ComponentsCreating event.
Protected methodSerializeSaves the state of the toolbox item to the specified serialization information object.
Public methodToStringReturns a String that represents the current ToolboxItem. (Overrides Object::ToString().)
Protected methodValidatePropertyTypeValidates that an object is of a given type.
Protected methodValidatePropertyValueValidates a property before it is assigned to the property dictionary.
Top

  NameDescription
Public eventComponentsCreatedOccurs immediately after components are created.
Public eventComponentsCreatingOccurs when components are about to be created.
Top

  NameDescription
Explicit interface implemetationPrivate methodISerializable::GetObjectDataFor a description of this member, see the GetObjectData method.
Top

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.


#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;
using namespace System::Security::Permissions;

namespace TextDataTextBoxComponent
{
   // Custom toolbox item creates a TextBox and sets its Text property
   // to the constructor-specified text.
   [PermissionSetAttribute(SecurityAction::Demand, Name="FullTrust")]
   public ref class TextToolboxItem: public ToolboxItem
   {
   private:
      String^ text;
      delegate void SetTextMethodHandler( Control^ c, String^ text );

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

   protected:

      // ToolboxItem::CreateComponentsCore  to create the TextBox
      // and link a method to set its Text property.

      virtual array<IComponent^>^ CreateComponentsCore( IDesignerHost^ host ) override
      {
         TextBox^ textbox = dynamic_cast<TextBox^>(host->CreateComponent( TextBox::typeid ));

         // 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);
         array<Object^>^temp0 = {textbox,text};
         c->BeginInvoke( gcnew SetTextMethodHandler( this, &TextToolboxItem::OnSetText ), temp0 );
         array<IComponent^>^temp1 = {textbox};
         return temp1;
      }

   private:

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

   };


   // 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.
   public ref class TextDataTextBoxComponent: public Component
   {
   private:
      bool creatorAdded;
      IToolboxService^ ts;

   public:
      TextDataTextBoxComponent()
      {
         creatorAdded = false;
      }


      property System::ComponentModel::ISite^ Site 
      {
         // ISite to register TextBox creator
         virtual System::ComponentModel::ISite^ get() override
         {
            return __super::Site;
         }

         virtual void set( System::ComponentModel::ISite^ value ) override
         {
            if ( value != nullptr )
            {
               __super::Site = value;
               if (  !creatorAdded )
                              AddTextTextBoxCreator();
            }
            else
            {
               if ( creatorAdded )
                              RemoveTextTextBoxCreator();
               __super::Site = value;
            }
         }
      }

   private:

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


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


      // ToolboxItemCreatorCallback delegate format method to create
      // the toolbox item.
      ToolboxItem^ CreateTextBoxForText( Object^ serializedObject, String^ format )
      {
		IDataObject^ o = gcnew DataObject(dynamic_cast<IDataObject^>(serializedObject));

		if( o->GetDataPresent("System::String", true) )
		{
			String^ toolboxText = dynamic_cast<String^>(o->GetData( "System::String", true ));
		   return( gcnew TextToolboxItem( toolboxText ));
		}

		return nullptr;
	  }

   public:
      ~TextDataTextBoxComponent()
      {
         if ( creatorAdded )
                  RemoveTextTextBoxCreator();
      }
   };
}


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

No code example is currently available or this language may not be supported.

.NET Framework

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

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

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

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