Padrões de controle Text e TextRange

Descreve diretrizes e convenções para implementar ITextProvider, ITextProvider2e ITextRangeProvider, incluindo informações sobre propriedades e métodos. O padrão de controle de de texto permite que aplicativos e controles exponham um modelo de objeto de texto simples, permitindo que os clientes recuperem conteúdo textual, atributos de texto e objetos incorporados de controles baseados em texto.

Para suportar o padrão de controle de de texto, os controles implementam o ITextProvider e interfaces de ITextProvider2. Os tipos de controle que devem suportar o padrão de controle Text incluem os tipos de controle Edit e Document e qualquer outro tipo de controle que permita ao usuário inserir texto ou selecionar texto somente leitura.

O padrão de controle Text pode ser usado com outros padrões de controle da Microsoft UI Automation para oferecer suporte a vários tipos de objetos incorporados no texto, incluindo tabelas, hiperlinks e botões de comando.

As interfaces ITextProvider e ITextProvider2 incluem vários métodos para adquirir intervalos de texto. Um intervalo de texto é um objeto que representa uma extensão contígua de texto — ou várias extensões separadas de texto — em um contêiner de texto. Um método ITextProvider adquire um intervalo de texto que representa o documento inteiro, enquanto outros adquirem intervalos de texto que representam alguma parte do documento, como o texto selecionado, o texto visível ou um objeto incorporado no texto.

Um objeto de intervalo de texto é representado pelo padrão de controle TextRange, que é implementado por meio da interfaceITextRangeProvider. O padrão de controle TextRange fornece métodos e propriedades usados para expor informações sobre o texto no intervalo, mover os pontos finais do intervalo, selecionar ou desmarcar texto, rolar o intervalo para exibição e assim por diante.

Para obter mais informações sobre os padrões de controle Text e TextRange, consulte UI Automation Support for Textual Content.

A partir do Windows 8.1, os provedores podem implementar a interfaceITextRangeProvider2 do. Isso permite invocar menus de contexto associados a um intervalo de texto. Isso suporta cenários como correção automática de texto ou seleção de candidatos do IME (Editor de Método de Entrada).

Este tópico contém as seguintes seções.

• Diretrizes de Implementação e Convenções
• Membros necessários para ITextProvider
• Membros necessários para ITextRangeProvider
• Intervalos de texto de suporte
  • Manipulando um intervalo de texto por unidade de texto
  • Selecionando texto em um intervalo de texto
  • Adquirindo texto de um intervalo de texto
  • Implementando o ShowContextMenu
• Interoperabilidade com o Sistema Caret
• Tópicos relacionados

Orientações e convenções de aplicação

Ao implementar o padrão de controle texto, observe as seguintes diretrizes e convenções:

