Partager via


Propriétés UI Automation pour les clients

RemarqueRemarque

Cette documentation s'adresse aux développeurs .NET Framework qui veulent utiliser les classes UI Automation managées définies dans l'espace de noms System.Windows.Automation.Pour obtenir les informations les plus récentes sur UI Automation, consultez API Windows Automation : UI Automation (page éventuellement en anglais).

Cette vue d'ensemble présente les propriétés UI Automation telles qu'elles sont exposées aux applications du client UI Automation.

Les propriétés sur les objets AutomationElement contiennent des informations sur les éléments d'user interface (UI), généralement les contrôles. Les propriétés d'un AutomationElement sont génériques, c'est-à-dire qu'elles ne sont pas propres à un type de contrôle. Beaucoup de ces propriétés sont exposées dans la structure AutomationElement.AutomationElementInformation.

Les modèles de contrôle possèdent également des propriétés. Les propriétés des modèles de contrôle sont propres au modèle. Par exemple, ScrollPattern dispose de propriétés qui permettent à une application cliente de déterminer si une fenêtre peut faire l'objet d'un défilement vertical ou horizontal, et de connaître les tailles d'affichage et les positions de défilement actuelles. Les modèles de contrôle exposent toutes leurs propriétés via une structure, par exemple ScrollPattern.ScrollPatternInformation.

Les propriétés UI Automation sont en lecture seule. Pour définir des propriétés d'un contrôle, vous devez utiliser les méthodes du modèle de contrôle approprié. Par exemple, utilisez Scroll pour modifier les valeurs de position d'une fenêtre de défilement.

Pour améliorer les performances, les valeurs de propriété des contrôles et modèles de contrôle peuvent être mises en cache lorsque des objets AutomationElement sont récupérés. Pour plus d'informations, consultez Mise en cache dans les clients UI Automation.

Cette rubrique comprend les sections suivantes.

  • ID de propriété
  • Conditions de propriétés
  • Récupération de propriétés
  • Valeurs de propriété par défaut
  • Événements de modification de propriété
  • Propriétés AutomationElement supplémentaires
  • Rubriques connexes

ID de propriété

Les identifiers (IDs) de propriété sont des valeurs constantes uniques encapsulées dans des objets AutomationProperty. Les applications Client UI Automation obtiennent ces IDs de la classe AutomationElement ou de la classe de modèle de contrôle appropriée, telle que ScrollPattern. Les fournisseurs UI Automation les obtiennent de AutomationElementIdentifiers ou de l'une des classes d'identificateurs de modèle de contrôle, telles que ScrollPatternIdentifiers.

L'Id numérique d'un AutomationProperty est utilisé par les fournisseurs pour identifier les propriétés demandées dans la méthode IRawElementProviderSimple.GetPropertyValue. En général, les applications clientes n'ont pas besoin d'examiner l'Id. Le ProgrammaticName n'est utilisé que pour le débogage et le diagnostic.

Conditions de propriétés

Les IDs de propriété sont utilisés pour la génération des objets PropertyCondition utilisés pour rechercher des objets AutomationElement. Par exemple, vous souhaiterez peut-être rechercher un AutomationElement avec un nom spécifique ou bien tous les contrôles qui sont activés. Chaque PropertyCondition spécifie un identificateur AutomationProperty et la valeur à laquelle doit correspondre la propriété.

Pour plus d'informations, consultez les rubriques de référence suivantes :

Récupération de propriétés

Certaines propriétés de AutomationElement et toutes les propriétés d'une classe de modèles de contrôle sont exposées comme propriétés imbriquées de la propriété Current ou Cached de AutomationElement ou de l'objet de modèle de contrôle.

De plus, tout AutomationElement ou toute propriété de modèle de contrôle, y compris toute propriété non disponible dans la structure Cached ou Current, peut être récupéré à l'aide de l'une des méthodes suivantes :

Ces méthodes offrent des performances légèrement meilleures et un accès à la gamme complète des propriétés.

L'exemple de code suivant présente les deux manières de récupérer une propriété sur un AutomationElement.

' elementList is an AutomationElement.
' The following two calls are equivalent.
Dim name As String = elementList.Current.Name
name = CStr(elementList.GetCurrentPropertyValue(AutomationElement.NameProperty))
// elementList is an AutomationElement.

// The following two calls are equivalent.
string name = elementList.Current.Name;
name = elementList.GetCurrentPropertyValue(AutomationElement.NameProperty) as string;

