Como a automação da interface do usuário expõe objetos incorporados

Este tópico descreve como a Automação da Interface do Usuário da Microsoft usa os padrões de controle Text e TextRange para expor objetos incorporados (elementos filho/descendente) em um documento de texto ou contêiner.

Para a Automação da Interface do Usuário, um objeto incorporado é qualquer elemento que tenha limites não textuais, como uma imagem, hiperlink, tabela ou tipo de documento (planilha do Microsoft Excel, arquivo do Microsoft Windows Media e assim por diante).

Objetos incorporados e a árvore de automação da interface do usuário

Os objetos incorporados são tratados como elementos individuais na exibição de controle da árvore de Automação da Interface do Usuário. Eles são expostos como filhos do contêiner de texto para que possam ser acessados por meio do mesmo modelo de objeto que outros controles na Automação da Interface do Usuário.

A tabela a seguir lista exemplos de elementos contêiner e não contêiner.

A imagem a seguir mostra um contêiner de texto (documento) com uma tabela e uma imagem incorporadas.

A vista de conteúdo de Automação da Interface de Utilizador do documento anterior é apresentada no diagrama a seguir.

Objetos incorporados "compatíveis" e "não compatíveis"

Alguns provedores de automação da interface do usuário usam o mesmo armazenamento de texto para cada objeto TextPattern que eles contêm. Os objetos apoiados pelo mesmo armazenamento de texto que seu contêiner são chamados de objetos incorporados "compatíveis". Esses objetos podem ser os próprios objetos TextPattern e, nesse caso, seus intervalos de texto são comparáveis aos intervalos de texto obtidos de seu contêiner. Isso permite que os provedores exponham informações do cliente sobre os objetos TextPattern individuais como se fossem um provedor de texto grande.

No entanto, os provedores podem usar armazenamentos de texto diferentes para diferentes objetos TextPattern incorporados em um contêiner TextPattern. Os objetos não suportados pelo armazém de texto do contentor são referidos como objetos incorporados não compatíveis. Esses tipos de objetos incorporados podem ou não ser objetos baseados em TextPattern.

A tabela a seguir lista alguns exemplos de objetos incorporados compatíveis e não compatíveis.

Expondo objetos incorporados

Os padrões de controle Text e TextRange expõem propriedades e métodos que facilitam a navegação e a consulta de objetos incorporados.

O conteúdo textual (ou texto interno) de um contêiner de texto e um objeto incorporado, como um hiperlink ou célula de tabela, é exposto como um fluxo de texto único e contínuo na exibição de controle e na exibição de conteúdo da árvore de Automação da Interface do Usuário; Os limites do objeto são ignorados. Se um cliente de automação da interface do usuário estiver recuperando o texto para recitar, interpretar ou analisar de alguma maneira, o intervalo de texto deve ser verificado para casos especiais, como uma tabela com conteúdo textual ou outros objetos incorporados. Chame IUIAutomationTextRange::GetChildren para obter uma interface IUIAutomationElement para cada objeto incorporado e, em seguida, chame o IUIAutomationTextPattern::RangeFromChild para obter um intervalo de texto para cada elemento. Isso é feito recursivamente até que todo o conteúdo textual tenha sido recuperado.

O diagrama a seguir mostra um fluxo de texto com objetos incorporados e seus intervalos.

Objetos incorporados e TextUnit

Um ITextProvider objeto pode ser percorrido e por um especificado TextUnit. Os fornecedores que contêm objetos incorporados podem ser percorridos de forma semelhante, mas os objetos incorporados afetam o percurso. Aqui estão algumas coisas a ter em conta:

• Qualquer objeto incorporado não compatível é representado pelo caractere de substituição U+FFFC no armazenamento de texto do TextPattern do elemento contêiner. Também é considerada uma unidade de caracteres e uma unidade de palavras.
• Os objetos incorporados compatíveis podem consistir em vários caracteres e palavras.
• O elemento envolvente é o elemento inferior que abrange todo o intervalo de texto.
• Os elementos filho de um intervalo também são elementos filho de um elemento contedor que está parcial ou completamente abrangido dentro do intervalo.
• Idealmente (especialmente no caso de elementos de contentor como tabela) o limite de uma palavra não vai além do limite do objeto. No exemplo a seguir, a unidade de palavras "Bar" não contém nenhuma posição de texto que esteja fora da marca </td> (<br \> não faz parte da palavra "Bar").

