ToolboxItem 類別

定義

命名空間:

System.Drawing.Design

組件:

System.Windows.Forms.Design.dll

提供工具箱項目的基底實作。

C#

public class ToolboxItem : System.Runtime.Serialization.ISerializable

繼承

Object

ToolboxItem

衍生

System.Web.UI.Design.WebControlToolboxItem

System.Workflow.ComponentModel.Design.ActivityToolboxItem

實作

ISerializable

範例

下列程式代碼範例提供使用 介面將文字數據格式處理程式 或 ToolboxItemCreatorCallback新增至工具箱的元件IToolboxService。 數據建立者回呼委派會將貼到工具箱的任何文字數據，並拖曳到窗體上，以建立包含TextBox文字的 自定義ToolboxItem。

C#

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.
    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.
    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.
        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;
        }
    }
}

下列程式代碼範例示範如何使用 ToolboxItem 類別做為自定義工具箱項目實作的基類。

C#

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Drawing;
using System.Drawing.Design;
using System.Data;
using System.Runtime.Serialization;
using System.Text;
using System.Windows.Forms;

namespace CustomToolboxItem
{
    public class Form1 : Form
    {
        private System.ComponentModel.IContainer components = null;
        private UserControl1 userControl11;
        private System.Windows.Forms.Label label1;

        public Form1()
        {
            InitializeComponent();
        }

        private void InitializeComponent()
        {
            this.label1 = new System.Windows.Forms.Label();
            this.userControl11 = new CustomToolboxItem.UserControl1();
            this.SuspendLayout();
            // 
            // label1
            // 
            this.label1.Location = new System.Drawing.Point(15, 16);
            this.label1.Name = "label1";
            this.label1.Size = new System.Drawing.Size(265, 62);
            this.label1.TabIndex = 0;
            this.label1.Text = "Build the project and drop UserControl1 from the toolbox onto the form.";
            // 
            // userControl11
            // 
            this.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.";
            this.userControl11.Location = new System.Drawing.Point(74, 81);
            this.userControl11.Name = "userControl11";
            this.userControl11.Padding = new System.Windows.Forms.Padding(6);
            this.userControl11.Size = new System.Drawing.Size(150, 150);
            this.userControl11.TabIndex = 1;
            // 
            // Form1
            // 
            this.ClientSize = new System.Drawing.Size(292, 266);
            this.Controls.Add(this.userControl11);
            this.Controls.Add(this.label1);
            this.Name = "Form1";
            this.Text = "Form1";
            this.ResumeLayout(false);
        }

        protected override void Dispose(bool disposing)
        {
            if (disposing && (components != null))
            {
                components.Dispose();
            }
            base.Dispose(disposing);
        }

        static void Main()
        {
            Application.EnableVisualStyles();
            Application.Run(new Form1());
        }
    }

    // Configure this user control to have a custom toolbox item.
    [ToolboxItem(typeof(MyToolboxItem))]
    public class UserControl1 : UserControl
    {
        private System.ComponentModel.IContainer components = null;
        private System.Windows.Forms.Label label1;

        public UserControl1()
        {
            InitializeComponent();
        }

        public string LabelText
        {
            get
            {
                return label1.Text;
            }
            set
            {
                label1.Text = value;
            }
        }

        private void InitializeComponent()
        {
            this.label1 = new System.Windows.Forms.Label();
            this.SuspendLayout();
            // 
            // label1
            // 
            this.label1.Dock = System.Windows.Forms.DockStyle.Fill;
            this.label1.Location = new System.Drawing.Point(6, 6);
            this.label1.Name = "label1";
            this.label1.Size = new System.Drawing.Size(138, 138);
            this.label1.TabIndex = 0;
            this.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.\r\n";
            this.label1.TextAlign = 
                System.Drawing.ContentAlignment.MiddleCenter;
            // 
            // UserControl1
            // 
            this.Controls.Add(this.label1);
            this.Name = "UserControl1";
            this.Padding = new System.Windows.Forms.Padding(6);
            this.ResumeLayout(false);
        }

        protected override void Dispose(bool disposing)
        {
            if (disposing && (components != null))
            {
                components.Dispose();
            }
            base.Dispose(disposing);
        }
    }

    // Toolbox items must be serializable.
    [Serializable]
    class MyToolboxItem : ToolboxItem
    {
        // The add components dialog in Visual Studio looks for a public
        // constructor that takes a type.
        public MyToolboxItem(Type toolType)
            : base(toolType)
        {
        }

        // 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.  
        MyToolboxItem(SerializationInfo info, StreamingContext context)
        {
            Deserialize(info, context);
        }

