Obtention d'éléments UI Automation

Cette rubrique décrit différentes façons d’obtenir des interfaces IUIAutomationElement pour les éléments d’interface utilisateur.

IUIAutomationElement est utilisé dans l’exemple d’application client de contenu du document UI Automation.

Élément racine

Bien que les éléments puissent être récupérés directement à l’aide de méthodes, telles que IUIAutomation::GetFocusedElement, certaines applications clientes nécessitent une vue de la structure hiérarchique des éléments, appelée arborescence UI Automation. L’élément racine de cette hiérarchie est le bureau. Vous pouvez obtenir cet élément avec la méthode IUIAutomation::GetRootElementou de la méthode IUIAutomation::GetRootElementBuildCache. Ces deux méthodes récupèrent un pointeur d’interface IUIAutomationElement . Vous pouvez rechercher des éléments descendants à l’aide de méthodes, telles que IUIAutomationElement::FindFirst et FindAll.

Remarque

En général, vous devez essayer d’obtenir uniquement les enfants directs de l’élément racine. Une recherche de descendants peut itérer à travers des centaines ou des milliers d’éléments. Si vous tentez d’obtenir un élément spécifique de niveau inférieur, vous devez commencer votre recherche à partir de la fenêtre d’application ou d’un conteneur de niveau inférieur.

 

Conditions

Pour la plupart des techniques que vous utilisez pour récupérer des éléments UI Automation, vous devez spécifier une condition. Une condition est un ensemble de critères qui définit les éléments que vous souhaitez récupérer. Une condition est représentée par l’interface IUIAutomationCondition.

La condition la plus simple est la condition true, qui est un objet prédéfini spécifiant que tous les éléments de l’étendue de recherche doivent être retournés. La condition false est l’inverse de la condition true et est moins utile, car elle empêcherait la découverte d’éléments. Vous pouvez obtenir une interface vers la condition true avec IUIAutomation::CreateTrueCondition.

Trois autres conditions prédéfinies, disponibles en tant que propriétés sur l’objet IUIAutomation peuvent être utilisées seul ou en combinaison avec d’autres conditions :IUIAutomation::ContentViewCondition, ControlViewCondition, etRawViewCondition. RawViewCondition, utilisée seule, est équivalente à la condition true, car il ne filtre pas les éléments par les propriétés IUIAutomationElement::CurrentIsControlElement ou CurrentIsContentElement.

D’autres conditions sont générées à partir d’objets de condition, chacun d’entre eux spécifiant une valeur de propriété. Par exemple, une condition de propriété peut spécifier que l’élément est activé ou qu’il prend en charge un certain modèle de contrôle.

Les conditions qui utilisent la logique booléenne peuvent être combinées en appelant IUIAutomation::CreateAndCondition, CreateOrCondition, CreateNotCondition, ainsi que les méthodes associées.

Étendue de recherche

Les recherches effectuées avec IUIAutomationElement::FindFirst ou FindAlldoivent avoir une étendue et un emplacement de départ.

Remarque

Tout commentaire sur ces deux méthodes s’applique également à IUIAutomationElement::FindFirstBuildCache et FindAllBuildCache.

 

L’étendue définit l’espace autour de l’emplacement de départ à rechercher. Cela peut comprendre l’élément lui-même, ses frères, son parent, ses enfants immédiats et ses descendants. N’oubliez pas que les méthodes Find ne prennent pas en charge la recherche dans l’arborescence Microsoft UI Automation ; autrement dit, la recherche d’éléments ancêtres n’est pas prise en charge.

L’étendue d’une recherche est définie par une combinaison bit à bit de valeurs du type énuméré TreeScope.

Recherche d’un élément connu

Pour rechercher un élément connu identifié par un nom, un ID d’automatisation ou une autre propriété ou combinaison de propriétés, il est plus simple d’utiliser la méthode IUIAutomationElement::FindFirst. Si l’élément recherché est une fenêtre d’application, le point de départ de la recherche peut être l’élément racine.

Cette façon de rechercher des éléments UI Automation est très utile dans les scénarios de test automatisé.

Pour obtenir un exemple de code qui montre comment rechercher un élément connu, consultez Recherche d’un élément par nom.

Recherche d’éléments dans une sous-arborescence

