Como Automação da Interface do Usuário expõe objetos inseridos

Este tópico descreve como a Microsoft Automação da Interface do Usuário 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).

Observação

Isso difere da definição de OLE do COM (Component Object Model) (consulte Objetos Inseridos), em que um elemento é criado em um aplicativo e inserido ou vinculado em outro aplicativo. Se o objeto pode ser editado em seu aplicativo original é irrelevante no contexto de Automação da Interface do Usuário.

Objetos inseridos e a árvore de Automação da Interface do Usuário

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 no Automação da Interface do Usuário.

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

Elementos de contêiner

Elementos que não são de contêiner

• Calendário
• Combobox
• DataGrid
• Documento
• Editar
• Grupo
• Cabeçalho
• HeaderItem
• Lista
• Menu

• MenuBar
• Painel
• SplitButton
• Tab
• Tabela
• Barra de ferramentas
• Árvore
• TreeItem
• Janela

• Link
• Caixas
• Botão

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

A exibição de conteúdo Automação da Interface do Usuário do documento anterior é mostrada no diagrama a seguir.

Objetos inseridos "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 contêm. Objetos apoiados pelo mesmo repositório de texto que seu contêiner são chamados de objetos inseridos "compatíveis". Esses objetos podem ser objetos TextPattern em si 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 diferentes repositórios de texto para diferentes objetos TextPattern inseridos em um contêiner TextPattern. Objetos não apoiados pelo repositório de texto do contêiner são chamados de objetos inseridos "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 inseridos compatíveis e não compatíveis.

Objetos	Objetos inseridos compatíveis	Objetos inseridos não compatíveis
Objetos inseridos não TextPattern	Botão no Microsoft Edge Tabela de dados no Microsoft Edge	Botão no RichTextBlock na estrutura XAML da Microsoft Imagens com texto alt no Microsoft Edge ListView com ListItems em RichTextBlock na estrutura XAML da Microsoft
Objetos inseridos textPattern	Controle de entrada do tipo "text" no Microsoft Edge Tabela em um documento Word	Elemento TextBox em um documento do Microsoft Word

Expondo objetos inseridos

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

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 Automação da Interface do Usuário estiver recuperando o texto para recitar, interpretar ou analisar de alguma forma, o intervalo de texto deverá ser verificado quanto a casos especiais, como uma tabela com conteúdo textual ou outros objetos inseridos. 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.

Observação

Um intervalo degenerado (ou recolhido) é onde o ponto de extremidade inicial e o ponto de extremidade são iguais. Intervalos degenerados geralmente são usados para indicar a posição do cursor de texto por meio dos métodos ITextProviderGetSelection e GetCaretRange .

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

Objetos inseridos e TextUnit

Um objeto ITextProvider pode ser percorrido e por um TextUnit especificado. Provedores que contêm objetos inseridos podem ser percorridos da mesma maneira, mas objetos inseridos afetam a passagem. Aqui estão algumas coisas que você deve estar ciente:

• Qualquer objeto inserido não compatível é representado pelo caractere de substituição U+FFFC no repositório de texto do TextPattern do elemento contêiner. Ele também é considerado uma unidade de caracteres e uma unidade de palavra.
• Objetos inseridos compatíveis podem consistir em vários caracteres e palavras.
• O elemento delimitador é o elemento mais inferior que abrange todo o intervalo de texto.
• Elementos filho de um intervalo também são elementos filho de um elemento de contêiner que está parcial ou completamente entre o 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 palavra unidade "Barra" não contém nenhuma posição de texto fora da </td> marca (<br \> não faz parte da palavra "Barra").

<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 vá além de um limite de linha.
• Uma exceção à regra anterior é onde uma unidade de texto Word contém objetos completos dentro de si. Por exemplo, , <p>Hello <a href="#">link</a> here.</p>que inclui contêineres embutidos, tem as palavras "Olá", "link" e "aqui". Em que "link" tem um objeto TextPattern como o elemento delimitador e um objeto de link como seu filho.
• No caso de unidades character, o objeto é o elemento delimitador (unidades de texto como esta não devem ter filhos).
• Os objetos de anotação não devem ser representados como objeto inserido. Por exemplo, a presença de outros especificadores author em um documento de coautoria.
• Os objetos inseridos assumem pelo menos uma posição de 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 necessariamente resulta em um objeto Automação da Interface do Usuário. Por exemplo, o conteúdo dentro de marcas de ênfase não precisa ser representado como elemento, mas sim um fluxo de texto em que UIA_IsItalicAttributeId retorna TRUE.
• O ponto de extremidade inicial é inclusivo e é o ponto de extremidade preferencial enquanto o ponto de extremidade de extremidade é exclusivo. Isso é útil para quando o intervalo é degenerado e os pontos de extremidade Start e End pertencem à mesma posição para esse intervalo.

Comparando objetos inseridos

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, 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 inserido 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 inseridos e TextUnit do Documento

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

Word hierarquia de elementos TextPattern

