IUIAutomation6::AddActiveTextPositionChangedEventHandler-Methode (uiautomationclient.h)

Artikel
08/08/2024

Registriert eine Methode, die behandelt wird, wenn sich die aktive Textposition ändert.

Wichtig

Microsoft-Benutzeroberflächenautomatisierungs-Clients sollten die IUIAutomationEventHandlerGroup-Schnittstelle Methoden verwenden, um Ereignislistener anstelle einzelner hier definierter Ereignisregistrierungsmethoden und in den verschiedenen IUIAutomation-Schnittstelle Namespaces zu registrieren.

Syntax

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

Parameter

[in] element

Ein Zeiger auf das Benutzeroberflächenautomatisierungs-Element, das dem Ereignishandler zugeordnet ist.

[in] scope

Der Umfang der zu behandelnden Ereignisse; das heißt, ob sie sich auf dem Element selbst oder auf seinen Vorgängern und Nachfolgern befinden.

[in] cacheRequest

Ein Zeiger auf eine Cacheanforderung oder NULL, wenn keine Zwischenspeicherung gewünscht wird.

[in] handler

Ein Zeiger auf das Objekt, das das geänderte Ereignis der aktiven Textposition behandelt.

Rückgabewert

Wenn diese Methode erfolgreich ist, wird S_OK zurückgegeben. Andernfalls wird ein HRESULT-Fehlercode zurückgegeben.

Bemerkungen

Bevor Sie einen Ereignishandler implementieren, sollten Sie mit den Threadingproblemen vertraut sein, die in Grundlegendes zu Threadingproblemenbeschrieben werden.

Die aktive Textposition wird durch ein Navigationsereignis innerhalb oder zwischen schreibgeschützten Textelementen (z. B. Webbrowsern, PDF-Dokumenten (Portable Document Format) oder EPUB- Dokumenten) mithilfe von Textmarken (oder Fragmentbezeichnern) angegeben, um auf einen Speicherort innerhalb einer Ressource zu verweisen). Beispiele sind:

Navigieren zu einer Textmarke innerhalb derselben Webseite
Navigieren zu einer Textmarke auf einer anderen Webseite
Aktivieren eines Links zu einem anderen Speicherort innerhalb derselben PDF-Datei
Aktivieren eines Links zu einem anderen Speicherort innerhalb desselben EPUB-

Verwenden Sie diesen Ereignishandler, um die visuelle Position des Lesezeichens/Ziels mit der Fokusposition in einem schreibgeschützten Textelement zu synchronisieren, das bei Verwendung von Textmarken oder Fragmentbezeichnern abweichen kann.

Wenn beispielsweise ein Seitenanker (<a href="#C4">Jump to Chapter 4</a> ...<h1><a name="C4">Chapter 4</a></h1>) aufgerufen wird, wird der visuelle Speicherort aktualisiert, der Benutzeroberflächenautomatisierungs-Client verbleibt jedoch an der ursprünglichen Position. Dies führt zu Aktionen wie Textlesevorgang oder Verschieben von Befehlen für das nächste Element ab dem ursprünglichen Speicherort, nicht zum neuen Speicherort.

Ebenso lädt die Aktivierung eines neuen Seiten-URI (mit einem Fragmentbezeichner: (<a href="www.blah.com#C4">Jump to Chapter 4</a>) die neue Seite und springt zu der angegebenen Textmarke, belässt die Benutzeroberflächenautomatisierungs-Clients jedoch oben auf der Seite.

Für bearbeitbare Textelemente, z. B. Bearbeiten und Rich Edit-Steuerelemente, können Sie auf ein SelectionChanged-Ereignis lauschen.

Es ist möglich, dass ein Ereignis an einen Ereignishandler übermittelt wird, nachdem der Handler abbestellt wurde, wenn das Ereignis gleichzeitig mit der Anforderung zum Kündigen des Ereignisses empfangen wird. Die bewährte Methode besteht darin, dem COM-Standard (Component Object Model) zu folgen und zu vermeiden, dass das Ereignishandlerobjekt zerstört wird, bis die Referenzanzahl null erreicht hat. Das Löschen eines Ereignishandlers unmittelbar nach dem Aufheben der Ausschreibung für Ereignisse kann zu einer Zugriffsverletzung führen, wenn ein Ereignis verspätet übermittelt wird.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 10, Version 1809 [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server, Version 1709 [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	uiautomationclient.h (include UIAutomation.h)

Siehe auch

IUIAutomation6::RemoveActiveTextPositionChangedEventHandler, IUIAutomation6-Schnittstelle

Freigeben über