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 = "FullTrust")]
[PermissionSetAttribute(SecurityAction::LinkDemand, Name = "FullTrust")]
public ref class ToolboxItem : ISerializable

NameDescription
System_CAPS_pubmethodToolboxItem()

Initializes a new instance of the ToolboxItem class.

System_CAPS_pubmethodToolboxItem(Type^)

Initializes a new instance of the ToolboxItem class that creates the specified type of component.

NameDescription
System_CAPS_pubpropertyAssemblyName

Gets or sets the name of the assembly that contains the type or types that the toolbox item creates.

System_CAPS_pubpropertyBitmap

Gets or sets a bitmap to represent the toolbox item in the toolbox.

System_CAPS_pubpropertyCompany

Gets or sets the company name for this ToolboxItem.

System_CAPS_pubpropertyComponentType

Gets the component type for this ToolboxItem.

System_CAPS_pubpropertyDependentAssemblies

Gets or sets the AssemblyName for the toolbox item.

System_CAPS_pubpropertyDescription

Gets or sets the description for this ToolboxItem.

System_CAPS_pubpropertyDisplayName

Gets or sets the display name for the toolbox item.

System_CAPS_pubpropertyFilter

Gets or sets the filter that determines whether the toolbox item can be used on a destination component.

System_CAPS_pubpropertyIsTransient

Gets a value indicating whether the toolbox item is transient.

System_CAPS_pubpropertyLocked

Gets a value indicating whether the ToolboxItem is currently locked.

System_CAPS_pubpropertyOriginalBitmap

Gets or sets the original bitmap that will be used in the toolbox for this item.

System_CAPS_pubpropertyProperties

Gets a dictionary of properties.

System_CAPS_pubpropertyTypeName

Gets or sets the fully qualified name of the type of IComponent that the toolbox item creates when invoked.

System_CAPS_pubpropertyVersion

Gets the version for this ToolboxItem.

NameDescription
System_CAPS_protmethodCheckUnlocked()

Throws an exception if the toolbox item is currently locked.

System_CAPS_pubmethodCreateComponents()

Creates the components that the toolbox item is configured to create.

System_CAPS_pubmethodCreateComponents(IDesignerHost^)

Creates the components that the toolbox item is configured to create, using the specified designer host.

System_CAPS_pubmethodCreateComponents(IDesignerHost^, IDictionary^)

Creates the components that the toolbox item is configured to create, using the specified designer host and default values.

System_CAPS_protmethodCreateComponentsCore(IDesignerHost^)

Creates a component or an array of components when the toolbox item is invoked.

System_CAPS_protmethodCreateComponentsCore(IDesignerHost^, IDictionary^)

Creates an array of components when the toolbox item is invoked.

System_CAPS_protmethodDeserialize(SerializationInfo^, StreamingContext)

Loads the state of the toolbox item from the specified serialization information object.

System_CAPS_pubmethodEquals(Object^)

Determines whether two ToolboxItem instances are equal.(Overrides Object::Equals(Object^).)

System_CAPS_protmethodFilterPropertyValue(String^, Object^)

Filters a property value before returning it.

System_CAPS_protmethodFinalize()

Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)

System_CAPS_pubmethodGetHashCode()

Returns the hash code for this instance.(Overrides Object::GetHashCode().)

System_CAPS_pubmethodGetType()

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_pubmethodGetType(IDesignerHost^)

Enables access to the type associated with the toolbox item.

System_CAPS_protmethodGetType(IDesignerHost^, AssemblyName^, String^, Boolean)

Creates an instance of the specified type, optionally using a specified designer host and assembly name.

System_CAPS_pubmethodInitialize(Type^)

Initializes the current toolbox item with the specified type to create.

System_CAPS_pubmethodLock()

Locks the toolbox item and prevents changes to its properties.

System_CAPS_protmethodMemberwiseClone()

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_protmethodOnComponentsCreated(ToolboxComponentsCreatedEventArgs^)

Raises the ComponentsCreated event.

System_CAPS_protmethodOnComponentsCreating(ToolboxComponentsCreatingEventArgs^)

Raises the ComponentsCreating event.

System_CAPS_protmethodSerialize(SerializationInfo^, StreamingContext)

Saves the state of the toolbox item to the specified serialization information object.

System_CAPS_pubmethodToString()

Returns a String that represents the current ToolboxItem.(Overrides Object::ToString().)

System_CAPS_protmethodValidatePropertyType(String^, Object^, Type^, Boolean)

Validates that an object is of a given type.

System_CAPS_protmethodValidatePropertyValue(String^, Object^)

Validates a property before it is assigned to the property dictionary.

NameDescription
System_CAPS_pubeventComponentsCreated

Occurs immediately after components are created.

System_CAPS_pubeventComponentsCreating

Occurs when components are about to be created.

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.

NamedPermissionSet

for full access to system resources. Demand values: LinkDemand, InheritanceDemand. Associated state:

.NET Framework
Available since 1.1

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

Return to top
Show: