Partager via

Métadonnées de propriété de dépendance (WPF .NET)

  • Article

Le système de propriétés Windows Presentation Foundation (WPF) inclut un système de rapports de métadonnées de propriété de dépendance. Les informations disponibles via le système de rapports de métadonnées dépassent ce qui est accessible par les caractéristiques générales du CLR (Common Language Runtime) ou par la réflexion. Lorsque vous inscrivez une propriété de dépendance, vous avez la possibilité de créer et d’affecter des métadonnées. Si vous dérivez d’une classe qui définit une propriété de dépendance, vous pouvez remplacer les métadonnées de la propriété de dépendance héritée. Et, si vous ajoutez votre classe en tant que propriétaire d’une propriété de dépendance, vous pouvez remplacer les métadonnées de la propriété de dépendance héritée.

Conditions préalables

L’article suppose une connaissance de base des propriétés de dépendance et que vous avez lu vue d’ensemble des propriétés de dépendance. Pour suivre les exemples de cet article, il vous aide à connaître le langage XAML (Extensible Application Markup Language) et à savoir comment écrire des applications WPF.

Utilisation des métadonnées

Vous pouvez interroger les métadonnées de propriété de dépendance pour examiner les caractéristiques d’une propriété de dépendance. Lorsque le système de propriétés traite une propriété de dépendance, il accède à ses métadonnées. L’objet de métadonnées d’une propriété de dépendance contient les types d’informations suivants :

  • Valeur par défaut de la propriété de dépendance, qui est définie par le système de propriétés lorsqu’aucune autre valeur ne s’applique, telle qu’une valeur locale, de style ou d’héritage. Pour plus d'informations sur la précedence des valeurs lors de l'assignation à l'exécution des valeurs des propriétés de dépendance, consultez précedence des valeurs des propriétés de dépendance.

  • Références aux fonctions de rappel de valeur de contrainte et aux fonctions de rappel de modification de propriété sur le type propriétaire. Vous pouvez uniquement obtenir des références aux callbacks qui ont un modificateur d’accès public ou qui se trouvent dans votre périmètre d'accès autorisé. Pour plus d’informations sur les rappels de propriétés de dépendance, consultez rappels de propriétés de dépendance etde validation.

  • Caractéristiques de propriété de dépendance au niveau du framework WPF (si la propriété de dépendance est une propriété d’infrastructure WPF). Les processus WPF, tels que le moteur de disposition du cadre et la logique d'héritage de propriété, interrogent les métadonnées au niveau du cadre WPF. Pour plus d’informations, consultez métadonnées de propriété Framework.

API de métadonnées

La classe PropertyMetadata stocke la plupart des métadonnées utilisées par le système de propriétés. Les instances de métadonnées peuvent être créées et affectées par :

  • Types qui inscrivent les propriétés de dépendance avec le système de propriétés.

  • Types qui héritent d’une classe qui définit une propriété de dépendance.

  • Types qui s’ajoutent en tant que propriétaire d’une propriété de dépendance.

Si un type inscrit une propriété de dépendance sans spécifier de métadonnées, le système de propriétés affecte un objet PropertyMetadata avec des valeurs par défaut pour ce type à la propriété de dépendance.

Pour récupérer les métadonnées d’une propriété de dépendance, utilisez l’une des surcharges de GetMetadata sur l’identificateur DependencyProperty. Les métadonnées sont retournées en tant qu’objet PropertyMetadata.

Des classes de métadonnées plus spécifiques, dérivées de PropertyMetadata, existent pour différentes zones architecturales. Par exemple, UIPropertyMetadata prend en charge les rapports d’animation et FrameworkPropertyMetadata prend en charge les propriétés de l’infrastructure WPF. Les propriétés de dépendance peuvent également être enregistrées par les classes dérivées PropertyMetadata. Bien que GetMetadata retourne un objet PropertyMetadata, le cas échéant, vous pouvez effectuer un cast vers un type dérivé pour examiner les propriétés spécifiques au type.

Les caractéristiques de propriété exposées par FrameworkPropertyMetadata sont parfois appelées indicateurs . Lorsque vous créez une instance FrameworkPropertyMetadata, vous avez la possibilité de passer une instance du type d’énumération FrameworkPropertyMetadataOptions dans le constructeur FrameworkPropertyMetadata. FrameworkPropertyMetadataOptions vous permet de spécifier des indicateurs de métadonnées dans une combinaison au niveau du bit. Le FrameworkPropertyMetadata utilise FrameworkPropertyMetadataOptions afin de maintenir la longueur de sa signature de constructeur à un niveau raisonnable. Lors de l'enregistrement des propriétés de dépendance, les indicateurs de métadonnées que vous définissez sur FrameworkPropertyMetadataOptions sont exposés dans FrameworkPropertyMetadata en tant que propriétés Boolean plutôt qu’une combinaison bit-à-bit d’indicateurs, afin de rendre les caractéristiques des métadonnées plus intuitives.