• Qualquer controle que permita o acesso ao texto (por exemplo, inserir texto ou selecionar texto somente leitura) deve suportar o padrão de controle texto.
• O padrão de controle de de texto pode ser usado com qualquer elemento da interface do usuário que apresente texto, até mesmo um rótulo estático em um controle de botão padrão. No entanto, não é necessário em controles de texto estático que não podem ser selecionados ou não têm um ponto de inserção.
• Para garantir que o texto seja totalmente acessível, os controles que implementam ITextProvider também devem suportar a interfaceIValueProvider. IValueProvider complementa ITextProvider fornecendo uma maneira programática de alterar o texto. Ele também oferece maior compatibilidade com aplicativos cliente de tecnologia assistiva, incluindo aqueles baseados em tecnologias legadas, como o Microsoft Ative Accessibility. Quando ambos os padrões de controle são implementados, o evento TextChanged (UIA_Text_TextChangedEventId) e evento AutomationPropertyChanged (UIA_AutomationPropertyChangedEventId) são equivalentes para a propriedade Value (UIA_ValueValuePropertyId). Ambos os eventos devem ser apoiados.
• O padrão de controle Text suporta apenas um fluxo de texto e uma janela de visualização por controle. Se o aplicativo oferecer várias exibições do documento em painéis, cada exibição (controle) deverá oferecer suporte a ITextProvider independentemente.
• O método ITextProvider::GetSelection pode retornar um único intervalo de texto que representa o texto selecionado no momento. Se um controle oferecer suporte à seleção de várias extensões de texto não contíguas, o método GetSelection deverá retornar uma matriz que contenha uma interface de ITextRangeProvider para cada extensão de texto selecionada.
• O padrão de controle Text representa o ponto de inserção como um intervalo de texto degenerado (vazio). O método ITextProvider::GetSelection deve retornar um intervalo de texto degenerado quando o ponto de inserção existe e nenhum texto é selecionado. Para obter mais informações, consulte Interoperabilidade com o System Caret.
• O métodoITextProvider::GetVisibleRanges pode retornar um único intervalo de texto se um intervalo contíguo de texto estiver visível no visor ou pode retornar uma matriz de intervalos de texto separados representando várias linhas de texto parcialmente visíveis.
• O método ITextProvider::RangeFromChild deve retornar um intervalo degenerado se o elemento filho não contiver texto. Como um objeto incorporado pode incluir texto, o método RangeFromChild nem sempre retorna um intervalo de texto degenerado. Para obter mais informações, consulte Como a automação da interface do usuário expõe objetos incorporados.
• O método ITextProvider::RangeFromPoint executa testes de acerto na área do documento usando as coordenadas de tela especificadas. O intervalo de texto resultante deve ser consistente com o ponto de inserção ou seleção que resultaria de clicar no local nas coordenadas de tela especificadas. Por exemplo, se uma imagem reside nas coordenadas de tela especificadas, o intervalo de texto resultante deve ser o mesmo que o intervalo de texto que o método ITextProvider::RangeFromChild adquiriria para a imagem. Da mesma forma, se um aplicativo cliente solicitar um intervalo de texto para o local no centro do cursor do sistema (o ponto de inserção), o intervalo de texto resultante deverá ser o mesmo que o local do cursor do sistema.
• O propriedade ITextProvider::D ocumentRange deve sempre fornecer um intervalo de texto que inclua todo o texto suportado pela implementação deITextProvidercorrespondente.
• O evento UIA_Text_TextChangedEventId deve ser gerado após qualquer alteração de texto, mesmo que a alteração não esteja visível no visor. Por exemplo, o provedor deve gerar o evento mesmo se o usuário colar exatamente o mesmo texto sobre o texto selecionado.
• A UIA_Text_TextSelectionChangedEventId deve ser levantada sempre que a seleção do texto for alterada ou sempre que o ponto de inserção (acento circunflexo) se mover entre o texto.

Ao implementar o padrão de controle TextRange, observe as seguintes diretrizes e convenções:

