Passo a passo: Adicionando marcas inteligentes para um componente do Windows Forms

Artigo
02/25/2013

As marcas inteligentes são elementos de interface (UI) do usuário menu semelhante que fornecem opções usadas com freqüência de tempo de design.A maioria dos componentes padrão e os controles fornecidos com o.NET Framework contêm a marca inteligente e aprimoramentos do verbo designer.Os procedimentos neste passo a passo mostram como adicionar suporte de marcas inteligentes a componentes e controles personalizados.

Você pode adicionar marcas inteligentes a componentes do Windows Forms para opções de tempo de design de fonte usado.Itens em um painel de marcas inteligentes são logicamente agrupados por categoria e indivíduo DesignerActionMethodItem instâncias opcionalmente podem ser duplicadas como entradas de verbo designer.Muitos dos componentes padrão e dos controles fornecidos com o.NET Framework contêm a marca inteligente e aprimoramentos do verbo designer.Componente e autores de controle personalizado também podem adicionar suporte a marcas inteligentes, normalmente usando o modelo de envio.

A adição de marcas inteligentes com o modelo de envio requer as seguintes adições ao projeto componente:

Implementação de uma classe, derivada do DesignerActionList, que define os métodos e propriedades que são alvos dos itens de menu de marcas inteligentes.Essa classe também poderá fornecer uma substituição GetSortedActionItems método que retorna uma matriz de DesignerActionItem instâncias.
A classe do designer associada ao componente deve implementar a ActionLists propriedade.Esta propriedade fornece o DesignerActionListCollection , que contém todas as DesignerActionList instâncias associadas a um único menu de marcas inteligentes.Geralmente, há apenas uma lista em tal uma coleção.

Observação
Painéis de marcas inteligentes não oferecem suporte a rolagem ou de paginação, portanto, tenha cuidado para não preencher seus painéis com muitos itens de marcas inteligentes.Muitos itens podem resultar em Painel de marcas inteligentes que ultrapasse o limite da tela.

O procedimento a seguir demonstra como adicionar marcas inteligentes usando código de controle de um exemplo simples, ColorLabel, que é derivada de formulários padrão do Windows Label controle.Este controle tem um designer associado nomeados ColorLabelDesigner.

Para copiar o código deste tópico como uma única lista, consulte Como: anexar marcas inteligentes para um componente do Windows Forms.

Pré-requisitos

A fim de concluir este explicação passo a passo, será necessário:

Permissões suficientes para poder criar e executar projetos de aplicativos Windows Forms no computador onde o.NET Framework é instalado.

Para implementar uma classe derivada de DesignerActionList

No mesmo namespace que seu componente, adicione a declaração de sua classe derivada de DesignerActionList.

Observação
Você deve adicionar uma referência ao assembly em tempo de design, System.Design.dll.Este assembly não está incluído na.NET Framework 4 o perfil do cliente.Para adicionar uma referência a System.Design.dll, você deve alterar a estrutura do projeto de destino para .NET Framework 4.

Public Class ColorLabelActionList
    Inherits System.ComponentModel.Design.DesignerActionList

public class ColorLabelActionList :
          System.ComponentModel.Design.DesignerActionList

Adicione um construtor para essa classe que leva a uma instância do controle associado.Forneça um campo privado para manter uma referência a essa instância.Também fornecer um campo privado para armazenar em cache uma referência para o DesignerActionService.Isso será usado para atualizar a lista.

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

Adicione métodos e propriedades que você deseja associar aos itens de marcas inteligentes.Métodos serão executados quando a entrada de marcas inteligentes correspondente é selecionada.As propriedades devem ter as seções do getter para que seu valor atual é exibida; eles podem opcionalmente ter seções setter que usam o GetProperties método se seus valores estejam editável na entrada correspondente marcas inteligentes.

