Propriétés au moment du design pour les contrôles personnalisés

Cet article vous explique comment les propriétés sont gérées pour les contrôles dans le Concepteur visuel Windows Forms dans Visual Studio.

Chaque contrôle hérite de nombreuses propriétés de la classe de base System.Windows.Forms.Control, telles que :

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

Lors de la création d’un contrôle, vous pouvez définir de nouvelles propriétés et contrôler leur apparence dans le concepteur.

Définir une propriété

Toute propriété publique avec un accesseur get défini par un contrôle est automatiquement visible dans la fenêtre Propriétés de Visual Studio. Si la propriété définit également un accesseur set, la propriété peut être modifiée dans la fenêtre Propriétés. Toutefois, les propriétés peuvent être affichées ou masquées explicitement dans la fenêtre Propriétés en appliquant la BrowsableAttribute. Cet attribut prend un paramètre booléen unique pour indiquer s’il est affiché ou non. Pour plus d’informations sur les attributs, consultez Attributs (C#) ou Vue d’ensemble des attributs (Visual Basic).

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

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

Propriétés sérialisées

Les propriétés définies sur un contrôle sont sérialisées dans le fichier code-behind du concepteur. Cela se produit lorsque la valeur d’une propriété est définie sur une valeur autre que sa valeur par défaut.

Lorsque le concepteur détecte une modification d’une propriété, il évalue toutes les propriétés du contrôle et sérialise toute propriété dont la valeur ne correspond pas à la valeur par défaut de la propriété. La valeur d’une propriété est sérialisée dans le fichier code-behid du concepteur. Les valeurs par défaut aident le concepteur à déterminer quelles valeurs de propriété doivent être sérialisées.

Valeurs par défaut

Une propriété est considérée comme ayant une valeur par défaut lorsqu’elle applique l’attribut DefaultValueAttribute, ou que la classe de la propriété contient des méthodes Reset et ShouldSerialize spécifiques à la propriété. Pour plus d’informations sur les attributs, consultez Attributs (C#) ou Vue d’ensemble des attributs (Visual Basic).

En définissant une valeur par défaut, vous activez les éléments suivants :

• La propriété fournit une indication visuelle dans la fenêtre Propriétés si elle a été modifiée à partir de sa valeur par défaut.
• L’utilisateur peut cliquer avec le bouton droit sur la propriété et choisir Réinitialiser pour restaurer la propriété à sa valeur par défaut.
• Le concepteur génère du code plus efficace.

Si une propriété utilise un type simple, tel qu’un type primitif, la valeur par défaut peut être définie en appliquant la DefaultValueAttribute à la propriété. Toutefois, les propriétés avec cet attribut ne commencent pas automatiquement par cette valeur affectée. Vous devez définir le champ de sauvegarde de la propriété sur la même valeur par défaut. Vous pouvez définir la propriété sur la déclaration ou dans le constructeur de la classe.

Lorsqu’une propriété est un type complexe ou que vous souhaitez contrôler le comportement de réinitialisation et de sérialisation du concepteur, définissez les méthodes Reset<PropertyName> et ShouldSerialize<PropertyName> sur la classe. Par exemple, si le contrôle définit une propriété Age, les méthodes sont nommées ResetAge et ShouldSerializeAge.

Les propriétés peuvent être « réinitialisées » à leurs valeurs par défaut via la fenêtre Propriétés en cliquant avec le bouton droit sur le nom de la propriété et en sélectionnant Réinitialiser.

La disponibilité de l'option de menu contextuel Propriétés>Clic-droit>Réinitialiser est activée lorsque :

• La propriété a l’attribut DefaultValueAttribute appliqué et la valeur de la propriété ne correspond pas à la valeur de l’attribut.
• La classe de la propriété définit une méthode Reset<PropertyName> sans ShouldSerialize<PropertyName>.
• La classe de la propriété définit une méthode Reset<PropertyName> et la ShouldSerialize<PropertyName> retourne true.

DefaultValueAttribute

Si la valeur d’une propriété ne correspond pas à la valeur fournie par , la propriété est considérée comme modifiée et peut être réinitialisée via la fenêtre propriétés .

Le code suivant déclare deux propriétés, une énumération avec une valeur par défaut de North et un entier avec une valeur par défaut 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

Réinitialiser et ShouldSerialize

Comme mentionné précédemment, les méthodes Reset<PropertyName> et ShouldSerialize<PropertyName> permettent de guider non seulement le comportement de réinitialisation d’une propriété, mais également de déterminer si une valeur est modifiée et doit être sérialisée dans le fichier code-behind du concepteur. Les deux méthodes fonctionnent ensemble et vous ne devez pas définir l’une sans l’autre.

Lorsque Reset<PropertyName> est défini, la fenêtre Propriétés affiche une option de menu contextuel Réinitialiser pour cette propriété. Lorsque Réinitialiser est sélectionné, la méthode Reset<PropertyName> est appelée. L’option de menu contextuel Réinitialiser est activée ou désactivée en fonction de ce que renvoie la méthode ShouldSerialize<PropertyName>. Lorsque ShouldSerialize<PropertyName> retourne true, il indique que la propriété a changé de sa valeur par défaut et qu’elle doit être sérialisée dans le fichier code-behind et active l’option de menu contextuel Réinitialiser. Lorsque false est retourné, l’option de menu contextuel Réinitialiser est désactivée et le code associé à la propriété du code-behind est supprimé.

L’extrait de code suivant déclare une propriété nommée Direction. Le comportement du concepteur de cette propriété est contrôlé par les méthodes ResetDirection et 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

Convertisseurs de types

Bien que les convertisseurs de types convertissent généralement un type en un autre, ils fournissent également une conversion de chaîne en valeur pour la grille de propriétés et d’autres contrôles au moment de la conception. La conversion de chaîne à valeur permet de représenter des propriétés complexes dans ces contrôles au moment du design.

La plupart des types de données intégrés (nombres, énumérations et autres) ont des convertisseurs de types par défaut qui fournissent des conversions de chaîne à valeur et effectuent des vérifications de validation. Les convertisseurs de type par défaut se trouvent dans l'espace de noms System.ComponentModel et portent le nom du type qu'ils convertissent. Les noms de types de convertisseur utilisent le format suivant : {type name}Converter. Par exemple, StringConverter, TimeSpanConverteret Int32Converter.

Les convertisseurs de types sont largement utilisés au moment de la conception avec la fenêtre Propriétés. Un convertisseur de type peut être appliqué à une propriété ou à un type à l’aide de l'TypeConverterAttribute.

La fenêtre Propriétés utilise des convertisseurs pour afficher la propriété sous forme de valeur de chaîne lorsque le TypeConverterAttribute est déclaré sur la propriété. Lorsque le TypeConverterAttribute est déclaré sur un type, la fenêtre Propriétés utilise le convertisseur sur chaque propriété de ce type. Le convertisseur de types permet également de sérialiser la valeur de propriété dans le fichier code-behind du concepteur.

Éditeurs de type

La fenêtre Propriétés utilise automatiquement un éditeur de type pour une propriété lorsque le type de la propriété est un type intégré ou connu. Par exemple, une valeur booléenne est éditée en tant que zone de liste modifiable avec les valeurs Vrai et Faux, et le type DateTime utilise une liste déroulante de calendrier.