Usando IUIAutomationTextRange para acessar e manipular um intervalo de texto
Este tópico descreve como usar as propriedades e os métodos da interface IUIAutomationTextRange para acessar e manipular o conteúdo textual de um controle baseado em texto.
O que é um Intervalo de Texto?
O modelo de objeto de texto do Microsoft Automação da Interface do Usuário baseia-se no conceito do intervalo de texto. Um intervalo de texto é um objeto que expõe a interface IUIAutomationTextRange e representa um intervalo contíguo de texto em um controle baseado em texto. Cada intervalo de texto tem um ponto de extremidade inicial e um ponto de extremidade final, e todo o conteúdo textual entre os dois pontos de extremidade é considerado parte do intervalo. Um intervalo de texto cujo ponto de extremidade inicial e ponto de extremidade final estão no mesmo local é chamado de intervalo de texto degenerado (ou vazio). Um intervalo de texto degenerado é usado para marcar um local específico dentro do texto de um controle, como o local do ponto de inserção de texto.
Adquirindo objetos de intervalo de texto
Os aplicativos cliente adquirem objetos de intervalo de texto usando as propriedades e os métodos da interface IUIAutomationTextPattern . A propriedade IUIAutomationTextRangePattern::D ocumentRange recupera um intervalo de texto que representa todo o conteúdo textual de um controle baseado em texto, enquanto outros métodos adquirem intervalos de texto que representam alguma parte do conteúdo, como o texto selecionado, o texto visível ou um objeto inserido no texto.
Os métodos IUIAutomationTextRangePattern::GetVisibleRanges e GetSelection podem recuperar matrizes de objetos de intervalo de texto. Se um controle for parcialmente obscurecido por uma janela sobreposta ou outro objeto, GetVisibleRanges retornará uma matriz que contém um objeto de intervalo de texto para cada linha de texto parcialmente visível. Da mesma forma, se um controle baseado em texto der suporte à seleção de vários intervalos de texto não contíguos, GetSelection retornará uma matriz que contém um objeto de intervalo de texto para cada intervalo selecionado.
O método IUIAutomationTextRangePattern::RangeFromChild permite que um aplicativo cliente recupere um intervalo de texto que inclua um objeto inserido no conteúdo textual. O cliente especifica o ponteiro da interface IUIAutomationElement de um objeto inserido, como uma imagem, uma tabela ou um hiperlink, e o método retorna um intervalo de texto que inclui o objeto . No entanto, se o objeto inserido não tiver texto associado a ele, o método retornará um intervalo de texto degenerado.
Um aplicativo cliente pode usar o método IUIAutomationTextRangePattern::RangeFromPoint para recuperar um intervalo de texto para o texto visível ou objeto inserido mais próximo das coordenadas de tela especificadas.
Selecionando texto em um intervalo de texto
A interface IUIAutomationTextRange inclui vários métodos que permitem que um aplicativo cliente controle a seleção de texto em um controle baseado em texto.
Os aplicativos cliente podem usar o método IUIAutomationTextRange::Select para selecionar o texto que corresponde a um intervalo de texto e remover a seleção anterior, se houver, do controle de texto. Chamar Selecionar com um intervalo de texto degenerado move o ponto de inserção para o local do intervalo de texto sem selecionar nenhum texto.
Se um controle der suporte à seleção de vários intervalos de texto não contíguos, um cliente poderá usar os métodos IUIAutomationTextRange::AddToSelection e RemoveFromSelection para adicionar intervalos de texto e removê-los da coleção de intervalos de texto selecionados. Se o controle der suporte a apenas um intervalo de texto selecionado por vez, mas a operação de seleção resultar na seleção de vários intervalos de texto não contíguos, o método retornará um erro de E_INVALIDOPERATION ou estenderá ou truncará a seleção atual. Um aplicativo cliente pode descobrir se um controle dá suporte à seleção de um ou vários intervalos de texto ou nenhum, verificando a propriedade IUIAutomationTextPattern::SupportedTextSelection .
Se um controle baseado em texto der suporte a inserções de texto, chamar IUIAutomationTextRange::AddToSelection ou RemoveFromSelection em um intervalo de texto degenerado no controle moverá o ponto de inserção, mas não selecionará nenhum texto.
Recuperando texto de um intervalo de texto
Os aplicativos cliente podem usar o método IUIAutomationTextRange::GetText para recuperar o texto sem formatação de um intervalo de texto. O texto sem formatação inclui 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 sem formatação não inclui marcas de marcação, como HTML, que podem estar presentes no texto de origem. Além disso, todos os códigos de escape no texto de origem são convertidos nos equivalentes de texto sem formatação. Por exemplo, " " " é convertido em um caractere de espaço simples.
Se um objeto inserido abranger um intervalo de texto, o texto sem formatação incluirá o texto interno do objeto, mas não o texto alternativo (a propriedade name do objeto inserido). Para obter mais informações, consulte Como Automação da Interface do Usuário expõe objetos inseridos.
O método IUIAutomationTextRange::FindText pesquisa um intervalo de texto para uma cadeia de caracteres específica e, se for encontrado, retorna um novo intervalo de texto que abrange a cadeia de caracteres.
Recuperando atributos de texto de um intervalo de texto
Os atributos de texto determinam o estilo de formatação do texto em um controle baseado em texto e incluem coisas como cor de primeiro plano, estilo de marcador, tamanho da fonte e assim por diante. Automação da Interface do Usuário dá suporte a vários atributos de texto e define um identificador para cada atributo com suporte. Um aplicativo cliente pode consultar um intervalo de texto para o valor de um atributo de texto específico especificando um identificador de atributo em uma chamada para o método IUIAutomationTextRange::GetAttributeValue , juntamente com um ponteiro para uma estrutura VARIANT que recebe o valor do atributo. Para obter informações detalhadas sobre cada atributo de texto compatível com Automação da Interface do Usuário, consulte Identificadores de atributo de texto.
O valor recuperado por GetAttributeValue representa o valor do atributo em todo o intervalo de texto. Se todo o texto no intervalo compartilhar o mesmo valor para o atributo especificado, esse valor será retornado por GetAttributeValue. No entanto, se o valor do atributo variar entre o intervalo de texto, GetAttributeValue retornará um ponteiro IUnknown para um objeto de token estático chamado objeto ReservedMixedAttribute . Para descobrir se o valor de um atributo varia entre um intervalo de texto, um aplicativo cliente deve comparar os resultados de GetAttributeValue com o objeto ReservedMixedAttribute recuperado da propriedade IUIAutomation::ReservedMixedAttributeValue .
Um controle baseado em texto não é necessário para dar suporte a todos os atributos de texto Automação da Interface do Usuário. Se um cliente chamar o método IUIAutomationTextRange::GetAttributeValue e passar o identificador de um atributo sem suporte, o método retornará um ponteiro IUnknown para um objeto de token estático chamado objeto ReservedNotSupported . Para descobrir se há suporte para um atributo específico, um aplicativo cliente deve comparar os resultados de GetAttributeValue com o objeto ReservedNotSupported recuperado da propriedade IUIAutomation::ReservedNotSupportedValue .
Os aplicativos cliente podem usar o método IUIAutomationTextRange::FindAttribute para pesquisar um intervalo de texto em busca de texto que tenha um atributo de texto específico. Se encontrado, o método retorna um novo intervalo de texto que abrange o texto correspondente. Observe que FindAttribute retorna um intervalo de texto para correspondência de texto mesmo se o texto não estiver visível.
Recuperando objetos inseridos de um intervalo de texto
Um intervalo de texto pode incluir objetos inseridos, como tabelas, imagens, hiperlinks e assim por diante. Um aplicativo cliente pode recuperar uma coleção de todos os objetos inseridos em um intervalo chamando o método IUIAutomationTextRange::GetChildren . Objetos inseridos que se sobrepõem ao intervalo, mas não são totalmente incluídos por ele, também são incluídos na coleção. Se o intervalo não contiver objetos inseridos, GetChildren recuperará uma coleção vazia.
Embora dependa do provedor do controle baseado em texto, o método GetChildren normalmente não retorna nenhum filho dos elementos inseridos. Por exemplo, se um intervalo de texto contiver uma tabela que tenha várias células filho, o método GetChildren normalmente retornará apenas o elemento table e não os elementos de célula.
Por motivos de desempenho ou arquitetura, GetChildren pode não conseguir recuperar objetos IUIAutomationElement para todos os objetos inseridos em um intervalo de texto. Em vez disso, o provedor pode retornar uma coleção que inclui itens virtualizados. Para obter mais informações, consulte Trabalhando com itens virtualizados.
Manipulando um intervalo de texto
A interface IUIAutomationTextRange fornece vários métodos para manipular e navegar intervalos de texto em um controle baseado em texto. Os métodos IUIAutomationTextRange::Move, MoveEndpointByUnit e 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 Automação da Interface do Usuário Unidades de Texto.
Apesar do nome, o método ExpandToEnclosingUnit 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 engloba exatamente a unidade de texto especificada. O intervalo será expandido se for menor que a unidade especificada ou encurtado se for maior que a unidade especificada. O diagrama a seguir mostra como ExpandToEnclosingUnit normaliza um intervalo de texto movendo os pontos de extremidade 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 de unidade de texto, o ponto de extremidade final será movido para o próximo limite de unidade de texto (consulte 1 e 2 na ilustração anterior).
Se o intervalo de texto começar no início de uma unidade de texto e terminar em ou depois do 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 (consulte 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 com uma unidade de texto de comprimento.
Se o intervalo de texto começar no meio de uma 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 de unidade após o ponto de extremidade inicial (consulte 5 a 8 na ilustração anterior).
Quando o método IUIAutomationTextRange::Move é chamado, o provedor normaliza o intervalo de texto pela unidade de texto especificada. 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 ignora os limites de quaisquer objetos inseridos no texto. (No entanto, o limite de unidade em si pode ser afetado pela existência de um objeto inserido). O diagrama a seguir demonstra como o método Move move um intervalo de texto, unidade por unidade, entre objetos inseridos e limites de unidade de texto.
O método IUIAutomationTextRange::MoveEndpointByUnit move um dos pontos de extremidade para frente ou para trás por unidade de texto especificada. A ilustração a seguir mostra como um ponto de extremidade avança.
O método IUIAutomationTextRange::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.
Rolando um intervalo de texto para exibição
O método IUIAutomationTextRange::ScrollIntoView rola um intervalo de texto para que o texto fique visível no visor do controle baseado em texto. Ao chamar ScrollIntoView, um cliente pode especificar se o texto deve ser alinhado com a parte superior ou inferior do visor.
Recuperando o elemento delimitador de um intervalo de texto
Um aplicativo cliente pode usar o método IUIAutomationTextRange::GetEnclosingElement para recuperar o ponteiro da interface IUIAutomation do elemento mais interno que inclui um intervalo de texto. O elemento delimitador normalmente é o provedor de texto que fornece o intervalo de texto. No entanto, se o provedor de texto der suporte a elementos filho, como tabelas ou hiperlinks, o elemento delimitador poderá ser um descendente do provedor de texto.
Comparando e clonando intervalos de texto
A interface IUIAutomationTextRange inclui dois métodos para comparar intervalos de texto. O método IUIAutomationTextRange::Compare compara os pontos de extremidade inicial e final de dois intervalos de texto e retorna TRUE se ambos os pontos de extremidade forem iguais. O método IUIAutomationTextRange::CompareEndpoints compara o ponto de extremidade inicial ou final dos dois intervalos. O valor retornado será zero se os pontos de extremidade forem iguais ou um valor positivo ou negativo que indique as posições relativas dos dois pontos de extremidade.
Os aplicativos cliente podem usar o método IUIAutomationTextRange::Clone para criar uma cópia exata do intervalo de texto. O novo intervalo de texto pode ser manipulado independentemente do intervalo de texto original.
Recuperando anotações
Um intervalo de texto poderá incluir anotações se o controle baseado em texto der suporte a elas. Há muitos tipos diferentes de anotações. O arquivo de cabeçalho UIAutomationClient.h define um conjunto de valores constantes nomeados que identificam os tipos de anotações compatíveis com Automação da Interface do Usuário. Para obter mais informações, consulte Identificadores de tipo de anotação.
Alguns tipos de anotações são representados por um elemento de automação que dá suporte ao padrão de controle Annotation (interface IUIAutomationAnnotationPattern ). Outros tipos de anotações são expostos por meio do padrão de controle TextRange . Por exemplo, um provedor pode expor um indicador simples de erro ortográfico fazendo com que o método IUIAutomationTextRange::GetAttributeValue retorne um atributo de texto AnnotationTypes de AnnotationType_SpellingError e um valor nulo para o atributo de texto AnnotationObjects .
Recuperando tipos de anotações de um intervalo de texto
Você pode recuperar uma lista dos tipos de anotações presentes em um intervalo de texto usando o método IUIAutomationTextRange::GetAttributeValue . Ao chamar o método , especifique uma ID de atributo de texto de UIA_AnnotationTypesAttributeId e um ponteiro para um parâmetro do tipo VARIANT. Quando o método retorna, o parâmetro VARIANT contém uma lista de identificadores de tipo de anotação, um para cada tipo de anotação no intervalo de texto. Para obter mais informações, consulte Identificadores de tipo de anotação.
Recuperando todas as anotações de um intervalo de texto
Para recuperar as anotações de um intervalo de texto, chame o método IUIAutomationTextRange::GetAttributeValue , especificando uma ID de atributo de texto de UIA_AnnotationObjectsAttributeId e um ponteiro para um parâmetro do tipo VARIANT. Quando o método retorna, o parâmetro VARIANTcontém uma interface IUIAutomationElementArray que representa uma matriz de elementos de automação, uma para cada anotação no intervalo de texto. A propriedade IUIAutomationElementArray::Length indica o número de elementos na matriz e o método IUIAutomationElementArray::GetElement recupera a interface IUIAutomationElement para um elemento específico.
Recuperando informações sobre uma anotação específica
Para recuperar informações sobre uma anotação específica, primeiro recupere a interface IUIAutomationElement para o elemento de anotação, conforme descrito na seção anterior. Em seguida, recupere a interface IUIAutomationAnnotationPattern para a anotação chamando o método IUIAutomationElement::GetCurrentPatternAs com uma ID de padrão de controle de UIA_AnnotationPatternId, um identificador de interface de IID_IUIAutomationAnnotationPattern e o endereço de uma variável que recebe o ponteiro IUIAutomationAnnotation para a anotação. Consulte as propriedades da interface IUIAutomationAnnotation para recuperar o nome do tipo de anotação e a ID do tipo, o nome do autor da anotação, a data e a hora da anotação e a interface IUIAutomationElement para o elemento que está sendo anotado.
Recuperando o texto de destino de anotação
Normalmente, uma anotação se aplica a algum subconjunto do texto em um intervalo de texto. Depois de recuperar a interface IUIAutomationElement para uma anotação, você pode passar a interface para o método IUIAutomationTextRange2::RangeFromAnnotation para recuperar um intervalo de texto que contém o texto que é o destino da anotação.
Recuperando estilos visuais
Um provedor implementa o padrão de controle Styles para descrever um elemento de interface do usuário que tem um estilo específico, cor de preenchimento, padrão de preenchimento ou forma. Isso é especialmente útil ao descrever elementos em um documento, que frequentemente têm esses estilos. Estilos como esse geralmente carregam informações úteis para clientes com deficiências; por exemplo, os estilos podem descrever uma determinada cadeia de caracteres como o título de um documento ou um determinado objeto de fluxograma como um losango ou um círculo.
Você pode usar o método IUIAutomationTextRange::GetAttributeValue para recuperar os nomes e identificadores dos estilos visuais usados em um intervalo de texto. Use o atributo de texto UIA_StyleNameAttributeId para recuperar os nomes de estilo e UIA_StyleIdAttributeId para recuperar os identificadores de estilo.
Um controle baseado em texto que dá suporte a estilos visuais pode implementar o padrão de controle Styles para permitir que os clientes acessem informações sobre um estilo visual usado pelo controle . Os clientes acessam o padrão de controle Styles por meio da interface IUIAutomationStylesPattern . Você pode recuperar essa interface chamando o método IUIAutomationElement::GetCurrentPattern ou GetCurrentPatternAs , especificando UIA_StylesPatternId como o identificador de padrão de controle.
A interface IUIAutomationStylesPattern inclui propriedades e métodos que fornecem as seguintes informações sobre um estilo visual:
- O nome do estilo visual, como "Normal" ou "Título 1".
- O identificador do estilo visual. Para obter mais informações, consulte Identificadores de estilo.
- A cor usada para preencher o controle baseado em texto.
- A cor do padrão usado para preencher o controle baseado em texto.
- A forma do controle baseado em texto.
- As propriedades estendidas; ou seja, uma lista de nomes e valores de estilo específicos do controle.
Invocando menus de contexto de intervalos de texto
Começando com Windows 8.1, os intervalos de texto podem dar suporte à interface IUIAutomationTextRange2. Essa interface dá suporte ao método ShowContextMenu . Você pode chamar esse método para invocar qualquer menu de contexto associado a um intervalo de texto. O cenário para isso é a autocorreção de intervalos de texto ou seleção de candidatos ao IME. Nesses casos, aparece um menu de contexto que dá suporte à interação do usuário.
Tópicos relacionados