• Todos os métodos do padrão de controle TextRange devem executar operações de texto, independentemente do estado de visibilidade do texto. A visibilidade de um intervalo de texto sempre pode ser determinada consultando o atributo IsHidden text (UIA_IsHiddenAttributeId).
• Se possível, um provedor deve garantir que quaisquer alterações de texto, como exclusões, inserções e movimentos, sejam refletidas nos objetos de intervalo de texto associados (instâncias de interface ITextRangeProvider) e gerem um evento UIA_Text_TextChangedEventId. Os clientes podem usar o evento como uma dica para confirmar as alterações editoriais feitas no texto de um controle.
• Todos os objetos de intervalo de texto usados pelos ITextRangeProvider::Compare, CompareEndpointse métodos de MoveEndpointByRange devem ser pares da mesma implementação de padrão de controle texto.
• Embora não seja necessário, o valor pRetVal recuperado pelo método ITextRangeProvider::CompareEndpoints pode indicar a distância, em caracteres (TextUnit_Character), entre os dois pontos de extremidade. No entanto, os aplicativos cliente não devem depender da precisão de pRetVal além de seu valor positivo ou negativo.
• Os ITextRangeProvider::ExpandToEnclosingUnit, Movee métodos de MoveEndpointByUnit exigem uma consideração cuidadosa da unidade de texto especificada. Para obter mais informações, consulte Manipulando um TextRange por unidade de texto.
• Para requisitos de implementação relacionados ao ITextRangeProvider::Select, AddToSelectione métodos RemoveFromSelection, consulte Selecionando texto em um intervalo de texto.
• Os métodos ITextRangeProvider::FindText e FindAttribute pesquisa para frente ou para trás para uma única cadeia de caracteres de texto ou atributo de texto correspondente. Eles devem retornar NULL se nenhuma correspondência for encontrada.
• O métodoITextRangeProvider::GetAttributeValue deve retornar o endereço adquirido do UiaGetReservedMixedAttributeValue ou função UiaGetReservedNotSupportedValue se o atributo associado variar no intervalo ou se o atributo não for suportado pelo controle de texto. A especificação de padrão de controle TextRange não permite adicionar novos identificadores de atributo de texto ou alterar como os atributos existentes são definidos.
• Se possível, o métodoITextRangeProvider::GetBoundingRectangles deve retornar uma matriz que contenha um retângulo delimitador para cada linha de texto total ou parcialmente visível em um intervalo de texto. Se isso não for possível, o provedor pode retornar uma matriz que contém os retângulos delimitadores de apenas linhas totalmente visíveis; No entanto, isso limita a capacidade de um aplicativo cliente de descrever com precisão como o texto está sendo apresentado na tela.
• O métodoITextRangeProvider::GetChildren deve retornar todos os elementos filho incorporados em um intervalo de texto, mas não precisa retornar nenhum filho dos elementos filho. Por exemplo, se um intervalo de texto contiver uma tabela com várias células filhas, o método GetChildren poderá retornar apenas o elemento table e não os elementos cell. Por motivos de desempenho ou arquitetura, um provedor pode não ser capaz de expor todos os objetos incorporados hospedados em um documento na árvore de automação. Nesse caso, o provedor deve pelo menos dar suporte à enumeração de objetos filho por meio do método GetChildren e, como opção, dar suporte ao padrão de controle VirtualizedItem para suporte à desvirtualização.
• O método ITextRangeProvider::GetEnclosingElement normalmente retorna o provedor de texto que fornece o intervalo de texto. No entanto, se o provedor de texto oferecer suporte a objetos filho, como tabelas ou hiperlinks, o elemento de inclusão poderá ser um descendente do provedor de texto. O elemento retornado por GetEnclosingElement deve ser o elemento mais próximo do intervalo de texto fornecido. Por exemplo, se o intervalo de texto estiver em uma célula de uma tabela, GetEnclosingElement deverá retornar a célula que contém em vez do elemento da tabela.
• O método ITextRangeProvider::GetText deve retornar o texto sem formatação no intervalo. Para obter mais informações, consulte Adquirindo texto de um intervalo de texto.
• Chamando ITextRangeProvider::ScrollIntoView deve alinhar o texto no visor do controle de texto conforme especificado pelo parâmetro alignToTop. Embora não haja nenhum requisito em termos de alinhamento horizontal, o intervalo de texto deve ser visível tanto horizontal quanto verticalmente. Ao avaliar o parâmetro alignToTop, um provedor deve levar em conta a orientação do controle de texto e a direção do fluxo do texto. Por exemplo, se alignToTop for TRUE para um controle de texto orientado verticalmente contendo texto que flui da direita para a esquerda, o provedor deverá alinhar o intervalo de texto com o lado direito do visor.
• Ao percorrer um documento por TextUnit_Line, se o intervalo de texto entrar numa tabela incorporada, cada linha de texto numa célula deve ser tratada como uma linha.

Membros necessários para ITextProvider

As propriedades e métodos a seguir são necessários para implementar o ITextProvider interface.

As seguintes propriedades e métodos adicionais são necessários para implementar o ITextProvider2 interface.

Membros necessários para ITextRangeProvider

As propriedades e métodos a seguir são necessários para implementar o ITextRangeProvider interface.

As seguintes propriedades e métodos adicionais são necessários para implementar o ITextRangeProvider2 interface.

O padrão de controle TextRange não tem eventos associados.

Intervalos de texto de suporte

Esta seção descreve como um provedor deve implementar vários métodos do ITextRangeProvider e ITextRangeProvider2 interfaces para dar suporte ao padrão de controle TextRange.

Manipulando um intervalo de texto por unidade de texto

O ITextRangeProvider interface fornece vários métodos para manipular e navegar em intervalos de texto em um controle baseado em texto. Os métodos ITextRangeProvider::Move, MoveEndpointByUnite ExpandToEnclosingUnit movem um intervalo de texto ou um de seus pontos de extremidade pela unidade de texto especificada, como caractere, palavra, parágrafo e assim por diante. Para obter mais informações, consulte unidades de texto de automação da interface do usuário.

