Modèle de contrôle d’annotation

  • Article

Décrit des instructions et des conventions pour l’implémentation d’IAnnotationProvider, y compris des informations sur les propriétés et les méthodes. Le modèle de contrôle Annotation est utilisé pour exposer les propriétés d’une annotation dans un document.

Par exemple, une bulle de commentaires qui se trouve dans la marge d’un document et qui est connectée à un texte de document ou à une cellule de feuille de calcul.

L’illustration suivante montre un exemple d’annotation. Pour obtenir des exemples de contrôles qui implémentent ce modèle de contrôle, consultez Types de contrôles et leurs modèles de contrôle pris en charge.

capture d’écran montrant un baloon de commentaire dans un document

Cette rubrique contient les sections suivantes.

Conventions et directives d'implémentation

Lors de l’implémentation du modèle de contrôle Annotation , notez les instructions et conventions suivantes :

  • Il existe de nombreux types d’annotations. Le fichier d’en-tête UIAutomationClient.h définit un ensemble de valeurs constantes nommées qui identifient les types d’annotations pris en charge par Microsoft UI Automation. Pour plus d’informations, consultez Identificateurs de type d’annotation.
  • Si vous utilisez AnnotationType_Unknown, vous devez implémenter la propriété IAnnotationProvider::AnnotationTypeName pour permettre aux clients de découvrir le nom du type d’annotation. Vous n’avez pas besoin d’implémenter AnnotationTypeName pour un type d’annotation standard, car UI Automation fournit un nom par défaut, mais vous pouvez l’implémenter si vous devez remplacer le nom par défaut.
  • La propriété IAnnotationProvider::Author est facultative.
  • La propriété IAnnotationProvider::D ateTime est facultative.
  • La propriété IAnnotationProvider::Target est requise, car elle lie une annotation à un élément d’interface utilisateur, ce qui permet à un client de naviguer de l’annotation vers l’élément d’interface utilisateur auquel l’annotation fait référence.
  • Étant donné que les annotations peuvent prendre de nombreuses formes différentes, l’interface IAnnotationProvider ne définit pas de propriété pour stocker la valeur ou le texte d’une annotation. Une annotation simple doit exposer l’interface IValueProvider , et la propriété IValueProvider::Value doit retourner une valeur en lecture seule qui spécifie le texte de l’annotation. Une annotation plus riche doit exposer l’interface ITextProvider pour fournir du texte plus riche aux clients.
  • La navigation d’un élément d’interface utilisateur vers une annotation sur l’élément dépend du type d’élément annoté, comme suit :
  • Certains types d’annotations ne nécessitent pas une implémentation complète de l’interface IAnnotationProvider . Par exemple, un indicateur d’erreur d’orthographe simple peut être représenté en faisant en sorte que l’interface ITextRangeProvider retourne un attribut de texte AnnotationTypesde AnnotationType_SpellingError et une valeur null pour l’attribut de texte AnnotationObjects .
  • Il peut être utile d’implémenter l’interface IAnnotationProvider sur un élément d’interface utilisateur qui n’est pas visible. Par exemple, vous pouvez créer un élément UI Automation non visible qui implémente IAnnotationProvider pour fournir des informations étendues sur une erreur de grammaire.
  • Les annotations dans un contrôle textuel peuvent être complexes si le contrôle contient des commentaires qui se chevauchent. Utilisez les instructions suivantes pour gérer les annotations complexes :
    • Une plage de texte sans annotations doit retourner un tableau vide pour l’attribut de texte AnnotationTypes et un tableau vide pour l’attribut de texte AnnotationObjects .
    • Une plage de texte avec une annotation doit retourner un tableau d’une valeur entière pour l’attribut de texte AnnotationTypes et un tableau d’une interface IRawElementProviderSimple pour l’attribut de texte AnnotationObjects .
    • Une plage de texte avec plusieurs annotations doit retourner un tableau de plusieurs valeurs entières pour l’attribut de texte AnnotationTypes et un tableau d’un nombre correspondant d’interfaces IRawElementProviderSimple pour l’attribut de texte AnnotationObjects .
    • Une plage de texte avec des annotations variables, comme une plage avec du texte annoté et non annoté, doit retourner la propriété ReservedMixedAttributeValue pour AnnotationTypes et AnnotationObjects. Un client recevant cette réponse peut subdiviser la plage de texte pour trouver où les annotations commencent et se terminent.

Membres requis pour IAnnotationProvider

Les propriétés suivantes sont requises pour implémenter l’interface IAnnotationProvider .

Membres nécessaires Type de membre Notes
AnnotationTypeId Propriété Aucun.
AnnotationTypeName Propriété Aucun.
Auteur Propriété Aucun.
DateTime Propriété Aucun.
Cible Propriété Aucun.

 

Ce modèle de contrôle n’est associé aucun événement.

Types de contrôles et leurs modèles de contrôle pris en charge

Vue d'ensemble des modèles de contrôle UI Automation

Vue d’ensemble de l’arborescence UI Automation