        // Let's override the creation code and pop up a dialog.
        protected override IComponent[] CreateComponentsCore(
            System.ComponentModel.Design.IDesignerHost host, 
            System.Collections.IDictionary defaultValues)
        {
            // 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 (ToolboxItemDialog d = new ToolboxItemDialog())
            {
                if (d.ShowDialog() == DialogResult.OK)
                {
                    string text = d.CreationText;

                    IComponent[] comps =
                        base.CreateComponentsCore(host, defaultValues);
                    // comps will have a single component: our data type.
                    ((UserControl1)comps[0]).LabelText = text;
                    return comps;
                }
                else
                {
                    return null;
                }
            }
        }
    }

    public class ToolboxItemDialog : Form
    {
        private System.ComponentModel.IContainer components = null;
        private System.Windows.Forms.Label label1;
        private System.Windows.Forms.TextBox textBox1;
        private System.Windows.Forms.Button button1;
        private System.Windows.Forms.Button button2;

        public ToolboxItemDialog()
        {
            InitializeComponent();
        }

        private void InitializeComponent()
        {
            this.label1 = new System.Windows.Forms.Label();
            this.textBox1 = new System.Windows.Forms.TextBox();
            this.button1 = new System.Windows.Forms.Button();
            this.button2 = new System.Windows.Forms.Button();
            this.SuspendLayout();
            // 
            // label1
            // 
            this.label1.Location = new System.Drawing.Point(10, 9);
            this.label1.Name = "label1";
            this.label1.Size = new System.Drawing.Size(273, 43);
            this.label1.TabIndex = 0;
            this.label1.Text = "Enter the text you would like" + 
                " to have the user control populated with:";
            // 
            // textBox1
            // 
            this.textBox1.AutoSize = false;
            this.textBox1.Location = new System.Drawing.Point(10, 58);
            this.textBox1.Multiline = true;
            this.textBox1.Name = "textBox1";
            this.textBox1.Size = new System.Drawing.Size(270, 67);
            this.textBox1.TabIndex = 1;
            this.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
            // 
            this.button1.DialogResult = System.Windows.Forms.DialogResult.OK;
            this.button1.Location = new System.Drawing.Point(124, 131);
            this.button1.Name = "button1";
            this.button1.TabIndex = 2;
            this.button1.Text = "OK";
            // 
            // button2
            // 
            this.button2.DialogResult = System.Windows.Forms.DialogResult.Cancel;
            this.button2.Location = new System.Drawing.Point(205, 131);
            this.button2.Name = "button2";
            this.button2.TabIndex = 3;
            this.button2.Text = "Cancel";
            // 
            // ToolboxItemDialog
            // 
            this.AcceptButton = this.button1;
            this.CancelButton = this.button2;
            this.ClientSize = new System.Drawing.Size(292, 162);
            this.ControlBox = false;
            this.Controls.Add(this.button2);
            this.Controls.Add(this.button1);
            this.Controls.Add(this.textBox1);
            this.Controls.Add(this.label1);
            this.FormBorderStyle = 
                System.Windows.Forms.FormBorderStyle.FixedDialog;
            this.Name = "ToolboxItemDialog";
            this.Text = "ToolboxItemDialog";
            this.ResumeLayout(false);
        }

        public string CreationText
        {
            get
            {
                return textBox1.Text;
            }
        }

        protected override void Dispose(bool disposing)
        {
            if (disposing && (components != null))
            {
                components.Dispose();
            }
            base.Dispose(disposing);
        }
    }
}

備註

ToolboxItem 是工具箱專案的基類，可以顯示在設計時間環境的工具箱中。 工具箱專案通常代表在設計模式檔上叫用時所要建立的元件。 類別 ToolboxItem 提供為工具箱專案提供顯示屬性所需的方法和屬性、在使用時建立元件或元件，以及串行化和還原串行化本身以在工具箱資料庫中保存。

類別的 ToolboxItem 實例可以使用名稱、位圖和類型進行設定，而不需要建立衍生自 ToolboxItem的類別。 類別 ToolboxItem 也提供自定義工具箱項目實作的基類。 自訂 ToolboxItem 可以建立多個元件。 若要實作自定義工具箱專案，您必須衍生自 ToolboxItem 並覆寫 CreateComponentsCore、 Serialize和 Deserialize 方法。

必須設定下列屬性和方法，才能 ToolboxItem 正確運作：

• 屬性 DisplayName 會在工具箱中顯示時，指定工具箱項目的標籤。

• 屬性 TypeName 會指定專案所建立元件類型的完整名稱。 如果衍生類別建立多個元件，可能會使用 屬性， TypeName 視方法覆寫是否 CreateComponentsCore 取決於此屬性的值而定。

• 屬性 AssemblyName 會指定元件，其中包含專案所建立之元件的型別。

• 屬性 Bitmap 選擇性地指定要顯示在工具箱中工具箱項目顯示名稱旁的點陣圖影像。

• 屬性 Filter 選擇性地包含任何 ToolboxItemFilterAttribute 物件，可判斷工具箱專案是否可以在特定元件上使用。