• O elemento document implementa TextPattern e Document retorna todo o Word intervalo de documentos.
• 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).

Página da Web e controles de entrada de texto no Edge

• O elemento Painel da página da Web main implementa TextPattern e expõe todo o conteúdo da página da Web.
• 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 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 inseridos: 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 Hiperlink 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 inserido.

{A URL https://www.microsoft.com está inserida no texto}.

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

Método chamado	Result
IUIAutomationTextRange::GetText	Retorna a cadeia de caracteres "A URL https://www.microsoft.com está inserida no texto".
IUIAutomationTextRange::GetEnclosingElement	Retorna o elemento de Automação da Interface do Usuário mais interno que inclui o intervalo de texto, nesse caso, o elemento de automação que representa o próprio provedor de texto.
IUIAutomationTextRange::GetChildren	Retorna um elemento Automação da Interface do Usuário que representa o controle de hiperlink.
IUIAutomationTextPattern::RangeFromChild, em que o elemento Automação da Interface do Usuário foi retornado pelo método IUIAutomationTextRange::GetChildren anterior.	Retorna o intervalo que representa "https://www.microsoft.com".

Exemplo de Hiperlink 2: um intervalo de texto que abrange parcialmente um hiperlink de texto inserido

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

A URL https://{www} está inserida no texto.

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

Método chamado	Result
IUIAutomationTextRange::GetText	Retorna a cadeia de caracteres "www".
IUIAutomationTextRange::GetEnclosingElement	Retorna o elemento Automação da Interface do Usuário mais interno que inclui o intervalo de texto; nesse caso, o controle de hiperlink.
IUIAutomationTextRange::GetChildren	Retorna NULL porque o intervalo de texto não abrange toda a cadeia de caracteres de URL.

Exemplo de Hiperlink 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 é inserido no texto.

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

Método chamado	Result
IUIAutomationTextRange::GetText	Retorna a cadeia de caracteres "The URL".
IUIAutomationTextRange::GetEnclosingElement	Retorna o elemento Automação da Interface do Usuário mais interno que inclui o intervalo de texto, nesse caso, o elemento que representa o próprio provedor de texto.
IUIAutomationTextRange::Move	Move o intervalo de texto para "https://" porque o texto do hiperlink é composto por palavras individuais. Nesse caso, o hiperlink não é tratado como um objeto. A URL {http} está inserida no texto.

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

O intervalo de texto a seguir contém uma imagem inserida de uma nave auxiliar.

{A inserida em texto}.

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

Método chamado	Result
IUIAutomationTextRange::GetText	Retorna a cadeia de caracteres "A imagem está inserida no texto". Qualquer texto ALT associado à imagem não está incluído no fluxo de texto.
IUIAutomationTextRange::GetEnclosingElement	Retorna o elemento Automação da Interface do Usuário mais interno que inclui o intervalo de texto, nesse caso, o elemento que representa o próprio provedor de texto.
IUIAutomationTextRange::GetChildren	Retorna um elemento Automação da Interface do Usuário que representa o controle de imagem.
IUIAutomationTextPattern::RangeFromChild em que o elemento Automação da Interface do Usuário foi retornado pelo método IUIAutomationTextRange::GetChildren anterior.	Retorna o intervalo degenerado.

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} é inserida em texto.

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

Método chamado	Result
IUIAutomationTextRange::GetText	Retorna a cadeia de caracteres "The image".
IUIAutomationTextRange::GetEnclosingElement	Retorna o elemento Automação da Interface do Usuário mais interno que inclui o intervalo de texto, nesse caso, o elemento que representa o próprio provedor de texto.
IUIAutomationTextRange::Move com parâmetros de (TextUnit_Word, 2).	Move o intervalo de texto para "is ". Como somente objetos inseridos baseados em texto são considerados parte do fluxo de texto, a imagem neste exemplo não afeta IUIAutomationTextRange::Move ou seu valor retornado, neste caso, 2.

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
	S
	Z

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

Método chamado	Result
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 de tabela, nesse caso, o elemento é um controle de texto.
iuiautomationtextpattern::rangefromchild	retorna o intervalo da .
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 Automação da Interface do Usuário que representa a tabela.
IUIAutomationTextRange::GetEnclosingElement para o objeto retornado pelo método GetEnclosingElement anterior.	Retorna o elemento Automação da Interface do Usuário 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.

Método chamado	Result
IUIAutomationGridPattern::GetItem com parâmetros (1,1).	Retorna o elemento Automação da Interface do Usuário que representa o conteúdo da célula da tabela. Nesse caso, o elemento é um controle de texto.
IUIAutomationTextPattern::RangeFromChild em que o elemento Automação da Interface do Usuário é o objeto retornado pelo método IUIAutomationGridPattern::GetItem anterior.	Retorna "Y".

Ao mover um documento por TextUnit_Line, se o intervalo de texto entrar em uma tabela inserida, 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 Automação da Interface do Usuário
• Visão Geral de Padrões de Controle de Automação de Interface de Usuário
• suporte Automação da Interface do Usuário para conteúdo textual