Padrão de controle de anotação

Descreve diretrizes e convenções para implementar IAnnotationProvider, incluindo informações sobre propriedades e métodos. O padrão de controle de 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 de planilha.

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

Este tópico inclui as seções a seguir.

• Diretrizes e convenções de implementação
• Membros necessários para IAnnotationProvider
• Tópicos relacionados

Diretrizes e convenções de implementação

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

• Há 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 compatíveis com a Microsoft Automação da Interface do Usuário. 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. Você não precisa implementar AnnotationTypeName para um tipo de anotação padrão porque 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 de interface do usuário, permitindo que um cliente navegue da anotação de volta para o elemento de interface do usuário ao qual a anotação se refere.
• Como as anotações podem tomar várias formas diferentes, a interface IAnnotationProvider não define uma propriedade para armazenar o valor ou o texto de uma anotação. Uma anotação simples deve expor a interface IValueProvider e a propriedade IValueProvider::Value deve retornar um valor somente leitura que especifica o texto de anotação. Uma anotação mais rica deve expor a interface ITextProvider para fornecer texto mais avançado aos clientes.
• Navegar de um elemento de interface do usuário para uma anotação no elemento depende do tipo de elemento que está sendo anotado, da seguinte maneira:
  • Para células de planilha, implemente o método ISpreadsheetItemProvider::GetAnnotationObjects para se referir à anotação.
  • Para conteúdo textual, implemente o atributo de texto AnnotationObjects na interface ITextRangeProvider para fazer referência à anotação.
• Alguns tipos de anotações não exigem uma implementação completa da interface IAnnotationProvider . Por exemplo, um indicador simples de erro ortográfico pode ser representado fazendo com que a interface ITextRangeProvider retorne um atributo de texto AnnotationTypes de AnnotationType_SpellingError e um valor nulo para o atributo de texto AnnotationObjects .
• Pode ser útil implementar a interface IAnnotationProvider em um elemento de interface do usuário que não está visível. Por exemplo, você pode criar um elemento Automação da Interface do Usuário não visível que implementa IAnnotationProvider para fornecer informações estendidas sobre um erro gramatical.
• 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 de texto AnnotationTypes e uma matriz vazia para o atributo de texto AnnotationObjects .
  • Um intervalo de texto com uma anotação deve retornar uma matriz de um valor inteiro para o atributo de texto AnnotationTypes e uma matriz de uma interface IRawElementProviderSimple para o atributo de texto AnnotationObjects .
  • Um intervalo de texto com várias anotações deve retornar uma matriz de vários valores inteiros para o atributo de texto AnnotationTypes e uma matriz de um número correspondente de interfaces IRawElementProviderSimple para o atributo de texto AnnotationObjects .
  • Um intervalo de texto com anotações variadas, como um intervalo com texto anotado e não anotado, deve retornar a propriedade ReservedMixedAttributeValue para AnnotationTypes e AnnotationObjects. Um cliente que recebe essa resposta pode subdividir o intervalo de texto para localizar onde as anotações começam e terminam.

Membros necessários para IAnnotationProvider

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

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

Tópicos relacionados

Tipos de controle e seus padrões de controle com suporte

Visão Geral de Padrões de Controle de Automação de Interface de Usuário

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