Pour récupérer les propriétés de modèles de contrôle pris en charge par AutomationElement, vous n'avez pas besoin de récupérer l'objet de modèle de contrôle. Il suffit de passer l'un des identificateurs de propriété de modèle à la méthode.

L'exemple de code suivant présente les deux manières de récupérer une propriété sur un modèle de contrôle.

' elementList is an AutomationElement representing a list box.
' Error-checking is omitted. Assume that elementList is known to support SelectionPattern.
Dim selectPattern As SelectionPattern = _
    DirectCast(elementList.GetCurrentPattern(SelectionPattern.Pattern), SelectionPattern)
Dim isMultipleSelect As Boolean = selectPattern.Current.CanSelectMultiple

' The following call is equivalent to the one above.
isMultipleSelect = CBool(elementList.GetCurrentPropertyValue(SelectionPattern.CanSelectMultipleProperty))
// elementList is an AutomationElement representing a list box.
// Error-checking is omitted. Assume that elementList is known to support SelectionPattern.

SelectionPattern selectPattern =
    elementList.GetCurrentPattern(SelectionPattern.Pattern) as SelectionPattern;
bool isMultipleSelect = selectPattern.Current.CanSelectMultiple;

// The following call is equivalent to the one above.
isMultipleSelect = (bool)
    elementList.GetCurrentPropertyValue(SelectionPattern.CanSelectMultipleProperty);

Les méthodes Get retournent un Object. L'application doit effectuer un cast de l'objet retourné en type approprié avant d'utiliser la valeur.

Valeurs de propriété par défaut

Si un fournisseur UI Automation n'implémente pas de propriété, le système UI Automation peut fournir une valeur par défaut. Par exemple, si le fournisseur d'un contrôle ne prend pas en charge la propriété identifiée par HelpTextProperty, UI Automation retourne une chaîne vide. De la même façon, si le fournisseur ne prend pas en charge la propriété identifiée par IsDockPatternAvailableProperty, UI Automation retourne false.

Vous pouvez modifier ce comportement en utilisant les surcharges de méthode AutomationElement.GetCachedPropertyValue et AutomationElement.GetCurrentPropertyValue. Lorsque vous spécifiez true comme second paramètre, UI Automation ne retourne pas de valeur par défaut, mais retourne la valeur spéciale NotSupported.

L'exemple de code suivant tente de récupérer une propriété d'un élément, et si la propriété n'est pas prise en charge, une valeur définie par l'application est utilisée à la place.

' elementList is an AutomationElement.
Dim help As Object = elementList.GetCurrentPropertyValue(AutomationElement.HelpTextProperty, True)
If help Is AutomationElement.NotSupported Then
    help = "No help available"
End If
Dim helpText As String = CStr(help)
// elementList is an AutomationElement.
object help = elementList.GetCurrentPropertyValue(AutomationElement.HelpTextProperty, true);
if (help == AutomationElement.NotSupported)
{
    help = "No help available";
}
string helpText = (string)help;

Pour découvrir les propriétés qui sont prises en charge par un élément, utilisez GetSupportedProperties. Un tableau d'identificateurs AutomationProperty est ainsi retourné.

Événements de modification de propriété

Lorsqu'une valeur de propriété change sur un AutomationElement ou un modèle de contrôle, un événement est déclenché. Une application peut s'abonner à ces événements en appelant AddAutomationPropertyChangedEventHandler, en fournissant un tableau d'identificateurs AutomationProperty comme dernier paramètre afin de spécifier les propriétés qui présentent un intérêt.

Dans AutomationPropertyChangedEventHandler, vous pouvez identifier la propriété qui a changé en vérifiant le membre Property des arguments d'événement. Les arguments contiennent également les valeurs anciennes et nouvelles de la propriété UI Automation qui a changé. Ces valeurs sont du type Object et doivent être castées en type correct avant d'être utilisées.

Propriétés AutomationElement supplémentaires

Outre les structures de propriété Current et Cached, AutomationElement dispose des propriétés suivantes qui sont récupérées via des accesseurs de propriétés simples.

Propriété

Description

CachedChildren

Collection d'objets AutomationElement enfants situés dans le cache.

CachedParent

Objet parent AutomationElement situé dans le cache.

FocusedElement

(Propriété statique) AutomationElement ayant le focus d'entrée.

RootElement

(Propriété statique) AutomationElement racine.

Voir aussi

Tâches

S'abonner à des événements UI Automation

Concepts

Mise en cache dans les clients UI Automation

Implémentation de fournisseur UI Automation côté serveur