Observação
Assim como acontece em todo o ambiente de tempo de design, uma propriedade é capaz de que está sendo editado somente se um dos tipos base fornecido pelo.NET Framework, o tipo pode ser facilmente convertido em um tipo base um fornecido TypeConverter, ou quando um personalizado UITypeEditor for fornecida.

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

Opcionalmente, implementar uma versão de substituição a GetSortedActionItems método para retornar uma matriz de DesignerActionItem instâncias, onde cada item está associado uma propriedade ou método criado na etapa anterior.Você pode fazer isso para alterar a ordem dos itens, categorizá-las ou opcionalmente mostrá-los.A lista também pode incluir itens estáticos, como, por exemplo, títulos de grupo lógico.

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

Para atualizar a classe do designer associada para implementar a propriedade ActionLists

Localize a classe do designer para o controle.Se não existir, crie uma classe designer e associá-la à classe do controle.Para obter mais informações sobre os designers, consulte Classes base do Designer.
Como uma técnica de otimização, adicione um campo particular do tipo DesignerActionListCollection.
```
Private lists As DesignerActionListCollection
```
```
private DesignerActionListCollection actionLists;
```

Adicionar o substituído ActionLists propriedade para retornar uma nova instância da ColorLabelActionList classe que você criou anteriormente.

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

Comentários

Várias áreas do código que merecem uma explicação mais detalhada:

Quando uma propriedade ou método na classe derivada de DesignerActionList altera o estado do controle associado, essas alterações não devem ser feitas por chamadas diretas setter para as propriedades do componente.Em vez disso, essas alterações devem ser feitas por meio de uma criada adequadamente PropertyDescriptor.Essa abordagem indireta garante que desfazer de marcas inteligentes e a interface do usuário atualizar a função de ações corretamente.
Você pode atualizar dinamicamente o painel de marcas inteligentes, chamando DesignerActionUIService.Refresh.Esse processo pode ser usado para alterar dinamicamente o conteúdo do painel de marcas inteligentes.No exemplo, as marcas inteligentes preocupadas com a alteração de cores são incluídas condicionalmente dependendo do estado da LockColors propriedade.Essa propriedade booleana também está associada uma marca inteligente, para que o desenvolvedor pode bloquear ou desbloquear a seleção de cores atual, de pelo menos por meio do menu.
Uma entrada de marcas inteligentes do tipo DesignerActionMethodItem pode ser opcionalmente incluído no menu de atalho para o controle associado, definindo a includeAsDesignerVerb parâmetro no construtor para true.A.NET Framework, em seguida, cria implicitamente um correspondente DesignerVerb e o adiciona ao menu de atalho para você.Neste exemplo, o InvertColors item é tratado dessa maneira.
Os itens de marcas inteligentes são agrupados em um painel por seus Category propriedade, que é definida no construtor para cada item.Se essa propriedade não estiver explicitamente definida, ela é atribuída à categoria padrão.Cada item é ordenada no painel de marcas inteligentes por categoria e, em seguida, por ordem de ocorrência na DesignerActionItem matriz retornada pela classe derivada de DesignerActionList classe.Este exemplo contém duas categorias: Appearance e Information.

Observação

Não DesignerActionHeaderItem é fornecido para a segunda categoria.
Uma entrada que exibe informações de texto estático pode ser implementada usando um DesignerActionTextItem ou um DesignerActionPropertyItem cuja propriedade associada contém apenas um setter.Este exemplo usa a primeira abordagem.

Observação
Não DesignerActionHeaderItem é fornecido para a segunda categoria.

Próximas etapas

Assim que tiver iniciado a integrar seu componente para o ambiente de tempo de design, considere expandindo seu suporte de designer.

Adicione atributos a seus membros para facilitar a comunicação com o ambiente de tempo de design.Para obter mais informações, consulte Atributos de controles do Windows Forms.
Escreva seu próprio designer personalizado.Para obter mais informações, consulte Como: criar um controle Windows Forms que tira proveito dos recursos de tempo de Design.