Partilhar via

Padrão de controle de anotação

  • Artigo

Descreve diretrizes e convenções para implementar IAnnotationProvider, incluindo informações sobre propriedades e métodos. O padrão de controle anotação é usado para expor as propriedades de uma anotação em um documento.

Um exemplo é um balão de comentário que está na margem de um documento e está conectado a algum texto do documento ou a uma célula da planilha.

A ilustração a seguir mostra um exemplo de uma anotação. Para obter exemplos de controles que implementam esse padrão de controle, consulte tipos de controle e seus padrões de controle suportados.

captura de tela mostrando um balão de comentários em um documento

Este tópico contém as seguintes seções.

Orientações e convenções de aplicação

Ao implementar o padrão de controle anotação, observe as seguintes diretrizes e convenções:

  • Existem 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 que a Automação da Interface do Usuário da Microsoft suporta. Para obter mais informações, consulte Identificadores de tipo de anotação.
  • Se você usar AnnotationType_Unknown, deverá implementar a propriedade IAnnotationProvider::AnnotationTypeName para permitir que os clientes descubram o nome do tipo de anotação. Não é necessário implementar AnnotationTypeName para um tipo de anotação padrão porque a Automação da Interface do Usuário fornece um nome padrão, mas você pode implementá-lo se precisar substituir o nome padrão.
  • A propriedade IAnnotationProvider::Author é opcional.
  • A propriedade IAnnotationProvider::D ateTime é opcional.
  • A propriedade IAnnotationProvider::Target é necessária porque vincula uma anotação a um elemento da interface do usuário, permitindo que um cliente navegue da anotação de volta para o elemento da interface do usuário ao qual a anotação se refere.
  • Como as anotações podem assumir muitas formas diferentes, o IAnnotationProvider interface não define uma propriedade para armazenar o valor ou o texto de uma anotação. Uma anotação simples deve expor a interfaceIValueProvider e a propriedade IValueProvider::Value deve retornar um valor somente leitura que especifica o texto da anotação. Uma anotação mais rica deve expor o ITextProvider interface para fornecer texto mais rico aos clientes.
  • Navegar de um elemento da interface do usuário para uma anotação no elemento depende do tipo de elemento que está sendo anotado, da seguinte maneira:
  • Alguns tipos de anotações não exigem uma implementação completa do IAnnotationProvider interface. Por exemplo, um indicador de erro ortográfico simples pode ser representado fazendo com que a interface ITextRangeProvider retorne um AnnotationTypes atributo de texto de AnnotationType_SpellingErrore um valor nulo para o AnnotationObjects atributo text.
  • Pode ser útil implementar o IAnnotationProvider interface em um elemento da interface do usuário que não está visível. Por exemplo, você pode criar um elemento de automação da interface do usuário não visível que implementa IAnnotationProvider para fornecer informações estendidas sobre um erro gramatical.
  • As anotações em um controle baseado em texto podem ser complexas se o controle contiver comentários sobrepostos. Use as seguintes diretrizes para lidar com anotações complexas:
    • Um intervalo de texto sem anotações deve retornar uma matriz vazia para o atributo AnnotationTypes text e uma matriz vazia para o atributo AnnotationObjects text.
    • Um intervalo de texto com uma anotação deve retornar uma matriz de um valor inteiro para o atributo AnnotationTypes text e uma matriz de um IRawElementProviderSimple interface para o AnnotationObjects atributo text.
    • Um intervalo de texto com várias anotações deve retornar uma matriz de vários valores inteiros para o atributo AnnotationTypes text e uma matriz de um número correspondente de interfaces de IRawElementProviderSimple para o AnnotationObjects atributo text.
    • Um intervalo de texto com anotações variáveis, como um intervalo com texto anotado e não anotado, deve retornar a propriedadeReservedMixedAttributeValue para AnnotationTypes e AnnotationObjects. Um cliente que recebe essa resposta pode subdividir o intervalo de texto para encontrar onde as anotações começam e terminam.

Membros necessários para IAnnotationProvider

As propriedades a seguir são necessárias para implementar o IAnnotationProvider interface.

Membros obrigatórios Tipo de membro Observações
AnnotationTypeId Propriedade Nenhuma.
AnnotationTypeName Propriedade Nenhuma.
Autor Propriedade Nenhuma.
DateTime Propriedade Nenhuma.
Target Propriedade Nenhuma.

 

Esse padrão de controle não tem eventos associados.

tipos de controle e seus padrões de controle suportados

Visão geral dos padrões de controle de automação da interface do do usuário

Visão geral da árvore de automação da interface do usuário