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

Registra um método que manipula quando a posição de texto ativo é alterada.

Importante

Os clientes do Microsoft Automação da Interface do Usuário devem usar os métodos de interface IUIAutomationEventHandlerGroup para registrar ouvintes de eventos em vez de métodos individuais de registro de eventos definidos aqui e nos vários namespaces da interface IUIAutomation.

Sintaxe

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

Parâmetros

[in] element

Um ponteiro para o elemento Automação da Interface do Usuário associado ao manipulador de eventos.

scope

[in] cacheRequest

Um ponteiro para uma solicitação de cache ou NULL se nenhum cache for desejado.

[in] handler

Um ponteiro para o objeto que manipula o evento alterado de posição de texto ativo.

Retornar valor

Se o método for bem-sucedido, ele retornará S_OK. Caso contrário, ela retornará um código de erro HRESULT.

Comentários

Antes de implementar um manipulador de eventos, você deve estar familiarizado com os problemas de threading descritos em Noções básicas sobre problemas de threading.

A posição de texto ativo é indicada por um evento de navegação dentro ou entre elementos de texto somente leitura (como navegadores da Web, documentos PDF (Portable Document Format) ou documentos EPUB ) usando indicadores (ou identificadores de fragmento para se referir a um local dentro de um recurso). Os exemplos incluem:

• Navegando até um indicador na mesma página da Web
• Navegando até um indicador em uma página da Web diferente
• Ativando um link para um local diferente no mesmo PDF
• Ativando um link para um local diferente dentro do mesmo EPUB

Use esse manipulador de eventos para sincronizar o local visual do indicador/destino com o local de foco em um elemento de texto somente leitura, que pode divergir ao usar indicadores ou identificadores de fragmento.

Por exemplo, quando uma mesma âncora de página (<a href="#C4">Jump to Chapter 4</a> ...<h1><a name="C4">Chapter 4</a></h1>) é invocada, o local visual é atualizado, mas o cliente Automação da Interface do Usuário permanece no local original. Isso resulta em ações como leitura de texto ou movimentação dos próximos comandos de item a partir do local original, não no novo local.

Da mesma forma, ativar um novo URI de página (com um identificador de fragmento: (<a href="www.blah.com#C4">Jump to Chapter 4</a>) carrega a nova página e salta para o indicador especificado, mas deixa os clientes Automação da Interface do Usuário na parte superior da página.

Para elementos de texto editáveis, como os controles Editar e Edição Avançada, você pode escutar um evento SelectionChanged.

É possível que um evento seja entregue a um manipulador de eventos após a assinatura do manipulador, se o evento for recebido simultaneamente com a solicitação para cancelar a assinatura do evento. A melhor prática é seguir o padrão COM (Component Object Model) e evitar destruir o objeto do manipulador de eventos até que sua contagem de referência tenha atingido zero. Destruir um manipulador de eventos imediatamente após cancelar a assinatura de eventos poderá resultar em uma violação de acesso se um evento for entregue com atraso.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 10, versão 1809 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server, versão 1709 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	uiautomationclient.h (include UIAutomation.h)

Confira também

IUIAutomation6::RemoveActiveTextPositionChangedEventHandler, interface IUIAutomation6