Propriétés UI Automation pour les clients
Notes
Cette documentation s’adresse aux développeurs .NET Framework qui souhaitent utiliser les classes UI Automation managées définies dans l’espace de noms System.Windows.Automation. Pour obtenir les dernières informations sur UI Automation, consultez API Windows Automation : UI Automation.
Cette vue d’ensemble présente les propriétés UI Automation telles qu’elles sont exposées aux applications clientes UI Automation.
Les propriétés des objets AutomationElement contiennent des informations sur les éléments d’interface utilisateur, généralement les contrôles. Les propriétés de AutomationElement sont génériques. En d’autres termes, elles ne sont pas spécifiques à un type de contrôle. Un grand nombre de ces propriétés est exposé dans la structure AutomationElement.AutomationElementInformation .
Les modèles de contrôle ont également des propriétés. Les propriétés des modèles de contrôle sont spécifiques au modèle. Par exemple, ScrollPattern possède des 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 ainsi que 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 les 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 changer les valeurs de position d’une fenêtre de défilement.
Pour améliorer les performances, vous pouvez mettre en cache les valeurs des propriétés des contrôles et des modèles de contrôle quand des objets AutomationElement sont récupérés. Pour plus d’informations, consultez Mise en cache dans les clients UI Automation.
ID de propriété
Les ID de propriété sont des valeurs constantes, uniques, encapsulées dans des objets AutomationProperty. Les applications clientes UI Automation obtiennent ces ID à partir de la classe AutomationElement, ou de la classe de modèle de contrôle appropriée, par exemple ScrollPattern. Les fournisseurs UI Automation les obtiennent à partir de AutomationElementIdentifiers , ou de l’une des classes d’identificateurs de modèle de contrôle, par exemple ScrollPatternIdentifiers.
Les fournisseurs utilisent l’ Id numérique de AutomationProperty pour identifier les propriétés interrogées dans la méthode IRawElementProviderSimple.GetPropertyValue . En général, les applications clientes n’ont pas besoin d’examiner l’Id. L’ProgrammaticName est utilisé uniquement à des fins de débogage et de diagnostic.
Conditions de propriété
Les ID de propriété sont utilisés dans la construction des objets PropertyCondition permettant de rechercher des objets AutomationElement. Par exemple, vous pouvez être amené à rechercher un AutomationElement ayant un nom spécifique, ou tous les contrôles qui sont activés. Chaque PropertyCondition spécifie un identificateur AutomationProperty et la valeur à laquelle la propriété doit correspondre.
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èle de contrôle sont exposées en tant que propriétés imbriquées de la propriété Current ou Cached de AutomationElement ou de l’objet de modèle de contrôle.
En outre, AutomationElement ou les propriétés de modèles de contrôle, ainsi que les propriétés non disponibles dans la structure Cached ou Current , peuvent être récupérés via l’une des méthodes suivantes :
Ces méthodes offrent des performances un peu meilleures, ainsi qu’un accès à la gamme complète des propriétés.
L’exemple de code suivant montre deux façons de récupérer une propriété sur AutomationElement.
// elementList is an AutomationElement.
// The following two calls are equivalent.
string name = elementList.Current.Name;
name = elementList.GetCurrentPropertyValue(AutomationElement.NameProperty) as string;
' elementList is an AutomationElement.
' The following two calls are equivalent.
Dim name As String = elementList.Current.Name
name = CStr(elementList.GetCurrentPropertyValue(AutomationElement.NameProperty))
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. Transmettez simplement l’un des identificateurs de propriété de modèle à la méthode.
L’exemple de code suivant montre deux façons 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.
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);
' 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))
Les méthodes Get retournent Object. L’application doit effectuer un cast de l’objet retourné vers le type approprié avant d’utiliser la valeur.
Valeurs de propriété par défaut
Si un fournisseur UI Automation n’implémente pas une 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 même, si le fournisseur ne prend pas en charge la propriété identifiée par IsDockPatternAvailableProperty, UI Automation retourne false.
Vous pouvez changer ce comportement à l’aide des surcharges de méthode AutomationElement.GetCachedPropertyValue et AutomationElement.GetCurrentPropertyValue . Quand vous spécifiez true comme second paramètre, UI Automation ne retourne pas de valeur par défaut mais la valeur spéciale NotSupported.
L’exemple de code suivant tente de récupérer une propriété d’un élément. 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.
object help = elementList.GetCurrentPropertyValue(AutomationElement.HelpTextProperty, true);
if (help == AutomationElement.NotSupported)
{
help = "No help available";
}
string helpText = (string)help;
' 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)
Pour découvrir les propriétés prises en charge par un élément, utilisez GetSupportedProperties. Un tableau d’identificateurs AutomationProperty est retourné.
Événements de modification de propriété
Quand une valeur de propriété change pour 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, et en fournissant un tableau d’identificateurs AutomationProperty comme dernier paramètre pour spécifier les propriétés pertinentes.
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 ayant changé. Ces valeurs sont de type Object , et doivent être castées vers le type approprié avant d’être utilisées.
Propriétés AutomationElement supplémentaires
Outre les structures de propriété Current et Cached , AutomationElement possède les 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 qui se trouvent dans le cache. |
| CachedParent | Objet parent AutomationElement qui se trouve dans le cache. |
| FocusedElement | (Propriété statique) AutomationElement ayant le focus d’entrée. |
| RootElement | (Propriété statique) AutomationElementracine. |