Remplacer ou créer de nouvelles métadonnées ?

Lorsque vous héritez d’une propriété de dépendance, vous avez la possibilité de modifier les caractéristiques de la propriété de dépendance en substituant ses métadonnées. Toutefois, vous ne pourrez peut-être pas toujours accomplir votre scénario de propriété de dépendance en substituant les métadonnées, et il est parfois nécessaire de définir une propriété de dépendance personnalisée dans votre classe avec de nouvelles métadonnées. Les propriétés de dépendance personnalisées ont les mêmes fonctionnalités que les propriétés de dépendance définies par les types WPF. Pour plus d’informations, consultez propriétés de dépendance personnalisées.

L’une des caractéristiques d’une propriété de dépendance que vous ne pouvez pas remplacer est son type valeur. Si une propriété de dépendance héritée a le comportement approximatif dont vous avez besoin, mais que votre scénario nécessite un type de valeur différent, envisagez d’implémenter une propriété de dépendance personnalisée. Vous pouvez peut-être lier les valeurs de propriété par le biais de la conversion de type ou d’une autre implémentation dans votre classe dérivée.

Scénarios de substitution des métadonnées

Les exemples de scénarios de substitution des métadonnées de propriété de dépendance existantes sont les suivants :

  • Modification de la valeur par défaut, qui est un scénario courant.

  • Modification ou ajout de rappels de modification de propriété, ce qui peut être nécessaire si une propriété de dépendance héritée interagit avec d’autres propriétés de dépendance différemment de son implémentation de base. L’une des caractéristiques d’un modèle de programmation qui prend en charge le code et le balisage, est que les valeurs de propriété peuvent être définies dans n’importe quel ordre. Ce facteur peut affecter la façon dont vous implémentez des notifications de changement de propriété. Pour plus d’informations, consultez les rappels de propriétés de dépendance et la validation.

  • Modification des options des métadonnées de propriété du framework WPF . En règle générale, les options de métadonnées sont définies lors de l’inscription d’une nouvelle propriété de dépendance, mais vous pouvez les re-spécifier dans les appels OverrideMetadata ou AddOwner. Pour plus d'informations sur la redéfinition des métadonnées de propriété de cadre, consultez Specifying FrameworkPropertyMetadata. Pour savoir comment définir des options de métadonnées pour les propriétés de cadre lors de l'enregistrement d'une propriété de dépendance, consultez Propriétés de dépendance personnalisées.

Note

Étant donné que les rappels de validation ne font pas partie des métadonnées, ils ne peuvent pas être modifiés en substituant les métadonnées. Pour plus d’informations, consultez rappels de valeurs de validation.

Modification des métadonnées

Lors de l’implémentation d’une nouvelle propriété de dépendance, vous pouvez définir ses métadonnées à l’aide de surcharges de la méthode Register. Si votre classe hérite d’une propriété de dépendance, vous pouvez remplacer les valeurs de métadonnées héritées à l’aide de la méthode OverrideMetadata. Par exemple, vous pouvez utiliser OverrideMetadata pour définir des valeurs spécifiques au type. Pour plus d’informations et d’exemples de code, consultez Remplacer les métadonnées d’une propriété de dépendance.

Un exemple de propriété de dépendance WPF est Focusable. La classe FrameworkElement inscrit Focusable. La classe Control dérive de FrameworkElement, hérite de la propriété de dépendance Focusable et remplace les métadonnées de propriété héritées. La substitution modifie la valeur de propriété par défaut de false en true, mais conserve d’autres valeurs de métadonnées héritées.