Pour rechercher tous les éléments qui répondent à des critères spécifiques et qui sont liés à un élément connu, vous pouvez appeler IUIAutomationElement::FindAll sur l’élément connu. Par exemple, utilisez cette méthode pour récupérer des éléments de liste ou des éléments de menu à partir d’une liste ou d’un menu, ou pour identifier tous les contrôles d’une boîte de dialogue.

Pour obtenir un exemple de code qui montre comment rechercher des éléments dans une sous-arborescence, consultez Recherche d’éléments connexes.

Parcourir une sous-arborescence

Si vous n’avez aucune connaissance préalable des applications avec lesquelles votre client peut être utilisé, vous pouvez construire une sous-arborescence de tous les éléments intéressants avec IUIAutomationTreeWalker. Votre client peut le faire, par exemple, en réponse à un événement modifié par focus ; autrement dit, lorsqu’une application ou un contrôle reçoit le focus d’entrée, le client UI Automation examine les enfants et possiblement tous les descendants de l’élément ciblé.

N’oubliez pas que le fonctionnement de l’arborescence UI Automation est gourmande en ressources. Parcourez l’arborescence uniquement lorsqu’il n’est pas possible d’utiliser les méthodes IUIAutomationElement::FindFirst, FindAll ou BuildUpdatedCache.

Vous pouvez définir votre propre marcheur d’arbre en passant une condition personnalisée à IUIAutomation::CreateTreeWalker, ou vous pouvez utiliser l’un des objets prédéfinis suivants définis comme propriétés de l’IUIAutomation de base.

Objet	Objectif
ContentViewWalker	Recherche uniquement les éléments dont la propriété IUIAutomationElement::CurrentIsContentElement a la valeur TRUE.
ControlViewWalker	Recherche uniquement les éléments dont la propriété IUIAutomationElement::CurrentIsControlElement a la valeur TRUE.
RawViewWalker	Recherche tous les éléments.

 

Après avoir obtenu un IUIAutomationTreeWalker, appelez les méthodes IUIAutomationTreeWalker::GetXxx pour parcourir les éléments de la sous-arborescence, en passant l’élément à partir duquel commencer son fonctionnement.

La méthode IUIAutomationTreeWalker::Normalize peut être utilisée pour accéder à un élément de la sous-arborescence à partir d’un autre élément qui ne fait pas partie de la vue. Par exemple, supposons que vous créez une vue d’une sous-arborescence avec IUIAutomation::ContentViewWalker. Votre application reçoit une notification indiquant qu’une barre de défilement a reçu le focus d’entrée. Comme une barre de défilement n’est pas un élément de contenu, elle n’est pas présente dans l’affichage de la sous-arborescence. Toutefois, vous pouvez passer l’IUIAutomationElement qui représente la barre de défilement vers IUIAutomationTreeWalker::Normalize et récupérer l’ancêtre le plus proche qui se trouve dans la vue de contenu.

Pour obtenir des exemples de code qui montrent comment utiliser l’interface IUIAutomationTreeWalker, consultez Comment suivre l’arborescence UI Automation.

Autres moyens de récupérer un élément

Outre les recherches et la navigation, vous pouvez récupérer une IUIAutomationElement de la manière suivante.

À partir d’un événement

Lorsque votre application reçoit un événement UI Automation, l’objet source transmis à votre gestionnaire d’événements est représenté par une IUIAutomationElement. Par exemple, si vous vous abonnez à des événements modifiés par le focus, la source transmise à votre IUIAutomationFocusChangedEventHandler est l’élément qui a reçu le focus. Pour plus d’informations, consultez Abonnement aux événements UI Automation.

À partir d’un point

Pour récupérer une IUIAutomationElement à partir des coordonnées de l’écran, par exemple, de la position du curseur, utilisez la méthode IUIAutomation::ElementFromPoint.

À partir d’un handle de fenêtre

Pour récupérer une IUIAutomationElement à partir d’une HWND , utilisez la méthode IUIAutomation::ElementFromHandle.

À partir du contrôle ayant le focus

Pour récupérer une IUIAutomationElement qui représente le contrôle prioritaire, utilisez la méthode IUIAutomation::GetFocusedElement.

Rubriques connexes

Vue d’ensemble de l’arborescence UI Automation

Exemple d’application client de contenu du document UI Automation