逐步解說：將智慧標籤加入至 Windows Form 元件

發行項
02/22/2013

智慧標籤是類似功能表的使用者介面 (UI) 項目，可提供常用的設計階段選項。隨 .NET Framework 提供的大部分標準元件和控制項都包含智慧標籤和設計工具動詞加強功能。本逐步解說中的程序為您示範：如何加入智慧標籤支援至元件和自訂控制項。

您可以加入智慧標籤至 Window Form 元件，以提供常用的設計階段選項。智慧標籤面板中的項目是以邏輯方式按分類群組，而且各個 DesignerActionMethodItem 執行個體可以選擇性地複製成設計工具動詞命令項目。隨 .NET Framework 提供的許多標準元件和控制項都包含智慧標籤和設計工具動詞加強功能。元件和自訂控制項作者也可以加入智慧標籤支援，一般都是使用推入模型進行。

利用推入模型加入智慧標籤需要在元件專案中加入下列各項：

衍生自 DesignerActionList 的類別實作，定義以智慧標籤功能表項目為目標的方法和屬性。這個類別也可以提供已覆寫的 GetSortedActionItems 方法，可傳回 DesignerActionItem 執行個體的陣列。
與元件相關聯的設計工具類別必須實作 ActionLists 屬性。擷取這個屬性會提供包含所有與單一智慧標籤功能表相關聯之 DesignerActionList 執行個體的 DesignerActionListCollection。在這種集合中經常只有一份清單。

注意事項
智慧標籤面板不支援捲動或分頁功能，因此請小心，不要使用許多智慧標籤項目填入您的面板。太多的項目可能會導致智慧標籤面板延伸到超出螢幕邊界的位置。

下列程序將示範如何使用從標準 Windows Form Label 控制項所衍生簡單範例控制項 ColorLabel 的程式碼加入智慧標籤。這個控制項有相關聯的設計工具，稱為 ColorLabelDesigner。

若要將此主題中的程式碼複製為一份清單，請參閱 HOW TO：將智慧標籤附加至 Windows Form 元件。

必要條件

若要完成這個逐步解說，您必須要有：

有足夠的權限可在已安裝 .NET Framework 的電腦上建立並執行 Windows Form 應用程式專案。

若要實作衍生自 DesignerActionList 的類別

在與元件相同的命名空間中，為衍生自 DesignerActionList 的類別加入宣告。

注意事項
您必須加入對設計階段組件 (System.Design.dll) 的參考。這個組件未包含在 .NET Framework 4 Client Profile 中。若要加入對 System.Design.dll 的參考，您必須將專案的目標 Framework 變更為 [.NET Framework 4]。

Public Class ColorLabelActionList
    Inherits System.ComponentModel.Design.DesignerActionList

public class ColorLabelActionList :
          System.ComponentModel.Design.DesignerActionList

加入建構函式至使用相關聯控制項之執行個體的類別。提供私用欄位，以存放此執行個體的參考。同時也提供私用欄位，以快取 DesignerActionService 的參考。此參考將用來更新清單。

Private colLabel As ColorLabel


...


Private designerActionUISvc As DesignerActionUIService = Nothing


...


Public Sub New(ByVal component As IComponent)

    MyBase.New(component)
    Me.colLabel = component

    ' Cache a reference to DesignerActionUIService, so the
    ' DesigneractionList can be refreshed.
    Me.designerActionUISvc = _
    CType(GetService(GetType(DesignerActionUIService)), _
    DesignerActionUIService)

End Sub

private ColorLabel colLabel;


...


private DesignerActionUIService designerActionUISvc = null;


...


public ColorLabelActionList( IComponent component ) : base(component) 
{
    this.colLabel = component as ColorLabel;

    // Cache a reference to DesignerActionUIService, so the
    // DesigneractionList can be refreshed.
    this.designerActionUISvc =
        GetService(typeof(DesignerActionUIService))
        as DesignerActionUIService;
}

加入您要與智慧標籤項目產生關聯的方法和屬性。方法將在選取其對應智慧標籤項目時執行。屬性應該要有 getter 區段，以便顯示其目前的值；如果屬性值要從對應的智慧標籤項目編輯，也可以有使用 GetProperties 方法的 setter 區段。

注意事項
與整個設計階段環境的情形相同，屬性只有在其中一個基底型別是由 .NET Framework 提供時，才能夠進行編輯，該型別可以由所提供的 TypeConverter，或是在提供自訂 UITypeEditor 時，轉換成基底型別。

