Export (0) Print
Expand All

IToolboxService Interface

Provides methods and properties to manage and query the toolbox in the development environment.

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

[InterfaceTypeAttribute(ComInterfaceType.InterfaceIsIUnknown)]
[GuidAttribute("4BACD258-DE64-4048-BC4E-FEDBEF9ACB76")]
public interface IToolboxService

The IToolboxService type exposes the following members.

  NameDescription
Public propertyCategoryNamesGets the names of all the tool categories currently on the toolbox.
Public propertySelectedCategoryGets or sets the name of the currently selected tool category from the toolbox.
Top

  NameDescription
Public methodAddCreator(ToolboxItemCreatorCallback, String)Adds a new toolbox item creator for a specified data format.
Public methodAddCreator(ToolboxItemCreatorCallback, String, IDesignerHost)Adds a new toolbox item creator for a specified data format and designer host.
Public methodAddLinkedToolboxItem(ToolboxItem, IDesignerHost)Adds the specified project-linked toolbox item to the toolbox.
Public methodAddLinkedToolboxItem(ToolboxItem, String, IDesignerHost)Adds the specified project-linked toolbox item to the toolbox in the specified category.
Public methodAddToolboxItem(ToolboxItem)Adds the specified toolbox item to the toolbox.
Public methodAddToolboxItem(ToolboxItem, String)Adds the specified toolbox item to the toolbox in the specified category.
Public methodDeserializeToolboxItem(Object)Gets a toolbox item from the specified object that represents a toolbox item in serialized form.
Public methodDeserializeToolboxItem(Object, IDesignerHost)Gets a toolbox item from the specified object that represents a toolbox item in serialized form, using the specified designer host.
Public methodGetSelectedToolboxItem()Gets the currently selected toolbox item.
Public methodGetSelectedToolboxItem(IDesignerHost)Gets the currently selected toolbox item if it is available to all designers, or if it supports the specified designer.
Public methodGetToolboxItems()Gets the entire collection of toolbox items from the toolbox.
Public methodGetToolboxItems(IDesignerHost)Gets the collection of toolbox items that are associated with the specified designer host from the toolbox.
Public methodGetToolboxItems(String)Gets a collection of toolbox items from the toolbox that match the specified category.
Public methodGetToolboxItems(String, IDesignerHost)Gets the collection of toolbox items that are associated with the specified designer host and category from the toolbox.
Public methodIsSupported(Object, ICollection)Gets a value indicating whether the specified object which represents a serialized toolbox item matches the specified attributes.
Public methodIsSupported(Object, IDesignerHost)Gets a value indicating whether the specified object which represents a serialized toolbox item can be used by the specified designer host.
Public methodIsToolboxItem(Object)Gets a value indicating whether the specified object is a serialized toolbox item.
Public methodIsToolboxItem(Object, IDesignerHost)Gets a value indicating whether the specified object is a serialized toolbox item, using the specified designer host.
Public methodRefreshRefreshes the state of the toolbox items.
Public methodRemoveCreator(String)Removes a previously added toolbox item creator of the specified data format.
Public methodRemoveCreator(String, IDesignerHost)Removes a previously added toolbox creator that is associated with the specified data format and the specified designer host.
Public methodRemoveToolboxItem(ToolboxItem)Removes the specified toolbox item from the toolbox.
Public methodRemoveToolboxItem(ToolboxItem, String)Removes the specified toolbox item from the toolbox.
Public methodSelectedToolboxItemUsedNotifies the toolbox service that the selected tool has been used.
Public methodSerializeToolboxItemGets a serializable object that represents the specified toolbox item.
Public methodSetCursorSets the current application's cursor to a cursor that represents the currently selected tool.
Public methodSetSelectedToolboxItemSelects the specified toolbox item.
Top

The IToolboxService interface provides properties and methods for adding and removing toolbox items and toolbox creator callback delegates, serializing and deserializing toolbox items, and retrieving toolbox state information and managing toolbox state.

You can retrieve information about the contents of the toolbox with the following methods:

You can add and remove toolbox items with the following methods:

You can refresh the toolbox, mark a toolbox item as used, or set the mouse cursor to a cursor that represents the current toolbox item using the following methods:

  • The Refresh method refreshes the toolbox display to reflect the current state of the toolbox items.

  • The SelectedToolboxItemUsed method signals the toolbox that the selected toolbox item has been used.

  • The SetCursor method sets the mouse cursor to a cursor that represents the current toolbox item.

You can use the toolbox to serialize or deserialize a toolbox item using the following methods:

The following code example demonstrates the use of the IToolboxService in design mode to list and select toolbox categories and items, and to create components or controls from toolbox items and add them to a Form. To use the example, compile the code to an assembly, and add a reference to the assembly in a Windows Forms application. If you are using Visual Studio, the IToolboxServiceControl is automatically added to the Toolbox. Create an instance of the IToolboxServiceControl on a form to test its behavior.

