Propriétés UI Automation pour les clientsUI Automation Properties for Clients

Notes

Cette documentation s'adresse aux développeurs .NET Framework qui souhaitent utiliser les classes Automatisation de l’interface utilisateurUI Automation managées définies dans l'espace de noms System.Windows.Automation.This documentation is intended for .NET Framework developers who want to use the managed Automatisation de l’interface utilisateurUI Automation classes defined in the System.Windows.Automation namespace. Pour obtenir les dernières informations sur Automatisation de l’interface utilisateurUI Automation, consultez API Windows Automation : UI Automation.For the latest information about Automatisation de l’interface utilisateurUI Automation, see Windows Automation API: UI Automation.

Cette vue d’ensemble présente les propriétés Automatisation de l’interface utilisateurUI Automation telles qu’elles sont exposées aux applications clientes UI Automation.This overview introduces you to Automatisation de l’interface utilisateurUI Automation properties as they are exposed to UI Automation client applications.

Les propriétés des objets AutomationElement contiennent des informations sur les éléments d’ interface utilisateur (UI)user interface (UI) , généralement les contrôles.Properties on AutomationElement objects contain information about interface utilisateur (UI)user interface (UI) elements, usually controls. 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.The properties of an AutomationElement are generic; that is, not specific to a control type. Un grand nombre de ces propriétés est exposé dans la structure AutomationElement.AutomationElementInformation .Many of these properties are exposed in the AutomationElement.AutomationElementInformation structure.

Les modèles de contrôle ont également des propriétés.Control patterns also have properties. Les propriétés des modèles de contrôle sont spécifiques au modèle.The properties of control patterns are specific to the pattern. 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.For example, ScrollPattern has properties that enable a client application to discover whether a window is vertically or horizontally scrollable, and what the current view sizes and scroll positions are. Les modèles de contrôle exposent toutes leurs propriétés via une structure, par exemple ScrollPattern.ScrollPatternInformation.Control patterns expose all their properties through a structure; for example, ScrollPattern.ScrollPatternInformation.

Les propriétésAutomatisation de l’interface utilisateurUI Automation sont en lecture seule.Automatisation de l’interface utilisateurUI Automation properties are read-only. Pour définir les propriétés d’un contrôle, vous devez utiliser les méthodes du modèle de contrôle approprié.To set properties of a control, you must use the methods of the appropriate control pattern. Par exemple, utilisez Scroll pour changer les valeurs de position d’une fenêtre de défilement.For example, use Scroll to change the position values of a scrolling window.

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.To improve performance, property values of controls and control patterns can be cached when AutomationElement objects are retrieved. Pour plus d’informations, consultez mise en cache dans les clients UI Automation.For more information, see Caching in UI Automation Clients.

ID de propriétéProperty IDs

Les identificateurs de propriété (ID) sont des valeurs constantes uniques qui sont encapsulées dans des AutomationProperty objets.Property identifiers (IDs) are unique, constant values that are encapsulated in AutomationProperty objects. Les applications clientes UI Automation obtiennent ces ID à partir de la AutomationElement classe ou de la classe de modèle de contrôle appropriée, telle que ScrollPattern .UI Automation client applications get these IDs from the AutomationElement class or from the appropriate control pattern class, such as 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.UI Automation providers get them from AutomationElementIdentifiers or from one of the control pattern identifiers classes, such as ScrollPatternIdentifiers.

Les fournisseurs utilisent l’ Id numérique de AutomationProperty pour identifier les propriétés interrogées dans la méthode IRawElementProviderSimple.GetPropertyValue .The numeric Id of an AutomationProperty is used by providers to identify properties that are being queried for in the IRawElementProviderSimple.GetPropertyValue method. En général, les applications clientes n’ont pas besoin d’examiner l’ Id.In general, client applications do not need to examine the Id. ProgrammaticName n’est utilisé que pour le débogage et le diagnostic.The ProgrammaticName is used only for debugging and diagnostic purposes.

Conditions de propriétéProperty Conditions

Les ID de propriété sont utilisés dans la construction des PropertyCondition objets utilisés pour rechercher des AutomationElement objets.The property IDs are used in constructing PropertyCondition objects used to find AutomationElement objects. Par exemple, vous pouvez être amené à rechercher un AutomationElement ayant un nom spécifique, ou tous les contrôles qui sont activés.For example, you might wish to find an AutomationElement that has a certain name, or all controls that are enabled. Chaque PropertyCondition spécifie un identificateur AutomationProperty et la valeur à laquelle la propriété doit correspondre.Each PropertyCondition specifies an AutomationProperty identifier and the value that the property must match.

Pour plus d’informations, consultez les rubriques de référence suivantes :For more information, see the following reference topics:

Récupération de propriétésRetrieving Properties

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.Some properties of AutomationElement and all properties of a control pattern class are exposed as nested properties of the Current or Cached property of the AutomationElement or control pattern object.

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 :In addition, any AutomationElement or control pattern property, including a property that is not available in the Cached or Current structure, can be retrieved by using one of the following methods:

Ces méthodes offrent des performances un peu meilleures, ainsi qu’un accès à la gamme complète des propriétés.These methods offer slightly better performance as well as access to the full range of properties.

L’exemple de code suivant montre deux façons de récupérer une propriété sur AutomationElement.The following code example shows the two ways of retrieving a property on an 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.To retrieve properties of control patterns supported by the AutomationElement, you do not need to retrieve the control pattern object. Transmettez simplement l’un des identificateurs de propriété de modèle à la méthode.Simply pass one of the pattern property identifiers to the method.

L’exemple de code suivant montre deux façons de récupérer une propriété sur un modèle de contrôle.The following code example shows the two ways of retrieving a property on a control pattern.

// 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.The Get methods return an Object. L’application doit effectuer un cast de l’objet retourné vers le type approprié avant d’utiliser la valeur.The application must cast the returned object to the proper type before using the value.

Valeurs de propriété par défautDefault Property Values

Si un fournisseur UI Automation n’implémente pas une propriété, le système Automatisation de l’interface utilisateurUI Automation peut fournir une valeur par défaut.If a UI Automation provider does not implement a property, the Automatisation de l’interface utilisateurUI Automation system is able to supply a default value. Par exemple, si le fournisseur d’un contrôle ne prend pas en charge la propriété identifiée par HelpTextProperty, Automatisation de l’interface utilisateurUI Automation retourne une chaîne vide.For example, if the provider for a control does not support the property identified by HelpTextProperty, Automatisation de l’interface utilisateurUI Automation returns an empty string. De même, si le fournisseur ne prend pas en charge la propriété identifiée par IsDockPatternAvailableProperty, Automatisation de l’interface utilisateurUI Automation retourne false.Similarly, if the provider does not support the property identified by IsDockPatternAvailableProperty, Automatisation de l’interface utilisateurUI Automation returns false.

Vous pouvez changer ce comportement à l’aide des surcharges de méthode AutomationElement.GetCachedPropertyValue et AutomationElement.GetCurrentPropertyValue .You can change this behavior by using the AutomationElement.GetCachedPropertyValue and AutomationElement.GetCurrentPropertyValue method overloads. Quand vous spécifiez true comme second paramètre, Automatisation de l’interface utilisateurUI Automation ne retourne pas de valeur par défaut mais la valeur spéciale NotSupported.When you specify true as the second parameter, Automatisation de l’interface utilisateurUI Automation does not return a default value, but instead returns the special value 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.The following example code attempts to retrieve a property from an element, and if the property is not supported, an application-defined value is used instead.

// 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.To discover what properties are supported by an element, use GetSupportedProperties. Un tableau d’identificateurs AutomationProperty est retourné.This returns an array of AutomationProperty identifiers.

Événements de modification de propriétéProperty-changed Events

Quand une valeur de propriété change pour AutomationElement ou un modèle de contrôle, un événement est déclenché.When a property value on an AutomationElement or control pattern changes, an event is raised. 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.An application can subscribe to such events by calling AddAutomationPropertyChangedEventHandler, supplying an array of AutomationProperty identifiers as the last parameter in order to specify the properties of interest.

Dans AutomationPropertyChangedEventHandler, vous pouvez identifier la propriété qui a changé en vérifiant le membre Property des arguments d’événement.In the AutomationPropertyChangedEventHandler, you can identify the property that has changed by checking the Property member of the event arguments. Les arguments contiennent également les valeurs anciennes et nouvelles de la propriété Automatisation de l’interface utilisateurUI Automation ayant changé.The arguments also contain the old and new values of the Automatisation de l’interface utilisateurUI Automation property that has changed. Ces valeurs sont de type Object , et doivent être castées vers le type approprié avant d’être utilisées.These values are of type Object and must be cast to the correct type before being used.

Propriétés AutomationElement supplémentairesAdditional AutomationElement Properties

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.In addition to the Current and Cached property structures, AutomationElement has the following properties, which are retrieved through simple property accessors.

PropriétéProperty DescriptionDescription
CachedChildren Collection d’objets AutomationElement enfants qui se trouvent dans le cache.A collection of child AutomationElement objects that are in the cache.
CachedParent Objet parent AutomationElement qui se trouve dans le cache.An AutomationElement parent object that is in the cache.
FocusedElement (Propriété statique) AutomationElement ayant le focus d’entrée.(Static property) The AutomationElement that has the input focus.
RootElement (Propriété statique) AutomationElementracine.(Static property) The root AutomationElement.

Voir aussiSee also