Modèle de contrôle d’annotation
Décrit les instructions et conventions d’implémentation 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.
Un exemple est une bulle de commentaire qui se trouve dans la marge d’un document et 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ôle et leurs modèles de contrôle pris en charge.
Cette rubrique contient les sections suivantes.
- directives et conventions de mise en œuvre
- membres obligatoires pour IAnnotationProvider
- rubriques connexes
Directives et conventions de mise en œuvre
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 différents. 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 revenir de l’annotation à 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 :
- Pour les cellules de feuille de calcul, implémentez la méthode ISpreadsheetItemProvider ::GetAnnotationObjects pour faire référence à l’annotation.
- Pour le contenu textuel, implémentez l’attribut de texte AnnotationObjects sur l’interface ITextRangeProvider pour faire référence à l’annotation.
- Certains types d’annotations ne nécessitent pas d’implémentation complète de l’interface IAnnotationProvider. Par exemple, un indicateur d’erreur orthographique simple peut être représenté par le fait que l’interface ITextRangeProvider retourne un attribut de texte AnnotationTypes de 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 ne 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’un IRawElementProviderSimple interface pour l’attribut de texte AnnotationObjects.
- Une plage de texte avec plusieurs annotations doit retourner un tableau de valeurs entières multiples 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 différentes annotations, comme une plage avec du texte annoté et non annoté, doit retourner la propriété ReservedMixedAttributeValue pour les deux 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 obligatoires pour IAnnotationProvider
Les propriétés suivantes sont requises pour implémenter l’interface IAnnotationProvider.
| Membres obligatoires | Type de membre | Notes |
|---|---|---|
| annotationTypeId | Propriété | Aucun. |
| annotationTypeName | Propriété | Aucun. |
| Author | Propriété | Aucun. |
| dateTime | Propriété | Aucun. |
| cible | Propriété | Aucun. |
Ce modèle de contrôle n’a aucun événement associé.
Rubriques connexes