Apesar de seu nome, o ITextRangeProvider::ExpandToEnclosingUnit método não necessariamente expande um intervalo de texto. Em vez disso, ele "normaliza" um intervalo de texto movendo os pontos de extremidade para que o intervalo abranja a unidade de texto especificada. O intervalo é expandido se for menor do que a unidade especificada ou encurtado se for maior do que a unidade especificada. É fundamental que o método ExpandToEnclosingUnit sempre normalize intervalos de texto de maneira consistente; caso contrário, outros aspetos da manipulação do intervalo de texto por unidade de texto seriam imprevisíveis. O diagrama a seguir mostra como ExpandToEnclosingUnit normaliza um intervalo de texto movendo os pontos finais do intervalo.

Se o intervalo de texto começar no início de uma unidade de texto e terminar no início ou antes do próximo limite da unidade de texto, o ponto de extremidade final será movido para o próximo limite da unidade de texto (veja 1 e 2 no diagrama anterior).

Se o intervalo de texto começar no início de uma unidade de texto e terminar em, ou depois, o próximo limite de unidade, o ponto de extremidade final permanecerá ou será movido para trás para o próximo limite de unidade após o ponto de extremidade inicial (veja 3 e 4 na ilustração anterior). Se houver mais de um limite de unidade de texto entre os pontos de extremidade inicial e final, o ponto de extremidade final será movido para trás para o próximo limite de unidade após o ponto de extremidade inicial, resultando em um intervalo de texto que é uma unidade de texto em comprimento.

Se o intervalo de texto começar no meio da unidade de texto, o ponto de extremidade inicial será movido para trás para o início da unidade de texto e o ponto de extremidade final será movido para frente ou para trás, conforme necessário, para o próximo limite da unidade após o ponto de extremidade inicial (consulte 5 a 8 no diagrama anterior).

Quando o método ITextRangeProvider::Move é chamado, o provedor normaliza o intervalo de texto pela unidade de texto especificada, usando a mesma lógica de normalização do métodoExpandToEnclosingUnit. Em seguida, o provedor move o intervalo para trás ou para frente pelo número especificado de unidades de texto. Ao mover o intervalo, o provedor deve ignorar os limites de quaisquer objetos incorporados no texto. (No entanto, o próprio limite da unidade pode ser afetado pela existência de um objeto incorporado). O diagrama a seguir demonstra como o método Move move um intervalo de texto, unidade por unidade, entre objetos incorporados e limites de unidade de texto.

O método ITextRangeProvider::MoveEndpointByUnit move um dos pontos de extremidade para frente ou para trás por unidade de texto especificada, como mostra a ilustração a seguir.

O métodoITextRangeProvider::MoveEndpointByRange permite que um aplicativo cliente defina um ponto de extremidade de um intervalo de texto para o mesmo local que o ponto de extremidade especificado de um segundo intervalo de texto.

Selecionando texto em um intervalo de texto

O ITextRangeProvider interface inclui vários métodos para controlar a seleção de texto em um controle baseado em texto.

O método ITextRangeProvider::Select deve selecionar o texto que corresponde a um intervalo de texto e remover a seleção anterior, se houver, do controle de texto. Se Selecionar for chamado em um intervalo de texto degenerado, o provedor deverá mover o ponto de inserção para o local do intervalo de texto sem selecionar nenhum texto.

Se um controle oferecer suporte à seleção de várias extensões separadas de texto, os métodos ITextRangeProvider::AddToSelection e RemoveFromSelection adicionam intervalos de texto e os removem da coleção de intervalos de texto selecionados. Se o controle oferecer suporte apenas a um intervalo de texto selecionado de cada vez, mas a operação de seleção resultar na seleção de vários intervalos de texto separados, o provedor deverá retornar um erro E_INVALIDOPERATION ou estender ou truncar a seleção atual. A propriedade ITextProvider::SupportedTextSelection deve indicar se um controle suporta a seleção de uma ou várias extensões de texto, ou nenhuma.

Se um controle baseado em texto oferece suporte a inserções de texto, chamar ITextRangeProvider::AddToSelection ou RemoveFromSelection em um intervalo de texto degenerado no controle deve mover o ponto de inserção, mas não deve selecionar nenhum texto.