Public Property ForeColor() As Color
    Get
        Return colLabel.ForeColor
    End Get
    Set(ByVal value As Color)
        GetPropertyByName("ForeColor").SetValue(colLabel, value)
    End Set
End Property


...


'Boolean properties are automatically displayed with binary 
' UI (such as a checkbox).
Public Property LockColors() As Boolean
    Get
        Return colLabel.ColorLocked
    End Get
    Set(ByVal value As Boolean)
        GetPropertyByName("ColorLocked").SetValue(colLabel, value)

        ' Refresh the list.
        Me.designerActionUISvc.Refresh(Me.Component)
    End Set
End Property


...


Public Sub InvertColors()
    Dim currentBackColor As Color = colLabel.BackColor
    BackColor = Color.FromArgb( _
    255 - currentBackColor.R, _
    255 - currentBackColor.G, _
    255 - currentBackColor.B)

    Dim currentForeColor As Color = colLabel.ForeColor
    ForeColor = Color.FromArgb( _
    255 - currentForeColor.R, _
    255 - currentForeColor.G, _
    255 - currentForeColor.B)
End Sub

public Color ForeColor
{
    get
    {
        return colLabel.ForeColor;
    }
    set
    {
        GetPropertyByName("ForeColor").SetValue(colLabel, value);
    }
}


...


// Boolean properties are automatically displayed with binary 
// UI (such as a checkbox).
public bool LockColors
{
    get
    {
        return colLabel.ColorLocked;
    }
    set
    {
        GetPropertyByName("ColorLocked").SetValue(colLabel, value);

        // Refresh the list.
        this.designerActionUISvc.Refresh(this.Component);
    }
}


...


public void InvertColors()
{
    Color currentBackColor = colLabel.BackColor;
    BackColor = Color.FromArgb(
        255 - currentBackColor.R, 
        255 - currentBackColor.G, 
        255 - currentBackColor.B);

    Color currentForeColor = colLabel.ForeColor;
    ForeColor = Color.FromArgb(
        255 - currentForeColor.R, 
        255 - currentForeColor.G, 
        255 - currentForeColor.B);
}

選擇性地實作 GetSortedActionItems 方法的已覆寫版本，以傳回 DesignerActionItem 執行個體的陣列，其中每個項目都與在前述步驟中建立的屬性或方法產生關聯。您可以執行上述作業，變更項目的順序，將項目分類，或選擇性地顯示項目。清單也可以包括靜態項目，如邏輯群組標題。

Public Overrides Function GetSortedActionItems() _
As DesignerActionItemCollection
    Dim items As New DesignerActionItemCollection()

    'Define static section header entries.
    items.Add(New DesignerActionHeaderItem("Appearance"))
    items.Add(New DesignerActionHeaderItem("Information"))

    'Boolean property for locking color selections.
    items.Add(New DesignerActionPropertyItem( _
    "LockColors", _
    "Lock Colors", _
    "Appearance", _
    "Locks the color properties."))

    If Not LockColors Then
        items.Add( _
        New DesignerActionPropertyItem( _
        "BackColor", _
        "Back Color", _
        "Appearance", _
        "Selects the background color."))

        items.Add( _
        New DesignerActionPropertyItem( _
        "ForeColor", _
        "Fore Color", _
        "Appearance", _
        "Selects the foreground color."))

        'This next method item is also added to the context menu 
        ' (as a designer verb).
        items.Add( _
        New DesignerActionMethodItem( _
        Me, _
        "InvertColors", _
        "Invert Colors", _
        "Appearance", _
        "Inverts the fore and background colors.", _
        True))
    End If
    items.Add( _
    New DesignerActionPropertyItem( _
    "Text", _
    "Text String", _
    "Appearance", _
    "Sets the display text."))

    'Create entries for static Information section.
    Dim location As New StringBuilder("Location: ")
    location.Append(colLabel.Location)
    Dim size As New StringBuilder("Size: ")
    size.Append(colLabel.Size)

    items.Add( _
    New DesignerActionTextItem( _
    location.ToString(), _
    "Information"))

    items.Add( _
    New DesignerActionTextItem( _
    size.ToString(), _
    "Information"))

    Return items
End Function