using System;
using System.Collections;
using System.ComponentModel;
using System.ComponentModel.Design;
using System.Drawing;
using System.Drawing.Design;
using System.Data;
using System.Diagnostics;
using System.Windows.Forms;

namespace IToolboxServiceExample
{	
    // Provides an example control that functions in design mode to  
    // demonstrate use of the IToolboxService to list and select toolbox  
    // categories and items, and to add components or controls  
    // to the parent form using code.
    [DesignerAttribute(typeof(WindowMessageDesigner), typeof(IDesigner))]
    [System.Security.Permissions.PermissionSet(System.Security.Permissions.SecurityAction.Demand, Name = "FullTrust")] 
    public class IToolboxServiceControl : System.Windows.Forms.UserControl
    {		
        private System.Windows.Forms.ListBox listBox1;
        private System.Windows.Forms.ListBox listBox2;
        private IToolboxService toolboxService = null;
        private ToolboxItemCollection tools;
        private int controlSpacingMultiplier;

        public IToolboxServiceControl()
        {
            InitializeComponent();
            listBox2.DoubleClick += new EventHandler(this.CreateComponent);
            controlSpacingMultiplier = 0;
        }

        // Obtain or reset IToolboxService reference on each siting of control. 
        public override System.ComponentModel.ISite Site
        {
            get
            {
                return base.Site;
            }
            set
            {     
                base.Site = value;

                // If the component was sited, attempt to obtain  
                // an IToolboxService instance. 
                if( base.Site != null )
                {
                    toolboxService = (IToolboxService)this.GetService(typeof(IToolboxService));
                    // If an IToolboxService was located, update the  
                    // category list. 
                    if( toolboxService != null )
                        UpdateLists();                    
                }
                else
                    toolboxService = null;
            }
        }

        // Updates the list of categories and the list of items in the  
        // selected category. 
        private void UpdateLists()
        {
            if( toolboxService != null )
            {
                this.listBox1.SelectedIndexChanged -= new System.EventHandler(this.UpdateSelectedCategory);
                this.listBox2.SelectedIndexChanged -= new System.EventHandler(this.UpdateSelectedItem);
                listBox1.Items.Clear();
                for( int i=0; i<toolboxService.CategoryNames.Count; i++ )
                {
                    listBox1.Items.Add( toolboxService.CategoryNames[i] );
                    if( toolboxService.CategoryNames[i] == toolboxService.SelectedCategory )
                    {
                        listBox1.SelectedIndex = i;                        
                        tools = toolboxService.GetToolboxItems( toolboxService.SelectedCategory );
                        listBox2.Items.Clear();
                        for( int j=0; j<tools.Count; j++ )
                            listBox2.Items.Add( tools[j].DisplayName );
                    }
                }
                this.listBox1.SelectedIndexChanged += new System.EventHandler(this.UpdateSelectedCategory);
                this.listBox2.SelectedIndexChanged += new System.EventHandler(this.UpdateSelectedItem);
            }
        }

        // Sets the selected category when a category is clicked in the  
        // category list. 
        private void UpdateSelectedCategory(object sender, System.EventArgs e)
        {
            if( toolboxService != null )
            {
                toolboxService.SelectedCategory = (string)listBox1.SelectedItem;
                UpdateLists();
            }
        }

        // Sets the selected item when an item is clicked in the item list. 
        private void UpdateSelectedItem(object sender, System.EventArgs e)
        {
            if( toolboxService != null )      
            {
                if( listBox1.SelectedIndex != -1 )
                {
                    if( (string)listBox1.SelectedItem == toolboxService.SelectedCategory )
                        toolboxService.SetSelectedToolboxItem(tools[listBox2.SelectedIndex]);  
                    else
                        UpdateLists();
                }
            }            
        }   

        // Creates a control from a double-clicked toolbox item and adds  
        // it to the parent form. 
        private void CreateComponent(object sender, EventArgs e)
        {
            // Obtains an IDesignerHost service from design environment.
            IDesignerHost host = (IDesignerHost)this.GetService(typeof(IDesignerHost));

            // Get the project components container (Windows Forms control  
            // containment depends on controls collections).
            IContainer container = host.Container;

            // Identifies the parent Form.
            System.Windows.Forms.Form parentForm = this.FindForm();

            // Retrieves the parent Form's designer host.
            IDesignerHost parentHost = (IDesignerHost)parentForm.Site.GetService(typeof(IDesignerHost));

            // Create the components.
            IComponent[] comps = null;
            try
            {
                 comps = toolboxService.GetSelectedToolboxItem().CreateComponents(parentHost);
            }
            catch(Exception ex)
            {
                // Catch and show any exceptions to prevent disabling  
                // the control's UI.
                MessageBox.Show(ex.ToString(), "Exception message");
            }
            if( comps == null )
                return;

            // Add any created controls to the parent form's controls  
            // collection. Note: components are added from the  
            // ToolboxItem.CreateComponents(IDesignerHost) method. 
            for( int i=0; i<comps.Length; i++ )            
            {
                if( parentForm!= null && comps[i].GetType().IsSubclassOf(typeof(System.Windows.Forms.Control)) )
                {                    
                    ((System.Windows.Forms.Control)comps[i]).Location = new Point(20*controlSpacingMultiplier, 20*controlSpacingMultiplier);
                    if( controlSpacingMultiplier > 10 )
                        controlSpacingMultiplier = 0;
                    else
                        controlSpacingMultiplier++;
                    parentForm.Controls.Add( (System.Windows.Forms.Control)comps[i] );
                }
            }
        }