Adquirindo texto de um intervalo de texto

O método ITextRangeProvider::GetText deve retornar o texto sem formatação de um intervalo de texto. O texto sem formatação deve incluir todos os caracteres de controle encontrados no texto de origem, como retornos de carro e a marca Unicode da esquerda para a direita (LRM). O texto simples não deve incluir marcas de marcação, como HTML, que possam estar presentes no texto de origem. Além disso, quaisquer códigos de escape no texto de partida devem ser convertidos para os equivalentes de texto simples. Por exemplo, " " deve ser convertido em um caractere de espaço simples.

Se um objeto incorporado abrange um intervalo de texto, o texto sem formatação deve incluir o texto interno do objeto, mas não o texto alternativo (a propriedade name do objeto incorporado) porque pode ser inconsistente com o texto interno descritivo. Para obter mais informações, consulte Como a automação da interface do usuário expõe objetos incorporados.

Implementando ShowContextMenu

ITextRangeProvider2::ShowContextMenu sempre deve mostrar o menu de contexto no ponto final inicial do intervalo. Isso deve ser equivalente ao que aconteceria se o usuário pressionasse a tecla do menu de contexto ou SHIFT + F10 com o ponto de inserção no início do intervalo.

Se a exibição do menu de contexto normalmente resultar na movimentação do ponto de inserção para um determinado local, ele deverá fazê-lo para invocar programaticamente ShowContextMenu para suporte à Automação da Interface do Usuário também.

Interoperabilidade com o System Caret

O suporte correto ao ponto de inserção é fundamental para muitos aplicativos cliente, incluindo aqueles que não se baseiam na automação da interface do usuário. No padrão de controle de de texto, o ponto de inserção é representado por um intervalo de texto degenerado (vazio) na posição do cursor do sistema. Quando o ponto de inserção se move, um controle deve gerar o TextSelectionChanged evento (UIA_Text_TextSelectionChangedEventId). Alguns aplicativos cliente dependem desse evento para monitorar o local do ponto de inserção e acompanhar a seleção de texto.

Quando um controle contém texto selecionado, o design atual do padrão de controle Text não fornece uma maneira de associar diretamente o local do ponto de inserção a um intervalo de texto específico. O provedor deve acompanhar a seleção de texto e definir a localização do ponto de inserção adequadamente. Como a seleção de texto geralmente é feita movendo o ponto de inserção enquanto mantém pressionada a tecla SHIFT ou CTRL, ou ambas, um provedor pode acompanhar a seleção de texto verificando o estado dessas teclas sempre que a seleção for alterada.

Como a estrutura de acessibilidade fornece suporte interno para o cursor do sistema, mas não para um cursor personalizado, os controles baseados em texto devem usar o cursor do sistema sempre que possível. Os controles que usam um cursor personalizado podem garantir que o cursor seja acessível criando um cursor do sistema que tenha as mesmas dimensões do cursor personalizado e posicionando o cursor do sistema no mesmo local na interface do usuário do controle que o cursor personalizado, ou seja, no ponto de inserção. Como alternativa, um controle que usa um cursor personalizado pode implementar um provedor Microsoft Ative Accessibility para OBJID_CARET fornecer informações de acessibilidade diretamente para seu cursor personalizado.

Para obter mais informações sobre o cursor do sistema, consulte Carets.

Para testar se o controle expõe corretamente o local do cursor do sistema, use as ferramentas Inspecionar e Observador de Eventos Acessível.

As coordenadas de tela do centro do bitmap de acento circunflexo do sistema devem sempre corresponder ao local do ponto de inserção. Dessa forma, um cliente pode usar as coordenadas da tela de cursor em uma chamada para ITextProvider::RangeFromPoint para recuperar um intervalo de texto que representa com precisão o local do ponto de inserção.

Tópicos relacionados

tipos de controle e seus padrões de controle suportados

Tipo de controle de texto

padrão de controle do Editor de Texto

padrão de controle TextChild

Visão geral dos padrões de controle de automação da interface do do usuário

Suporte de automação de interface do usuário para conteúdo textual

Visão geral da árvore de automação da interface do usuário