public override DesignerActionItemCollection GetSortedActionItems()
{
    DesignerActionItemCollection items = new DesignerActionItemCollection();

    //Define static section header entries.
    items.Add(new DesignerActionHeaderItem("Appearance"));
    items.Add(new DesignerActionHeaderItem("Information"));

    //Boolean property for locking color selections.
    items.Add(new DesignerActionPropertyItem("LockColors",
                     "Lock Colors", "Appearance",
                     "Locks the color properties."));
    if (!LockColors)
    {
        items.Add(new DesignerActionPropertyItem("BackColor",
                         "Back Color", "Appearance",
                         "Selects the background color."));
        items.Add(new DesignerActionPropertyItem("ForeColor",
                         "Fore Color", "Appearance",
                         "Selects the foreground color."));

        //This next method item is also added to the context menu 
        // (as a designer verb).
        items.Add(new DesignerActionMethodItem(this,
                         "InvertColors", "Invert Colors",
                         "Appearance",
                         "Inverts the fore and background colors.",
                          true));
    }
    items.Add(new DesignerActionPropertyItem("Text",
                     "Text String", "Appearance",
                     "Sets the display text."));

    //Create entries for static Information section.
    StringBuilder location = new StringBuilder("Location: ");
    location.Append(colLabel.Location);
    StringBuilder size = new StringBuilder("Size: ");
    size.Append(colLabel.Size);
    items.Add(new DesignerActionTextItem(location.ToString(),
                     "Information"));
    items.Add(new DesignerActionTextItem(size.ToString(),
                     "Information"));

    return items;
}

若要更新相關聯的設計工具類別，以實作 ActionLists 屬性

找出控制項的設計工具類別。如果找不到任何類別，就建立設計工具類別，並讓它與控制項類別產生關聯。如需設計工具的詳細資訊，請參閱基底設計工具類別。

若要運用最佳化的技巧，請加入型別 DesignerActionListCollection 的私用欄位。

Private lists As DesignerActionListCollection

private DesignerActionListCollection actionLists;

加入已覆寫的 ActionLists 屬性，以傳回您先前所建立 ColorLabelActionList 類別的新執行個體。

Public Overrides ReadOnly Property ActionLists() _
As DesignerActionListCollection
    Get
        If lists Is Nothing Then
            lists = New DesignerActionListCollection()
            lists.Add( _
            New ColorLabelActionList(Me.Component))
        End If
        Return lists
    End Get
End Property

public override DesignerActionListCollection ActionLists
{
    get
    {
        if (null == actionLists)
        {
            actionLists = new DesignerActionListCollection();
            actionLists.Add(
                new ColorLabelActionList(this.Component));
        }
        return actionLists;
    }
}

註解

程式碼中有一些區域應該要有更詳細的說明：

當衍生自 DesignerActionList 之類別中的屬性或方法變更相關聯控制項的狀態時，不可以透過元件屬性的直接 setter 呼叫作這些變更。而應該要透過適當地建立 PropertyDescriptor，進行這些變更。這種間接手法可確保智慧標籤復原和 UI 更新動作都能正確地運作。
您可以透過呼叫 DesignerActionUIService.Refresh，動態地更新智慧標籤面板。這種處理流程可以用來動態地變更智慧標籤面板的內容。在範例中，依 LockColors 屬性的狀態而定，有條件地包含了與變更色彩相關的智慧標籤。這個 Boolean 屬性也與智慧標籤產生關聯，以便讓開發人員至少能夠透過功能表，鎖定或解除鎖定目前的色彩選擇。
透過將 includeAsDesignerVerb 參數設定為 true，型別 DesignerActionMethodItem 的智慧標籤項目可以在建構函式中選擇性地包含在相關聯控制項的捷徑功能表中。然後 .NET Framework 會以隱含方式建立對應的 DesignerVerb，並為您加入至捷徑功能表中。在這個範例中，InvertColors 項目就是以這種方式處理。
智慧標籤項目是按其 Category 屬性群組成面板，而屬性是在每一個項目的建構函式中設定。如果此屬性並未明確地設定，就會指定為預設分類。每一個項目在智慧標籤面板中是按分類排列順序，然後在由衍生自 DesignerActionList 類別之類別傳回的 DesignerActionItem 陣列中按其產生順序排列。這個範例包含兩個分類：Appearance 和 Information。

注意事項

第二個分類不提供 DesignerActionHeaderItem。
顯示靜態文字資訊的項目可以使用其相關聯屬性只包含 setter 的 DesignerActionTextItem 或 DesignerActionPropertyItem 實作。這個範例使用的是前一種手法。