        // Displays labels. 
        protected override void OnPaint(System.Windows.Forms.PaintEventArgs e)
        {
            e.Graphics.DrawString("IToolboxService Control", new Font("Arial", 14), new SolidBrush(Color.Black), 6, 4);
            e.Graphics.DrawString("Category List", new Font("Arial", 8), new SolidBrush(Color.Black), 8, 26);
            e.Graphics.DrawString("Items in Category", new Font("Arial", 8), new SolidBrush(Color.Black), 208, 26);
            e.Graphics.DrawString("(Double-click item to add to parent form)", new Font("Arial", 7), new SolidBrush(Color.Black), 232, 12);
        }  

        private void InitializeComponent()
        {
            this.listBox1 = new System.Windows.Forms.ListBox();
            this.listBox2 = new System.Windows.Forms.ListBox();
            this.SuspendLayout();
            this.listBox1.Anchor = ((System.Windows.Forms.AnchorStyles.Top | System.Windows.Forms.AnchorStyles.Bottom) 
                | System.Windows.Forms.AnchorStyles.Left);
            this.listBox1.Location = new System.Drawing.Point(8, 41);
            this.listBox1.Name = "listBox1";
            this.listBox1.Size = new System.Drawing.Size(192, 368);
            this.listBox1.TabIndex = 0;
            this.listBox1.SelectedIndexChanged += new System.EventHandler(this.UpdateSelectedCategory);
            this.listBox2.Anchor = (((System.Windows.Forms.AnchorStyles.Top | System.Windows.Forms.AnchorStyles.Bottom) 
                | System.Windows.Forms.AnchorStyles.Left) 
                | System.Windows.Forms.AnchorStyles.Right);
            this.listBox2.Location = new System.Drawing.Point(208, 41);
            this.listBox2.Name = "listBox2";
            this.listBox2.Size = new System.Drawing.Size(228, 368);
            this.listBox2.TabIndex = 3;
            this.BackColor = System.Drawing.Color.Beige;
            this.Controls.AddRange(new System.Windows.Forms.Control[] {
                                                                          this.listBox2,
                                                                          this.listBox1});
            this.Location = new System.Drawing.Point(500, 400);
            this.Name = "IToolboxServiceControl";
            this.Size = new System.Drawing.Size(442, 422);
            this.ResumeLayout(false);
        }		
    }

    // This designer passes window messages to the controls at design time.     
    public class WindowMessageDesigner : System.Windows.Forms.Design.ControlDesigner
    {
        public WindowMessageDesigner()
        {
        }

        // Window procedure override passes events to control.
        [System.Security.Permissions.PermissionSet(System.Security.Permissions.SecurityAction.Demand, Name="FullTrust")] 
        protected override void WndProc(ref System.Windows.Forms.Message m)
        {   
            if( m.HWnd == this.Control.Handle )
                base.WndProc(ref m);            
            else             
                this.DefWndProc(ref m);            
        }        
    }
}

The following code 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 TextBox containing the text.

using System;
using System.ComponentModel;
using System.ComponentModel.Design;
using System.Drawing;
using System.Drawing.Design;
using System.Security.Permissions;
using System.Windows.Forms;

namespace TextDataTextBoxComponent
{
    // 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.
    [PermissionSet(SecurityAction.Demand, Name = "FullTrust")]
    public class TextDataTextBoxComponent : 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)
        {
            DataObject o = new DataObject((IDataObject)serializedObject);

            string[] formats = o.GetFormats();

            if (o.GetDataPresent("System.String", true))
            {
                string toolboxText = (string)(o.GetData("System.String", true));
                return (new TextToolboxItem(toolboxText));
            }

            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.
    [PermissionSet(SecurityAction.Demand, Name = "FullTrust")] 
    public class TextToolboxItem : 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.
        [PermissionSet(SecurityAction.Demand, Name="FullTrust")] 
        protected override IComponent[] CreateComponentsCore(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;
        }
    }
}

.NET Framework

Supported in: 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

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

Show:
© 2014 Microsoft