Étant donné que la plupart des propriétés de dépendance existantes ne sont pas des propriétés virtuelles, leur implémentation héritée ombrage le membre existant. Lorsque vous remplacez une caractéristique de métadonnées, la nouvelle valeur de métadonnées remplace la valeur d’origine ou elle est fusionnée :

  • Pour un DefaultValue, la nouvelle valeur remplace la valeur par défaut existante. Si vous ne spécifiez pas de DefaultValue dans les métadonnées de remplacement, la valeur provient de l’ancêtre le plus proche spécifié DefaultValue dans les métadonnées.

  • Pour un PropertyChangedCallback, la logique de fusion par défaut stocke toutes les valeurs PropertyChangedCallback dans une table, et toutes sont appelées sur une modification de propriété. L’ordre de rappel est déterminé par la profondeur de classe, où un rappel enregistré par la classe de base dans la hiérarchie sera exécuté en premier.

  • Pour un CoerceValueCallback, la nouvelle valeur remplace la valeur CoerceValueCallback existante. Si vous ne spécifiez pas de CoerceValueCallback dans les métadonnées de remplacement, la valeur provient de l’ancêtre le plus proche spécifié CoerceValueCallback dans les métadonnées.

Note

La logique de fusion par défaut est implémentée par la méthode Merge. Vous pouvez spécifier une logique de fusion personnalisée dans une classe dérivée qui hérite d’une propriété de dépendance, en substituant Merge dans cette classe.

Ajouter une classe en tant que propriétaire

Pour « hériter » d’une propriété de dépendance inscrite dans une hiérarchie de classes différente, utilisez la méthode AddOwner. Cette méthode est généralement utilisée lorsque la classe d’ajout n’est pas dérivée du type qui a inscrit la propriété de dépendance. Dans l’appel AddOwner, la classe d’ajout peut créer et affecter des métadonnées spécifiques au type pour la propriété de dépendance héritée. Pour être un participant complet au système de propriétés, par le biais du code et du balisage, la classe d’ajout doit implémenter ces membres publics :

  • Champ d’identificateur de propriété de dépendance. La valeur de l’identificateur de propriété de dépendance est la valeur de retour de l’appel AddOwner. Ce champ doit être un champ public static readonly de type DependencyProperty.

  • Un wrapper CLR qui implémente les accesseurs get et set. En utilisant un wrapper de propriété, les utilisateurs des propriétés de dépendance peuvent obtenir ou définir les valeurs de ces propriétés, comme ils le feraient pour n'importe quelle autre propriété CLR. Les accesseurs get et set interagissent avec le système de propriétés sous-jacent via les appels DependencyObject.GetValue et DependencyObject.SetValue, passant l’identificateur de propriété de dépendance en tant que paramètre. Implémentez le wrapper de la même façon que vous le feriez lors de l’inscription d’une propriété de dépendance personnalisée. Pour plus d’informations, consultez propriétés de dépendance personnalisées

Une classe qui appelle AddOwner a les mêmes exigences pour exposer le modèle objet de la propriété de dépendance héritée en tant que classe qui définit une nouvelle propriété de dépendance personnalisée. Pour plus d’informations, consultez Ajouter un type de propriétaire pour une propriété de dépendance.

Métadonnées de propriété jointes

Dans WPF, la plupart des propriétés jointes liées à l’interface utilisateur sur les types WPF sont implémentées en tant que propriétés de dépendance. Les propriétés jointes implémentées en tant que propriétés de dépendance prennent en charge les concepts de propriété de dépendance, tels que les métadonnées que les classes dérivées peuvent remplacer. Les métadonnées d’une propriété jointe ne sont généralement pas différentes de celles d’une propriété de dépendance. Vous pouvez remplacer la valeur par défaut, les rappels de modification de propriété et les propriétés de l’infrastructure WPF pour la propriété jointe héritée, sur les instances de la classe de substitution. Pour plus d'informations, consultez les métadonnées de la propriété attachée

Note

Utilisez toujours RegisterAttached pour inscrire les propriétés dans lesquelles vous spécifiez Inherits dans les métadonnées. Bien que l’héritage de valeur de propriété semble fonctionner pour les propriétés de dépendance non attachées, le comportement d’héritage de valeur d’une propriété non attachée via certaines divisions d’objet-objet dans l’arborescence runtime n’est pas défini. La propriété Inherits n’est pas pertinente pour les propriétés non attachées. Pour plus d’informations, consultez RegisterAttached(String, Type, Type, PropertyMetadata)et la section remarques de Inherits.

Ajouter une classe en tant que propriétaire d’une propriété jointe

Pour hériter d’une propriété jointe d’une autre classe, mais l’exposer en tant que propriété de dépendance non attachée sur votre classe :

  • Appelez AddOwner pour ajouter votre classe en tant que propriétaire de la propriété de dépendance attachée.

  • Affectez la valeur de retour de l’appel AddOwner à un champ public static readonly, à utiliser comme identificateur de propriété de dépendance.

  • Définissez un wrapper CLR, qui ajoute la propriété en tant que membre de classe et prend en charge l’utilisation des propriétés non attachées.

Voir aussi