• 方法會 CreateComponentsCore 傳回元件實例或實例，以插入使用此工具的位置。

• 方法 Serialize 會將工具箱項目儲存至指定的 SerializationInfo。

• 方法 Deserialize 會從指定 SerializationInfo中所包含的狀態資訊設定工具箱專案。

• 如果CreateComponentsCore尚未覆寫方法以以不同方式運作，方法Initialize會設定工具箱專案來建立指定的元件類型。

• 屬性 Locked 會指出是否可以變更工具箱項目的屬性。 工具箱專案通常會在新增至工具箱之後鎖定。

• 方法 Lock 會鎖定工具箱專案。

• 如果 Locked 屬性為 true，則CheckUnlocked方法會擲回例外狀況。

建構函式

ToolboxItem()	初始化 ToolboxItem 類別的新執行個體。
ToolboxItem(Type)	初始化 ToolboxItem 類別的新執行個體，以建立元件的指定型別。

屬性

AssemblyName	取得或設定組件的名稱，該組件包含類型或工具箱項目所建立的類型。
Bitmap	取得或設定點陣圖，表示工具箱中的工具箱項目。
Company	取得或設定這個 ToolboxItem 的公司名稱。
ComponentType	取得這個 ToolboxItem 的元件型別。
DependentAssemblies	取得或設定工具箱項目的 AssemblyName。
Description	取得或設定這個 ToolboxItem 的描述。
DisplayName	取得或設定工具箱項目的顯示名稱。
Filter	取得或設定篩選條件，判斷工具箱項目是否可以在目的元件上使用。
IsTransient	取得值，指出工具箱項目是否為暫時性 (Transient)。
Locked	取得值，指出 ToolboxItem 目前是否已鎖定。
OriginalBitmap	取得或設定此項目工具箱中將使用的原始點陣圖。
Properties	取得屬性的字典。
TypeName	取得或設定叫用工具箱項目時所建立的 IComponent 的型別完整名稱。
Version	取得這個 ToolboxItem 的版本。

方法

CheckUnlocked()	如果工具箱項目目前是鎖定的，則會擲回例外狀況。
CreateComponents()	建立工具箱項目受到設定要建立的元件。
CreateComponents(IDesignerHost)	使用指定的設計工具主應用程式 (Designer Host)，建立工具箱項目受到設定要建立的元件。
CreateComponents(IDesignerHost, IDictionary)	使用指定的設計工具主應用程式 (Designer Host) 和預設值，建立工具箱項目設定為要建立的元件。
CreateComponentsCore(IDesignerHost)	建立元件或叫用工具箱項目時要使用之元件的陣列。
CreateComponentsCore(IDesignerHost, IDictionary)	在叫用工具箱項目時建立元件陣列。
Deserialize(SerializationInfo, StreamingContext)	從指定的序列化資訊物件載入工具箱項目的狀態。
Equals(Object)	判斷兩個 ToolboxItem 執行個體是否相等。
FilterPropertyValue(String, Object)	在傳回前篩選屬性值。
GetHashCode()	傳回這個執行個體的雜湊碼。
GetType()	取得目前執行個體的 Type。 (繼承來源 Object)
GetType(IDesignerHost)	啟用對與工具箱項目關聯之類型的存取。
GetType(IDesignerHost, AssemblyName, String, Boolean)	建立指定類型的執行個體，並選擇性使用指定的設計工具主應用程式和組件名稱。
Initialize(Type)	使用要建立的指定類型來初始化目前工具箱項目。
Lock()	鎖定工具箱項目並防止變更其屬性。
MemberwiseClone()	建立目前 Object 的淺層複製。 (繼承來源 Object)
OnComponentsCreated(ToolboxComponentsCreatedEventArgs)	引發 ComponentsCreated 事件。
OnComponentsCreating(ToolboxComponentsCreatingEventArgs)	引發 ComponentsCreating 事件。
Serialize(SerializationInfo, StreamingContext)	將工具箱項目的狀態儲存到指定的序列化資訊物件。
ToString()	傳回代表目前 ToolboxItem 的 String。
ValidatePropertyType(String, Object, Type, Boolean)	驗證物件是否為指定類型。
ValidatePropertyValue(String, Object)	將屬性指派給屬性字典前驗證屬性。

事件

ComponentsCreated	立即發生於建立元件之後。
ComponentsCreating	發生於即將建立元件時。

明確介面實作

ISerializable.GetObjectData(SerializationInfo, StreamingContext)

如需這個成員的描述，請參閱 GetObjectData(SerializationInfo, StreamingContext) 方法。

適用於

另請參閱

• ToolboxItemFilterAttribute
• ToolboxItemAttribute
• IToolboxService
• IToolboxUser
• ToolboxComponentsCreatedEventArgs
• ToolboxComponentsCreatedEventHandler