IUIAutomation6 ::AddActiveTextPositionChangedEventHandler, méthode (uiautomationclient.h)

Article
08/08/2024

Inscrit une méthode qui gère lorsque la position de texte active change.

Important

Les clients Microsoft UI Automation doivent utiliser l’interface IUIAutomationEventHandlerGroup méthodes pour inscrire des écouteurs d’événements au lieu de méthodes d’inscription d’événements individuelles définies ici et dans les différentes interface IUIAutomation espaces de noms.

Syntaxe

HRESULT AddActiveTextPositionChangedEventHandler(
  [in] IUIAutomationElement                               *element,
  [in] TreeScope                                          scope,
  [in] IUIAutomationCacheRequest                          *cacheRequest,
  [in] IUIAutomationActiveTextPositionChangedEventHandler *handler
);

Paramètres

[in] element

Pointeur vers l’élément UI Automation associé au gestionnaire d’événements.

[in] scope

Étendue des événements à gérer ; c’est-à-dire, qu’ils soient sur l’élément lui-même, ou sur ses ancêtres et descendants.

[in] cacheRequest

Pointeur vers une demande de cache ou NULL si aucune mise en cache n’est souhaitée.

[in] handler

Pointeur vers l’objet qui gère l’événement de modification de la position de texte active.

Valeur de retour

Si cette méthode réussit, elle retourne S_OK. Sinon, elle retourne un code d’erreur HRESULT.

Remarques

Avant d’implémenter un gestionnaire d’événements, vous devez connaître les problèmes de thread décrits dans Understanding Threading Issues.

La position de texte active est indiquée par un événement de navigation au sein ou entre des éléments de texte en lecture seule (tels que les navigateurs web, les documents PDF (Portable Document Format) ou EPUB documents) à l’aide de signets (ou d’identificateurs de fragments pour faire référence à un emplacement au sein d’une ressource). Voici quelques exemples :

Navigation vers un signet dans la même page web
Navigation vers un signet sur une autre page web
Activation d’un lien vers un autre emplacement au sein du même PDF
Activation d’un lien vers un autre emplacement dans le même EPUB

Utilisez ce gestionnaire d’événements pour synchroniser l’emplacement visuel du signet/cible avec l’emplacement de focus dans un élément de texte en lecture seule, ce qui peut différer lors de l’utilisation de signets ou d’identificateurs de fragments.

Par exemple, lorsqu’une même ancre de page (<a href="#C4">Jump to Chapter 4</a> ...<h1><a name="C4">Chapter 4</a></h1>) est appelée, l’emplacement visuel est mis à jour, mais le client UI Automation reste à l’emplacement d’origine. Cela entraîne des actions telles que la lecture de texte ou le déplacement des commandes d’élément suivant à partir de l’emplacement d’origine, et non du nouvel emplacement.

De même, l’activation d’un nouvel URI de page (avec un identificateur de fragment : (<a href="www.blah.com#C4">Jump to Chapter 4</a>) charge la nouvelle page et passe au signet spécifié, mais laisse les clients UI Automation en haut de la page.

Pour les éléments de texte modifiables, tels que Modifier et contrôles Rich Edit, vous pouvez écouter un événement SelectionChanged.

Il est possible qu’un événement soit remis à un gestionnaire d’événements une fois que le gestionnaire a été annulé, si l’événement est reçu simultanément avec la demande de désinscription de l’événement. La meilleure pratique consiste à suivre la norme COM (Component Object Model) et à éviter de détruire l’objet du gestionnaire d’événements jusqu’à ce que son nombre de références ait atteint zéro. La destruction d’un gestionnaire d’événements immédiatement après la désinscrire des événements peut entraîner une violation d’accès si un événement est remis en retard.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 10, version 1809 [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server, version 1709 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	uiautomationclient.h (include UIAutomation.h)

Voir aussi

IUIAutomation6 ::RemoveActiveTextPositionChangedEventHandler, interface IUIAutomation6

Partager via