Propriedades de tempo de design para controles personalizados (Windows Forms .NET)

Este artigo ensina como as propriedades são tratadas para controles no Visual Designer do 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)]
public bool IsSelected { get; set; }

<Browsable(False)>
Public Property IsSelected As Boolean

[OBSERVAÇÃO] Propriedades complexas que não podem ser convertidas implicitamente de e para uma cadeia de caracteres exigem um conversor de tipo.

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 corresponda ao valor padrão da propriedade. O valor de uma propriedade é serializado no arquivo code-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 como tendo um valor padrão quando aplica o DefaultValueAttribute atributo ou a classe da propriedade contém métodos e ShouldSerialize específicos Reset 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 fornece indicação visual na janela Propriedades se tiver sido modificada a partir 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 o valor padrão.
• O designer gera um código mais eficiente.

Se uma propriedade usar um tipo simples, como um tipo primitivo, o valor padrão poderá 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 apoio 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 Reset<PropertyName> métodos and 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 do menu de contexto Redefinir do botão direito do mouse em>Propriedades>é ativada 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 retorna ShouldSerialize<PropertyName> true.

DefaultValueAttribute

Se o valor de uma propriedade não corresponder ao valor fornecido por DefaultValueAttribute, a 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 padrão de North 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

Redefinir e ShouldSerialize

Como mencionado anteriormente, os Reset<PropertyName> métodos and ShouldSerialize<PropertyName> fornecem a oportunidade de orientar não apenas o comportamento de redefinição de uma propriedade, mas também para determinar se um valor é 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> é definido, 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 de menu de contexto Redefinir é habilitada ou desabilitada ShouldSerialize<PropertyName> pelo que é retornado pelo método. Quando ShouldSerialize<PropertyName> retorna true, indica que a propriedade foi alterada de seu valor padrão e deve ser serializada no arquivo code-behind e habilita a opção de menu de contexto Redefinir . Quando false é retornado, a opção de menu de contexto Redefinir é desabilitada e o code-behind tem o código do conjunto de propriedades removido.

O snippet de código a seguir declara uma propriedade chamada Direction. O comportamento do designer dessa propriedade é controlado pelos ResetDirection métodos and 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 cadeia de caracteres em valor para a grade de propriedades e outros controles de tempo de design. A conversão de cadeia de caracteres em valor permite que propriedades complexas sejam representadas nesses controles de tempo de design.

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 em 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.

Os conversores de tipo são usados extensivamente em tempo de design com a janela Propriedades . Um conversor de tipo pode ser aplicado a uma propriedade ou a um tipo, usando o TypeConverterAttribute.

A janela Propriedades usa conversores para exibir a propriedade como um valor de cadeia de caracteres quando o é declarado TypeConverterAttribute na propriedade. Quando o é declarado TypeConverterAttribute em um tipo, a janela Propriedades usa o conversor em todas as propriedades 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 valores True e False e o DateTime tipo usa uma lista suspensa de calendário.