Compartir a través de

Método IUIAutomation6::AddActiveTextPositionChangedEventHandler (uiautomationclient.h)

  • Artículo

Registra un método que controla cuando cambia la posición del texto activo.

Importante

Los clientes de Automatización de la interfaz de usuario de Microsoft deben usar la interfaz IUIAutomationEventHandlerGroup métodos para registrar agentes de escucha de eventos en lugar de métodos de registro de eventos individuales definidos aquí y en las distintas interfaces IUIAutomation espacios de nombres.

Sintaxis

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

Parámetros

[in] element

Puntero al elemento de automatización de la interfaz de usuario asociado al controlador de eventos.

[in] scope

Ámbito de los eventos que se van a controlar; es decir, si están en el propio elemento o en sus antecesores y descendientes.

[in] cacheRequest

Puntero a una solicitud de caché o NULL si no se desea ningún almacenamiento en caché.

[in] handler

Puntero al objeto que controla el evento de cambio de posición de texto activo.

Valor devuelto

Si este método se ejecuta correctamente, devuelve S_OK. De lo contrario, devuelve un código de error HRESULT.

Observaciones

Antes de implementar un controlador de eventos, debe estar familiarizado con los problemas de subproceso descritos en Descripción de los problemas de subprocesos.

La posición del texto activo se indica mediante un evento de navegación dentro o entre elementos de texto de solo lectura (como exploradores web, documentos de formato de documento portátil (PDF) o documentos EPUB) mediante marcadores (o identificadores de fragmentos para hacer referencia a una ubicación dentro de un recurso). Algunos ejemplos son:

  • Navegación a un marcador dentro de la misma página web
  • Navegación a un marcador en una página web diferente
  • Activación de un vínculo a una ubicación diferente dentro del mismo PDF
  • Activación de un vínculo a una ubicación diferente dentro del mismo EPUB

Use este controlador de eventos para sincronizar la ubicación visual del marcador o destino con la ubicación de foco en un elemento de texto de solo lectura, que puede diverge cuando se usan marcadores o identificadores de fragmentos.

Por ejemplo, cuando se invoca un mismo delimitador de página (<a href="#C4">Jump to Chapter 4</a> ...<h1><a name="C4">Chapter 4</a></h1>), se actualiza la ubicación visual, pero el cliente de Automatización de la interfaz de usuario permanece en la ubicación original. Esto da como resultado acciones como la lectura de texto o mover los comandos del elemento siguiente a partir de la ubicación original, no desde la nueva ubicación.

Del mismo modo, la activación de un nuevo URI de página (con un identificador de fragmento: (<a href="www.blah.com#C4">Jump to Chapter 4</a>) carga la nueva página y salta al marcador especificado, pero deja los clientes de automatización de la interfaz de usuario en la parte superior de la página.

Para los elementos de texto editables, como Editar y controles De edición enriquecida, puede escuchar un evento SelectionChanged.

Es posible que un evento se entregue a un controlador de eventos después de cancelar la suscripción del controlador, si el evento se recibe simultáneamente con la solicitud de cancelar la suscripción del evento. El procedimiento recomendado es seguir el estándar modelo de objetos componentes (COM) y evitar destruir el objeto del controlador de eventos hasta que su recuento de referencias haya alcanzado cero. La destrucción de un controlador de eventos inmediatamente después de anular la suscripción de eventos puede provocar una infracción de acceso si se entrega un evento tarde.

Requisitos

Requisito Valor
cliente mínimo admitido Windows 10, versión 1809 [solo aplicaciones de escritorio]
servidor mínimo admitido Windows Server, versión 1709 [solo aplicaciones de escritorio]
de la plataforma de destino de Windows
encabezado de uiautomationclient.h (include UIAutomation.h)

Consulte también

IUIAutomation6::RemoveActiveTextPositionChangedEventHandler, interfaz IUIAutomation6