Propriedades de tempo de configuração para controlos personalizados

Este artigo ensina como as propriedades são manipuladas para controles no Windows Forms Visual Designer 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 definido , a propriedade poderá ser alterada na janela Propriedades . No entanto, as propriedades podem ser explicitamente exibidas ou ocultadas na janela Propriedades aplicando o BrowsableAttribute. Esse atributo usa um único parâmetro booleano para indicar se ele é exibido ou não. Para obter mais informações sobre atributos, consulte Attributes (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 deteta uma alteração em uma propriedade, ele avalia todas as propriedades para o controle e serializa qualquer propriedade cujo valor não corresponde ao valor padrão para a 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

Considera-se que uma propriedade tem 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 Attributes (C#) ou Visão geral de atributos (Visual Basic).

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

• A propriedade fornece uma indicação visual na janela Propriedades se tiver sido modificada em relação ao 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 ao 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 suporte 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 pretende 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 define uma Age propriedade, os métodos são nomeados ResetAge e ShouldSerializeAge.

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

A opção do menu de contexto Redefinir, acessível > em Propriedades>, é disponibilizada 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 método Reset<PropertyName> sem um ShouldSerialize<PropertyName>.
• A classe da propriedade define um método Reset<PropertyName> e ShouldSerialize<PropertyName> retorna true.

DefaultValueAttribute

Se o valor de uma propriedade não corresponder ao valor fornecido pelo DefaultValueAttribute, a propriedade será considerada alterada e poderá ser redefinida através 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 métodos Reset<PropertyName> e ShouldSerialize<PropertyName> fornecem a oportunidade de orientar não apenas o comportamento de redefinição de uma propriedade, mas também determinar se um valor é alterado e deve ser serializado no ficheiro de código subjacente do designer. Ambos os métodos funcionam juntos e você não deve definir um sem o outro.

Quando Reset<PropertyName> está 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 do menu de contexto Redefinir é ativada ou desativada de acordo com o que é retornado pelo método ShouldSerialize<PropertyName>. Quando ShouldSerialize<PropertyName> retorna true, isso indica que a propriedade foi alterada do seu valor padrão e deve ser serializada no arquivo code-behind, além de habilitar a opção de Redefinir no menu de contexto. Quando false é retornada, a opção do menu de contexto Redefinir é desabilitada e o code-behind tem o código do conjunto de propriedades removido.

O trecho de código a seguir declara uma propriedade chamada Direction. O comportamento designer desta 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 para outro, eles também fornecem conversão de string para valor para a grelha de propriedades e outros controlos durante o tempo de desenvolvimento. A conversão de cadeia de caracteres para 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 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 dos tipos 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 desenvolvimento 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 TypeConverterAttribute é declarado na propriedade. Quando o TypeConverterAttribute é declarado em 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 ficheiro code-behind do designer.

Editores de texto

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 os valores Verdadeiro e Falso e o tipo DateTime usa uma lista suspensa de calendário.