Propriedades de tempo de design para controles personalizados

Este artigo ensina como as propriedades são tratadas para controles no Designer Visual dos Windows Forms no Visual Studio.

Cada controle herda muitas propriedades da classe System.Windows.Forms.Controlbase, como:

• Enabled
• Font
• ForeColor
• Focused
• Visible
• Width

Ao criar um controle, você pode definir novas propriedades e controlar como elas aparecem no designer.

Definir uma propriedade

Qualquer propriedade pública com um acessador get definido por um controle é automaticamente visível na janela Propriedades do Visual Studio. Se a propriedade também definir um acessador de conjunto , a propriedade poderá ser alterada na janela Propriedades . No entanto, as propriedades podem ser exibidas explicitamente ou ocultadas da janela Propriedades aplicando o BrowsableAttribute. Esse atributo usa um único parâmetro booliano para indicar se ele é exibido ou não. Para obter mais informações sobre atributos, consulte Atributos (C#) ou Visão geral de atributos (Visual Basic).

[Browsable(false)]
[DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
public bool IsSelected { get; set; }

<Browsable(False)>
<DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)>
Public Property IsSelected As Boolean

Propriedades serializadas

As propriedades definidas em um controle são serializadas no arquivo code-behind do designer. Isso acontece quando o valor de uma propriedade é definido como algo diferente de seu valor padrão.

Quando o designer detecta uma alteração em uma propriedade, ele avalia todas as propriedades do controle e serializa qualquer propriedade cujo valor não corresponde ao valor padrão da propriedade. O valor de uma propriedade é serializado no arquivo de código-behid do designer. Os valores padrão ajudam o designer a determinar quais valores de propriedade devem ser serializados.

Valores padrão

Uma propriedade é considerada ter um valor padrão quando aplica o atributo DefaultValueAttribute, ou a classe da propriedade contém métodos Reset e ShouldSerialize específicos da propriedade. Para obter mais informações sobre atributos, consulte Atributos (C#) ou Visão geral de atributos (Visual Basic).

Ao definir um valor padrão, você habilita o seguinte:

• A propriedade fornecerá indicação visual na janela Propriedades se ela tiver sido modificada de seu valor padrão.
• O usuário pode clicar com o botão direito do mouse na propriedade e escolher Redefinir para restaurar a propriedade para seu valor padrão.
• O designer gera um código mais eficiente.

Se uma propriedade usa um tipo simples, como um tipo primitivo, o valor padrão pode ser definido aplicando-o DefaultValueAttribute à propriedade. No entanto, as propriedades com esse atributo não começam automaticamente com esse valor atribuído. Você deve definir o campo de backup da propriedade com o mesmo valor padrão. Você pode definir a propriedade na declaração ou no construtor da classe.

Quando uma propriedade é um tipo complexo ou você deseja controlar o comportamento de redefinição e serialização do designer, defina os métodos Reset<PropertyName> e ShouldSerialize<PropertyName> na classe. Por exemplo, se o controle definir uma Age propriedade, os métodos serão nomeados ResetAge e ShouldSerializeAge.

As propriedades podem ser "redefinidas" para seus valores padrão por meio da janela Propriedades clicando com o botão direito do mouse no nome da propriedade e selecionando Redefinir.

A disponibilidade da opção de menuRedefinir contexto com o> em > é habilitada quando:

• A propriedade tem o DefaultValueAttribute atributo aplicado e o valor da propriedade não corresponde ao valor do atributo.
• A classe da propriedade define um Reset<PropertyName> método sem um ShouldSerialize<PropertyName>.
• A classe da propriedade define um Reset<PropertyName> método e o ShouldSerialize<PropertyName> retorna true.

DefaultValueAttribute

Se o valor de uma propriedade não corresponder ao valor fornecido, DefaultValueAttributea propriedade será considerada alterada e poderá ser redefinida por meio da janela Propriedades .

O código a seguir declara duas propriedades, uma enumeração com um valor North padrão e um inteiro com um valor padrão de 10.

[DefaultValue(typeof(Directions), "North")]
public Directions PointerDirection { get; set; } = Directions.North;

[DefaultValue(10)]
public int DistanceInFeet { get; set; } = 10;

<DefaultValue(GetType(Directions), "North")>
Public Property PointerDirection As Directions = Directions.North

<DefaultValue(10)>
Public Property DistanceInFeet As Integer = 10

Restaurar e ShouldSerialize

Como mencionado anteriormente, os métodos Reset<PropertyName> e ShouldSerialize<PropertyName> oferecem a oportunidade de orientar não apenas o comportamento de redefinição de uma propriedade, mas também determinar se um valor foi alterado e deve ser serializado no arquivo code-behind do designer. Ambos os métodos funcionam juntos e você não deve definir um sem o outro.

Quando Reset<PropertyName> é definida, a janela Propriedades exibe uma opção de menu de contexto Redefinir para essa propriedade. Quando Redefinir é selecionado, o Reset<PropertyName> método é invocado. A opção Redefinir no menu de contexto é habilitada ou desabilitada conforme o que é retornado pelo método ShouldSerialize<PropertyName>. Quando ShouldSerialize<PropertyName> retorna true, indica que a propriedade foi alterada de seu valor padrão e deve ser serializada no arquivo de código subjacente e habilita a opção redefinir no menu de contexto. Quando false é retornado, a opção Redefinir do menu de contexto está desabilitada e o code-behind tem o código de configuração de propriedades removido.

O snippet de código a seguir declara uma propriedade chamada Direction. O comportamento do designer dessa propriedade é controlado pelos métodos ResetDirection e ShouldSerializeDirection.

public Directions Direction { get; set; } = Directions.None;

private void ResetDirection() =>
    Direction = Directions.None;

private bool ShouldSerializeDirection() =>
    Direction != Directions.None;

Public Property Direction As Directions = Directions.None

Private Sub ResetDirection()
    Direction = Directions.None
End Sub

Private Function ShouldSerializeDirection() As Boolean
    Return Direction <> Directions.None
End Function

Conversores de tipo

Embora os conversores de tipo normalmente convertam um tipo em outro, eles também fornecem conversão de string para valor para o grid de propriedades e outros controles em tempo de design. A conversão de cadeia de caracteres para valor permite que propriedades complexas sejam representadas em tempo de design nesses controles.

A maioria dos tipos de dados internos (números, enumerações e outros) tem conversores de tipo padrão que fornecem conversões de cadeia de caracteres para valor e executam verificações de validação. Os conversores de tipo padrão estão no System.ComponentModel namespace e são nomeados após o tipo que está sendo convertido. Os nomes de tipo de conversor usam o seguinte formato: {type name}Converter. Por exemplo, StringConverter, TimeSpanConverter e Int32Converter.

Conversores de tipo são usados extensivamente em tempo de desenvolvimento na janela de Propriedades. Um conversor de tipo pode ser aplicado a uma propriedade ou um tipo, usando o TypeConverterAttribute.

A janela Propriedades usa conversores para exibir a propriedade como um valor de cadeia de caracteres quando a TypeConverterAttribute propriedade é declarada. Quando o TypeConverterAttribute é declarado para um tipo, a janela Propriedades usa o conversor em cada propriedade desse tipo. O conversor de tipo também ajuda a serializar o valor da propriedade no arquivo code-behind do designer.

Editores de tipos

A janela Propriedades usa automaticamente um editor de tipos para uma propriedade quando o tipo da propriedade é um tipo interno ou conhecido. Por exemplo, um valor booleano é editado como uma caixa de combinação com as opções Verdadeiro e Falso, e o tipo DateTime usa uma lista suspensa de calendário.