Propriétés au moment du design pour les contrôles personnalisés (Windows Forms .NET)

  • Article

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 System.Windows.Forms.Controlde base, telles que :

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.

Important

La documentation du Guide du bureau pour .NET 7 et .NET 6 est en cours de construction.

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 le 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 La vue d’ensemble des attributs (C#) ou des attributs (Visual Basic).

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

<Browsable(False)>
Public Property IsSelected As Boolean

[REMARQUE] Les propriétés complexes qui ne peuvent pas être converties implicitement vers et à partir d’une chaîne nécessitent un convertisseur de type.

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’attributDefaultValueAttribute, ou que la classe de la propriété contient des méthodes et ShouldSerialize spécifiques Reset à la propriété. Pour plus d’informations sur les attributs, consultez La vue d’ensemble des attributs (C#) ou 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 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 stockage 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 et ShouldSerialize<PropertyName> les Reset<PropertyName> méthodes sur la classe. Par exemple, si le contrôle définit une Age propriété, les méthodes sont nommées ResetAge et ShouldSerializeAge.

Important

Appliquez la DefaultValueAttribute propriété ou fournissez les deux Reset<PropertyName>ShouldSerialize<PropertyName> méthodes. N’utilisez pas les deux.

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.

Élément de menu contextuel Réinitialiser dans la grille des propriétés.

La disponibilité de l’option de menu contextuel Réinitialiser avec le bouton>droit des propriétés>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 Reset<PropertyName> méthode sans .ShouldSerialize<PropertyName>
  • La classe de la propriété définit une Reset<PropertyName> méthode et renvoie la ShouldSerialize<PropertyName> valeur true.

DefaultValueAttribute

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

Important

Cet attribut ne doit pas être utilisé sur les propriétés qui ont des méthodes et ShouldSerialize<PropertyName> des correspondances correspondantesReset<PropertyName>.

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 Reset<PropertyName> méthodes et ShouldSerialize<PropertyName> les méthodes 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.

Important

Les Reset<PropertyName> méthodes et ShouldSerialize<PropertyName> les méthodes ne doivent pas être créées pour une propriété qui a un DefaultValueAttribute.

Quand Reset<PropertyName> elle est définie, la fenêtre Propriétés affiche une option de menu contextuel Réinitialiser pour cette propriété. Lorsque la réinitialisation est sélectionnée, la Reset<PropertyName> méthode est appelée. L’option de menu contextuel Réinitialiser est activée ou désactivée par ce qui est retourné par la ShouldSerialize<PropertyName> méthode. Quand ShouldSerialize<PropertyName> elle est retournée true, elle 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 . Quand false elle est retournée, l’option de menu contextuel Réinitialiser est désactivée et le code-behind a le code défini par la propriété supprimé.

Conseil

Les deux méthodes peuvent et doivent être définies avec une étendue privée afin qu’elles ne composent pas l’API publique du contrôle.

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 et ShouldSerializeDirection les ResetDirection méthodes.

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 type

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 du design. 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 case activée de validation. Les convertisseurs de type par défaut se trouvent dans l’espace System.ComponentModel de noms et sont nommés après la conversion du type. Les noms de types de convertisseur utilisent le format suivant : {type name}Converter. Par exemple, StringConverter, TimeSpanConverter ou Int32Converter.

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

La fenêtre Propriétés utilise des convertisseurs pour afficher la propriété sous forme de valeur de chaîne lorsque celle-ci TypeConverterAttribute est déclarée sur la propriété. Lorsque la TypeConverterAttribute valeur est déclarée 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 modifiée en tant que zone de liste modifiable avec des valeurs True et False et le DateTime type utilise une liste déroulante calendrier.

Important

Les éditeurs de types personnalisés ont changé depuis .NET Framework. Pour plus d’informations, consultez Le concepteur change depuis .NET Framework (Windows Forms .NET).