<table style="width:100%">
  <tr>
    <th>Name</th>
    <th>Notes</th>
  </tr>
  <tr>
    <td>Eve Jackson</td>
    <td>Foo Bar</td>
  </tr>
</table>
<br/>

• Em geral, <br \> é tratada como uma palavra individual de tal forma que não ultrapassa um limite de linha.
• Uma exceção à regra anterior é quando uma unidade de texto do Word contém objetos completos dentro de si. Por exemplo, <p>Hello <a href="#">link</a> here.</p>, que inclui contêineres em linha, contém as palavras "Olá", "link" e "aqui". Onde "link" tem um objeto TextPattern como o elemento envolvente e um objeto de ligação como seu filho.
• No caso de unidades de caracteres, o objeto é o elemento de encerramento (unidades de texto como esta não devem ter filhos).
• Os objetos de anotação não devem ser representados como objeto incorporado. Por exemplo, a presença de outros especificadores de Autor num documento com coautoria.
• Os objetos incorporados ocupam pelo menos uma posição do cursor, a anotação é apenas metadados.
• Cada limite de objeto (início e fim) é representado por uma quebra de formato dentro do intervalo do documento TextPattern.
• Para HTML, cada etiqueta HTML não resulta necessariamente num objeto de automação da interface do utilizador. Por exemplo, o conteúdo dentro tags de ênfase não precisa ser representado como elemento, mas sim como um fluxo de texto onde UIA_IsItalicAttributeId retorna TRUE.
• O ponto de extremidade inicial é inclusivo e é o ponto de extremidade preferido, enquanto o ponto de extremidade final é exclusivo. Isso é útil quando o intervalo é degenerado e as extremidades Início e Fim estão na mesma posição para esse intervalo.

Comparando objetos incorporados

Os objetos TextPattern aninhados que estão em uma relação filho semelhante e compartilham o mesmo armazenamento de texto de suporte são chamados comparáveis. Nesse caso, os intervalos de qualquer um dos objetos TextPattern podem ser comparados usando ITextRangeProvider::Compare e ITextRangeProvider::CompareEndpoints. Ambos resultam num valor numérico válido que especifica a sua posição relativa.

Um objeto não-TextPattern incorporado em um objeto TextPattern é comparável ao TextPattern se o objeto tiver um intervalo válido no TextPattern (ITextProvider::RangeFromChild) e o conteúdo por trás do intervalo de texto não estiver vazio e não for um caractere de substituição.

Objetos TextPattern incorporados e a Unidade de Texto do Documento

Para objetos TextPattern incorporados, a unidade Document reconhece apenas o conteúdo contido nesse elemento.

Hierarquia de elementos TextPattern do Word

• O elemento document implementa TextPattern e Document retorna todo o intervalo de documentos do Word.
• Páginas individuais do documento implementam TextPattern e Document retorna o conteúdo dessas páginas individuais (mesmo que as páginas compartilhem o mesmo armazenamento de texto com todo o documento TextPattern).

Controles de entrada de texto e página da Web no Edge

• O elemento do tipo 'Pane' na página principal da web implementa o TextPattern e expõe todo o conteúdo da página.
• Os controles de entrada de texto individuais suportam TextPattern onde um intervalo de documentos representa o texto contido em cada campo de entrada (mesmo que eles compartilhem o mesmo armazenamento de texto com toda a página da Web).

Cenários comuns

Esta seção apresenta exemplos de cenários comuns que envolvem objetos incorporados: hiperlinks, imagens e tabelas. Nos exemplos a seguir, a chave esquerda ({) representa o ponto de início do intervalo de texto, e a chave direita (}) representa o ponto de término.

Exemplo 1 do HyperLink: um intervalo de texto que contém um hiperlink de texto incorporado

