Metodo IUIAutomation6::AddActiveTextPositionChangedEventHandler (uiautomationclient.h)

Articolo
08/08/2024

Registra un metodo che gestisce quando cambia la posizione del testo attiva.

Importante

I client di automazione interfaccia utente Microsoft devono usare l'interfaccia interfaccia IUIAutomationEventHandlerGroup per registrare i listener di eventi anziché i singoli metodi di registrazione eventi definiti qui e nelle varie interfacce IUIAutomation spazi dei nomi.

Sintassi

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

Parametri

[in] element

Puntatore all'elemento di automazione interfaccia utente associato al gestore eventi.

[in] scope

Ambito degli eventi da gestire; ovvero se si trovano sull'elemento stesso, o sui suoi predecessori e discendenti.

[in] cacheRequest

Puntatore a una richiesta di cache o NULL se non si desidera memorizzare nella cache.

[in] handler

Puntatore all'oggetto che gestisce l'evento di modifica della posizione del testo attiva.

Valore restituito

Se questo metodo ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT.

Osservazioni

Prima di implementare un gestore eventi, è necessario avere familiarità con i problemi di threading descritti in Informazioni sui problemi di threading.

La posizione di testo attiva è indicata da un evento di navigazione all'interno o tra elementi di testo di sola lettura (ad esempio web browser, documenti PDF (Portable Document Format) o documenti EPUB) utilizzando segnalibri (o identificatori di frammento) per fare riferimento a una posizione all'interno di una risorsa. Gli esempi includono:

Passaggio a un segnalibro all'interno della stessa pagina Web
Passaggio a un segnalibro in una pagina Web diversa
Attivazione di un collegamento a una posizione diversa all'interno dello stesso PDF
Attivazione di un collegamento a un percorso diverso all'interno dello stesso EPUB

Utilizzare questo gestore eventi per sincronizzare la posizione visiva del segnalibro o della destinazione con la posizione dello stato attivo in un elemento di testo di sola lettura, che può divergere quando si usano segnalibri o identificatori di frammento.

Ad esempio, quando viene richiamato lo stesso ancoraggio di pagina (<a href="#C4">Jump to Chapter 4</a> ...<h1><a name="C4">Chapter 4</a></h1>), il percorso visivo viene aggiornato, ma il client di automazione interfaccia utente rimane nella posizione originale. Ciò comporta azioni come la lettura del testo o lo spostamento dei comandi dell'elemento successivo a partire dalla posizione originale, non dalla nuova posizione.

Analogamente, l'attivazione di un nuovo URI di pagina (con un identificatore di frammento: (<a href="www.blah.com#C4">Jump to Chapter 4</a>) carica la nuova pagina e passa al segnalibro specificato, ma lascia i client di automazione interfaccia utente nella parte superiore della pagina.

Per gli elementi di testo modificabili, ad esempio Modifica e controlli Rich Edit, è possibile restare in ascolto di un evento SelectionChanged.

È possibile che un evento venga recapitato a un gestore eventi dopo che il gestore è stato annullato, se l'evento viene ricevuto contemporaneamente con la richiesta di annullare la sottoscrizione dell'evento. La procedura consigliata consiste nel seguire lo standard COM (Component Object Model) ed evitare di eliminare definitivamente l'oggetto gestore eventi fino al raggiungimento del numero di riferimenti pari a zero. L'eliminazione di un gestore eventi immediatamente dopo l'annullamento della sottoscrizione per gli eventi può comportare una violazione di accesso se un evento viene recapitato in ritardo.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 10, versione 1809 [solo app desktop]
server minimo supportato	Windows Server, versione 1709 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	uiautomationclient.h (include UIAutomation.h)

Vedere anche

interfaccia IUIAutomation6::RemoveActiveTextPositionChangedEventHandler, interfaccia IUIAutomation6

Condividi tramite