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).
Observação
Isso difere da definição OLE do COM (Component Object Model) (consulte Objetos Incorporados), em que um elemento é criado em um aplicativo e inserido ou vinculado a 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
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.
Elementos de contêiner
Elementos não-contêiner
- Calendário
- Combobox
- DataGrid
- Documento
- Edição
- Grupo
- Cabeçalho
- HeaderItem
- Lista
- Menu
- MenuBar
- Painel
- SplitButton
- Tabulação
- Tabela
- Barra de ferramentas
- Árvore
- TreeItem
- Janela
- Link
- CheckBoxes
- 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 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.
| Objetos | Objetos incorporados compatíveis | Objetos incorporados não compatíveis |
|---|---|---|
| Objetos incorporados que não são TextPattern | Botão no Microsoft Edge Tabela de dados no Microsoft Edge |
Botão em RichTextBlock na estrutura XAML da Microsoft Imagens com texto alternativo no Microsoft Edge ListView com ListItems em RichTextBlock na estrutura XAML da Microsoft |
| Objetos incorporados que são TextPattern | Controle de entrada do tipo "texto" no Microsoft Edge Tabela em um documento do Word |
TextBox em um documento do Microsoft Word |
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.
Observação
Um intervalo degenerado (ou recolhido) é onde o ponto de extremidade inicial e o ponto final são iguais. Os intervalos degenerados geralmente são usados para indicar a posição do cursor de texto por meio dos métodos ITextProvider, GetSelection e GetCaretRange.
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.
| Método chamado | Resultado |
|---|---|
| IUIAutomationTextRange::GetText | Retorna a cadeia de caracteres "The URL https://www.microsoft.com is embedded in text". |
| IUIAutomationTextRange::GetEnclosingElement | Retorna o elemento UI Automation mais interno que abrange o intervalo de texto, neste caso, o elemento de automação que representa o próprio provedor de texto. |
| IUIAutomationTextRange::GetChildren | Retorna um elemento UI Automation que representa o controle de hiperlink. |
| IUIAutomationTextPattern::RangeFromChild, em que o elemento UI Automation foi retornado pelo método IUIAutomationTextRange::GetChildren. | Retorna o intervalo que representa "https://www.microsoft.com". |
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.
| Método chamado | Resultado |
|---|---|
| IUIAutomationTextRange::GetText | Retorna a cadeia de caracteres "www". |
| IUIAutomationTextRange::GetEnclosingElement | Retorna o elemento UI Automation 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 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.
| Método chamado | Resultado |
|---|---|
| IUIAutomationTextRange::GetText | Retorna a cadeia de caracteres "The URL". |
| IUIAutomationTextRange::GetEnclosingElement | Retorna o elemento UI Automation mais interno que abrange o intervalo de texto, neste caso, o elemento que representa o próprio provedor de texto. |
| IUIAutomationTextRange::Move | Move o intervalo de texto para "https://" pois o texto do hiperlink é composto por palavras individuais. Nesse caso, o hiperlink não é tratado como um objeto. A URL {http} é incorporada no texto. |
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.
| Método chamado | Resultado |
|---|---|
| IUIAutomationTextRange::GetText | Retorna a cadeia de caracteres "The image is embedded in text". Nenhum texto alternativo associado à imagem pode ser incluído na transmissão do texto. |
| IUIAutomationTextRange::GetEnclosingElement | Retorna o elemento UI Automation mais interno que abrange o intervalo de texto, neste caso, o elemento que representa o próprio provedor de texto. |
| IUIAutomationTextRange::GetChildren | Retorna um elemento UI Automation que representa o controle de imagem. |
| IUIAutomationTextPattern::RangeFromChild, em que o elemento UI Automation foi retornado pelo método IUIAutomationTextRange::GetChildren. | 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} está incorporada ao texto.
Chamar os métodos IUIAutomationTextRange::GetText, GetEnclosingElement, e Move resulta nos comportamentos descritos na tabela a seguir.
| Método chamado | Resultado |
|---|---|
| IUIAutomationTextRange::GetText | Retorna a cadeia de caracteres "The image". |
| IUIAutomationTextRange::GetEnclosingElement | Retorna o elemento UI Automation mais interno que abrange o intervalo de texto, neste 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 nem seu valor retornado (nesse caso, 2). |
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.
| Método chamado | Resultado |
|---|---|
| IUIAutomationGridPattern::GetItem com parâmetros (1,1). | 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 em que o elemento UI Automation é o objeto retornado pelo método IUIAutomationGridPattern::GetItem anterior. | Retorna "Y". |
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.