A faixa de texto a seguir contém um hiperlink de texto embutido.

O URL https://www.microsoft.com está incorporado no texto.

Chamar o IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildrene IUIAutomationTextPattern::RangeFromChild resulta nos comportamentos descritos na tabela a seguir.

Exemplo 2 do HyperLink: um intervalo de texto que abrange parcialmente um hiperlink de texto incorporado

O intervalo de texto a seguir abrange parcialmente um hiperlink de texto incorporado.

O URL https://{www} está incorporado no texto.

Chamar os métodos IUIAutomationTextRange::GetText, GetEnclosingElemente GetChildren resulta nos comportamentos descritos na tabela seguinte.

Exemplo 3 do HyperLink: um intervalo de texto que abrange parcialmente o conteúdo de um contêiner de texto

O intervalo de texto a seguir abrange parcialmente o conteúdo de um contêiner de texto. O contentor de texto tem um hiperlink incorporado que não faz parte da faixa de texto.

{O URL} https://www.microsoft.com está incorporado no texto.

Chamar os métodos IUIAutomationTextRange::GetText, GetEnclosingElemente Move resulta nos comportamentos descritos na tabela seguinte.

Exemplo de imagem 1: um intervalo de texto que contém uma imagem incorporada

O intervalo de texto a seguir contém uma imagem incorporada de um ônibus.

A imagem está incorporada no texto.

Chamar o IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildrene IUIAutomationTextPattern::RangeFromChild resulta nos comportamentos descritos na tabela a seguir.

Exemplo de imagem 2: um intervalo de texto que abrange parcialmente o conteúdo de um contêiner de texto

O intervalo de texto a seguir abrange parcialmente o conteúdo de um contêiner de texto. A caixa de texto tem uma imagem incorporada que não faz parte da faixa de texto.

{A imagem} está incorporada no texto.

Chamar os métodos IUIAutomationTextRange::GetText, GetEnclosingElemente Move resulta nos comportamentos descritos na tabela seguinte.

Tabela

Exemplo de tabela 1: obtém o contêiner de texto do conteúdo de uma célula

A tabela a seguir obtém o contêiner de texto do conteúdo de uma célula.

Célula com Imagem	Célula com texto
	X
	Y
	Z

Chamar os métodos IUIAutomationGridPattern::GetItem, IUIAutomationTextPattern::RangeFromChild, e IUIAutomationTextRange::GetEnclosingElement resulta nos comportamentos descritos na tabela abaixo.

Método denominado	Resultado
IUIAutomationGridPattern::GetItem com parâmetros (0, 0).	Retorna o elemento Automação da interface do usuário que representa o conteúdo da célula da tabela, neste caso, o elemento é um controle de texto.
IUuAutomationTextPattern::RangeFromChild	Devolve o intervalo da imagem .
GetEnclosingElement para o objeto retornado pelo anterior IUIAutomationTextPattern::RangeFromChild método.	Retorna o elemento de automação da interface do utilizador que representa a célula da tabela. Nesse caso, o elemento é um controlo de texto que suporta o padrão de controlo TableItem.
IUIAutomationTextRange::GetEnclosingElement para o objeto retornado pelo método GetEnclosingElement anterior.	Retorna o elemento de automação da interface do utilizador que representa a tabela.
IUIAutomationTextRange::GetEnclosingElement para o objeto retornado pelo método anterior GetEnclosingElement.	Retorna o elemento de Automação da UI que representa o próprio provedor de texto.

Exemplo de tabela 2: obtém o conteúdo de texto de uma célula

A tabela no exemplo anterior obtém o conteúdo de texto de uma célula.

Chamar os métodos IUIAutomationGridPattern::GetItem e IUIAutomationTextPattern::RangeFromChild resulta nos comportamentos descritos na tabela a seguir.

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.

Tópicos relacionados

Conceptual

• Sobre os padrões de controle Text e TextRange
• Atributos de Texto de Automação de Interface do Usuário
• Visão geral dos padrões de controlo de automação da interface do utilizador
• Suporte de automação de interface do usuário para conteúdo textual