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

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

Para Automação da Interface do Usuário, um objeto inserido é 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 inseridos e a árvore de Automação da Interface do Usuário

Os objetos inseridos são tratados como elementos individuais na exibição de controle da árvore 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 em Automação da Interface do Usuário.

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

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

A exibição de conteúdo de Automação da Interface do Usuário do documento anterior é mostrada 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 repositório de texto para cada objeto TextPattern que eles contêm. Os objetos apoiados pelo mesmo repositório de texto que seu contêiner são chamados de objetos incorporados "compatíveis". Esses objetos podem ser 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 repositórios de texto diferentes para diferentes objetos TextPattern inseridos em um contêiner TextPattern. Os objetos não suportados pelo repositório de texto do contêiner são chamados de objetos incorporados "não compatíveis". Esses tipos de objetos inseridos 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 consulta de objetos incorporados.

O conteúdo textual (ou texto interno) de um contêiner de texto e um objeto inserido, como um hiperlink ou célula de tabela, é exposto como um só fluxo de texto 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 de objeto são ignorados. Se um cliente da Automação da Interface do Usuário estiver recuperando o texto para recitar, interpretar ou analisar de alguma maneira, o intervalo de texto deverá 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 inserido e, em seguida, chame IUIAutomationTextPattern::RangeFromChild para obter um intervalo de texto para cada elemento. Isso é feito recursivamente até que todo o conteúdo textual seja recuperado.

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

Objetos incorporados e TextUnit

Um objeto ITextProvider pode ser percorrido e por um TextUnit especificado. Os provedores que contêm objetos inseridos podem ser percorridos da mesma maneira, mas os objetos inseridos afetam a passagem. Aqui estão algumas coisas que devem ser consideradas:

• Qualquer objeto inserido não compatível é representado pelo caractere de substituição U+FFFC no repositório de texto do TextPattern do elemento de contêiner. Também é considerado uma unidade de caractere e uma unidade de palavra.
• Objetos incorporados compatíveis podem consistir em vários caracteres e palavras.
• O elemento delimitador é o elemento mais inferior que abrange todo o intervalo de texto.
• Os elementos filho de um intervalo também são elementos filho de um elemento de contêiner que está parcial ou completamente incluído no intervalo.
• Idealmente (especialmente no caso de elementos de contêiner como Table), um limite de palavra não vai além do limite do objeto. No exemplo a seguir, a unidade de palavra "Bar" não contém nenhuma posição de texto que esteja fora da </td> tag (<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 \> é tratado como uma palavra individual de modo que não ultrapasse um limite de linha.
• Uma exceção à regra anterior é quando uma unidade de texto do Word contém objetos completos dentro de si mesma. Por exemplo, <p>Hello <a href="#">link</a> here.</p>, que inclui contêineres embutidos, tem as palavras "Olá", "link" e "aqui". Onde "link " tem um objeto TextPattern como o elemento delimitador e um objeto link como seu filho.
• No caso de unidades de caractere, o objeto é o elemento delimitador (unidades de texto como essa 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 em um documento de 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 no intervalo de documentos TextPattern.
• Para HTML, cada marca html não resulta necessariamente em um objeto de automação da interface do usuário. Por exemplo, o conteúdo dentro das tags de ênfase não precisa ser representado como elemento, mas sim uma trasmissão de texto em UIA_IsItalicAttributeId retorna TRUE.
• O ponto de extremidade inicial é inclusivo e é o ponto de extremidade preferencial, enquanto o ponto de extremidade final é exclusivo. Isso é útil para quando o intervalo é degenerado e os pontos de extremidade Início e Término pertencem à mesma posição para esse intervalo.

Comparando objetos incorporados

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

Um objeto não TextPattern incorporado em um objeto TextPattern será 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 o Document TextUnit

Para objetos TextPattern inseridos, 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 repositório de texto com todo o documento TextPattern).

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

• O elemento Pane da página da Web principal implementa TextPattern e expõe todo o conteúdo da página da Web.
• Os controles de entrada de texto individuais dão suporte a TextPattern, em que um intervalo de documentos representa o texto contido em cada campo de entrada (mesmo que eles compartilhem o mesmo repositório 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 extremidade inicial do intervalo de texto e a chave direita (}) representa o ponto de extremidade final.

Exemplo de HyperLink 1 – Um intervalo de texto que contém um hiperlink de texto inserido

O intervalo de texto a seguir contém um hiperlink de texto incorporado.

(A URL https://www.microsoft.com é incorporada no texto).

Chamar os métodos IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren e IUIAutomationTextPattern::RangeFromChild resulta nos comportamentos descritos na tabela a seguir.

Exemplo de HyperLink 2 – Um intervalo de texto que percorre parcialmente um hiperlink de texto inserido

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

A URL https://{www} é incorporada no texto.

Chamar os métodos IUIAutomationTextRange::GetText, GetEnclosingElement, e GetChildren resulta nos comportamentos descritos na tabela a seguir.

Exemplo de HyperLink 3: 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 contêiner de texto tem um hiperlink de texto inserido que não faz parte do intervalo de texto.

(A URL) https://www.microsoft.com é incorporada no texto.

Chamar os métodos IUIAutomationTextRange::GetText, GetEnclosingElement, e Move resulta nos comportamentos descritos na tabela a seguir.

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 espacial.

{A imagem está incorporada ao texto}.

Chamar os métodos IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren e 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. O contêiner de texto tem uma imagem incorporada que não faz parte do intervalo de texto.

{A imagem} está incorporada ao texto.

Chamar os métodos IUIAutomationTextRange::GetText, GetEnclosingElement, e Move resulta nos comportamentos descritos na tabela a seguir.

Tabela

Exemplo de tabela 1 – Obter 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 resultados de métodos IUIAutomationGridPattern::GetItem, IUIAutomationTextPattern::RangeFromChild, e IUIAutomationTextRange::GetEnclosingElement nos comportamentos descritos na tabela a seguir.

Método chamado	Resultado
IUIAutomationGridPattern::GetItem com parâmetros (0, 0).	Retorna o elemento UI Automation que representa o conteúdo da célula da tabela; nesse caso, o elemento é um controle de texto.
iuiautomationtextpattern::rangefromchild	Retorna o intervalo da imagem .
GetEnclosingElement para o objeto retornado pelo método IUIAutomationTextPattern::RangeFromChild anterior.	Retorna o elemento Automação da Interface do Usuário que representa a célula da tabela. Nesse caso, o elemento é um controle de texto que dá suporte ao padrão de controle TableItem.
IUIAutomationTextRange::GetEnclosingElement para o objeto retornado pelo método GetEnclosingElement anterior.	Retorna o elemento UI Automation que representa a célula da tabela.
IUIAutomationTextRange::GetEnclosingElement para o objeto retornado pelo método GetEnclosingElement anterior.	Retorna o elemento UI Automation que representa o próprio provedor de texto.

Exemplo de tabela 2 – Obter o conteúdo do texto de uma célula.

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

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

Ao percorrer um documento por TextUnit_Line, se o intervalo de texto entrar em uma tabela incorporada, cada linha de texto em uma célula deverá ser tratada como uma linha.

Tópicos relacionados

Conceitual

• Sobre os padrões de controle Text e TextRange
• Atributos de texto da automação da interface do usuário
• Visão Geral de Padrões de Controle de Automação de Interface de Usuário
• Suporte da Automação da Interface do Usuário ao conteúdo textual