Modèles de contrôle Text et TextRange
Décrit les instructions et conventions pour l’implémentation d’ITextProvider, ITextProvider2 et ITextRangeProvider, y compris des informations sur les propriétés et les méthodes. Le modèle de contrôle Texte permet aux applications et aux contrôles d’exposer un modèle objet texte simple, ce qui permet aux clients de récupérer du contenu textuel, des attributs de texte et des objets incorporés à partir de contrôles textuels.
Pour prendre en charge le modèle de contrôle Text , les contrôles implémentent les interfaces ITextProvider et ITextProvider2 . Les types de contrôle qui doivent prendre en charge le modèle de contrôle Texte incluent les types De contrôle Edit et Document , ainsi que tout autre type de contrôle qui permet à l’utilisateur d’entrer du texte ou de sélectionner du texte en lecture seule.
Le modèle de contrôle Texte peut être utilisé avec d’autres modèles de contrôle Microsoft UI Automation pour prendre en charge plusieurs types d’objets incorporés dans le texte, notamment les tables, les liens hypertexte et les boutons de commande.
Les interfaces ITextProvider et ITextProvider2 incluent un certain nombre de méthodes d’acquisition de plages de texte. Une plage de texte est un objet qui représente une étendue contiguë de texte (ou plusieurs étendues de texte disjointes) dans un conteneur de texte. Une méthode ITextProvider acquiert une plage de texte qui représente l’ensemble du document, tandis que d’autres acquièrent des plages de texte qui représentent une partie du document, comme le texte sélectionné, le texte visible ou un objet incorporé dans le texte.
Un objet de plage de texte est représenté par le modèle de contrôle TextRange , qui est implémenté via l’interface ITextRangeProvider . Le modèle de contrôle TextRange fournit des méthodes et des propriétés utilisées pour exposer des informations sur le texte dans la plage, déplacer les points de terminaison de la plage, sélectionner ou désélectionner du texte, faire défiler la plage dans l’affichage, etc.
Pour plus d’informations sur les modèles de contrôle Text et TextRange, consultez UI Automation prise en charge du contenu textuel.
À partir de Windows 8.1 fournisseurs peuvent implémenter l’interface ITextRangeProvider2. Cela permet d’appeler des menus contextuels associés à une plage de texte. Cela prend en charge des scénarios tels que la correction automatique de texte ou la sélection de candidats éditeur de méthode d’entrée (IME).
Cette rubrique contient les sections suivantes.
- Conventions et directives d'implémentation
- Membres requis pour ITextProvider
- Membres requis pour ITextRangeProvider
- Plages de texte de prise en charge
- Interopérabilité avec system Caret
- Rubriques connexes
Conventions et directives d'implémentation
Lorsque vous implémentez le modèle de contrôle Texte , notez les instructions et conventions suivantes :
- Tout contrôle qui active l’accès au texte (par exemple, la saisie de texte ou la sélection de texte en lecture seule) doit prendre en charge le modèle de contrôle Texte .
- Le modèle de contrôle Text peut être utilisé avec n’importe quel élément d’interface utilisateur qui présente du texte, même une étiquette statique sur un contrôle de bouton standard. Toutefois, elle n’est pas obligatoire sur les contrôles de texte statiques qui ne peuvent pas être sélectionnés ou qui n’ont pas de point d’insertion.
- Pour garantir que le texte est entièrement accessible, les contrôles qui implémentent ITextProvider doivent également prendre en charge l’interface IValueProvider . IValueProvider complète ITextProvider en fournissant un moyen par programme de modifier le texte. Il offre également une meilleure compatibilité avec les applications clientes de technologie d’assistance, y compris celles basées sur des technologies héritées telles que Microsoft Active Accessibility. Lorsque les deux modèles de contrôle sont implémentés, l’événement TextChanged (UIA_Text_TextChangedEventId) et l’événement AutomationPropertyChanged (UIA_AutomationPropertyChangedEventId) sont équivalents pour la propriété Value (UIA_ValueValuePropertyId). Les deux événements doivent être pris en charge.
- Le modèle de contrôle Texte ne prend en charge qu’un seul flux de texte et une fenêtre d’affichage par contrôle. Si l’application offre plusieurs vues de document dans des volets, chaque vue (contrôle) doit prendre en charge ITextProvider indépendamment.
- La méthode ITextProvider::GetSelection peut retourner une seule plage de texte représentant le texte actuellement sélectionné. Si un contrôle prend en charge la sélection de plusieurs étendues de texte non incohérentes, la méthode GetSelection doit retourner un tableau qui contient une interface ITextRangeProvider pour chaque étendue de texte sélectionnée.
- Le modèle de contrôle Text représente le point d’insertion sous la forme d’une plage de texte dégénérée (vide). La méthode ITextProvider::GetSelection doit retourner une plage de texte dégénérée lorsque le point d’insertion existe et qu’aucun texte n’est sélectionné. Pour plus d’informations, consultez Interopérabilité avec system Caret.
- La méthode ITextProvider::GetVisibleRanges peut renvoyer une seule plage de texte si une plage de texte contiguë est visible dans la fenêtre d’affichage, ou renvoyer un tableau de plages de texte disjointes représentant plusieurs lignes de texte partiellement visibles.
- La méthode ITextProvider::RangeFromChild doit retourner une plage dégénérée si l’élément enfant ne contient aucun texte. Étant donné qu’un objet incorporé peut inclure du texte, la méthode RangeFromChild peut ne pas toujours renvoyer une plage de texte dégénérée. Pour plus d’informations, consultez Comment UI Automation expose les objets incorporés.
- La méthode ITextProvider::RangeFromPoint effectue des tests d’accès dans la zone de document à l’aide des coordonnées d’écran spécifiées. La plage de texte résultante doit être cohérente avec le point d’insertion ou la sélection résultant d’un clic sur l’emplacement aux coordonnées d’écran spécifiées. Par exemple, si une image réside aux coordonnées d’écran spécifiées, la plage de texte obtenue doit être identique à la plage de texte que la méthode ITextProvider::RangeFromChild acquérirait pour l’image. De même, si une application cliente demande une plage de texte pour l’emplacement au centre du caret système (point d’insertion), la plage de texte résultante doit être la même que l’emplacement de caret système.
- La propriété ITextProvider::D ocumentRange doit toujours fournir une plage de texte qui inclut tout le texte pris en charge par l’implémentation ITextProvider correspondante.
- L’événement UIA_Text_TextChangedEventId doit être déclenché après toute modification de texte, même si la modification n’est pas visible dans la fenêtre d’affichage. Par exemple, le fournisseur doit déclencher l’événement même si l’utilisateur colle exactement le même texte sur le texte sélectionné.
- Le UIA_Text_TextSelectionChangedEventId doit être déclenché chaque fois que la sélection de texte change ou chaque fois que le point d’insertion (caret) se déplace dans le texte.
Lors de l’implémentation du modèle de contrôle TextRange , notez les instructions et conventions suivantes :
- Toutes les méthodes du modèle de contrôle TextRange doivent effectuer des opérations de texte quel que soit l’état de visibilité du texte. La visibilité d’une plage de texte peut toujours être déterminée en interrogeant l’attribut de texte IsHidden (UIA_IsHiddenAttributeId).
- Si possible, un fournisseur doit s’assurer que les modifications de texte, telles que les suppressions, les insertions et les déplacements, sont reflétées dans les objets de plage de texte associés (instances de l’interface ITextRangeProvider ) et déclenchent un événement UIA_Text_TextChangedEventId . Les clients peuvent utiliser l’événement comme indicateur pour confirmer les modifications éditoriales apportées au texte d’un contrôle.
- Tous les objets de plage de texte utilisés par les méthodes ITextRangeProvider::Compare, CompareEndpoints et MoveEndpointByRange doivent être des homologues de la même implémentation du modèle de contrôle Text .
- Bien qu’elle ne soit pas obligatoire, la valeur pRetVal récupérée par la méthode ITextRangeProvider::CompareEndpoints peut indiquer la distance, en caractères (TextUnit_Character), entre les deux points de terminaison. Toutefois, les applications clientes ne doivent pas dépendre de la précision de pRetVal au-delà de sa valeur positive ou négative.
- Les méthodes ITextRangeProvider::ExpandToEnclosingUnit, Move et MoveEndpointByUnit nécessitent un examen attentif de l’unité de texte spécifiée. Pour plus d’informations, consultez Manipulation d’un textrange par unité de texte.
- Pour connaître les exigences d’implémentation relatives aux méthodes ITextRangeProvider::Select, AddToSelection et RemoveFromSelection , consultez Sélection de texte dans une plage de texte.
- Les méthodes ITextRangeProvider::FindText et FindAttribute recherchent une chaîne de texte ou un attribut texte correspondant unique. Ils doivent retourner la valeur NULL si aucune correspondance n’est trouvée.
- La méthode ITextRangeProvider::GetAttributeValue doit retourner l’adresse acquise à partir de la fonction UiaGetReservededAttributeValue ou UiaGetReservedNotSupportedValue si l’attribut associé varie dans la plage, ou si l’attribut n’est pas pris en charge par le contrôle de texte. La spécification du modèle de contrôle TextRange ne permet pas d’ajouter de nouveaux identificateurs d’attribut de texte ni de modifier la façon dont les attributs existants sont définis.
- Si possible, la méthode ITextRangeProvider::GetBoundingRectangles doit retourner un tableau qui contient un rectangle englobant pour chaque ligne de texte entièrement ou partiellement visible dans une plage de texte. Si cela n’est pas possible, le fournisseur peut retourner un tableau qui contient les rectangles englobants de lignes entièrement visibles uniquement ; toutefois, cela limite la capacité d’une application cliente à décrire avec précision la façon dont le texte est présenté à l’écran.
- La méthode ITextRangeProvider::GetChildren doit retourner tous les éléments enfants incorporés dans une plage de texte, mais elle n’a pas besoin de retourner les enfants des éléments enfants. Par exemple, si une plage de texte contient une table qui contient un certain nombre de cellules enfants, la méthode GetChildren peut renvoyer uniquement l’élément table et non les éléments de cellule. Pour des raisons de performances ou d’architecture, un fournisseur peut ne pas être en mesure d’exposer tous les objets incorporés hébergés dans un document dans l’arborescence Automation. Dans ce cas, le fournisseur doit au moins prendre en charge l’énumération d’objets enfants via la méthode GetChildren et, en option, prendre en charge le modèle de contrôle VirtualizedItem pour la prise en charge de la dé virtualisation.
- La méthode ITextRangeProvider::GetEnclosingElement retourne généralement le fournisseur de texte qui fournit la plage de texte. Toutefois, si le fournisseur de texte prend en charge des objets enfants tels que des tables ou des liens hypertexte, l’élément englobant peut être un descendant du fournisseur de texte. L’élément retourné par GetEnclosingElement doit être l’élément le plus proche de la plage de texte donnée. Par exemple, si la plage de texte se trouve dans une cellule d’un tableau, GetEnclosingElement doit retourner la cellule conteneur au lieu de l’élément de tableau.
- La méthode ITextRangeProvider::GetText doit retourner le texte brut dans la plage. Pour plus d’informations, consultez Acquisition de texte à partir d’une plage de texte.
- L’appel de ITextRangeProvider::ScrollIntoView doit aligner le texte dans la fenêtre d’affichage du contrôle de texte, comme spécifié par le paramètre alignToTop . Bien qu’il n’y ait aucune exigence en termes d’alignement horizontal, la plage de texte doit être visible horizontalement et verticalement. Lors de l’évaluation du paramètre alignToTop , un fournisseur doit prendre en compte l’orientation du contrôle de texte et le sens du flux du texte. Par exemple, si alignToTop a la valeur TRUE pour un contrôle de texte orienté verticalement contenant du texte qui circule de droite à gauche, le fournisseur doit aligner la plage de texte sur le côté droit de la fenêtre d’affichage.
- Lorsque vous parcourez un document par TextUnit_Line, si la plage de texte entre dans un tableau incorporé, chaque ligne de texte d’une cellule doit être traitée comme une ligne.
Membres requis pour ITextProvider
Les propriétés et méthodes suivantes sont requises pour implémenter l’interface ITextProvider .
| Membres nécessaires | Type de membre | Notes |
|---|---|---|
| DocumentRange | Propriété | Aucun |
| SupportedTextSelection | Propriété | Aucun |
| GetSelection | Méthode | Aucun |
| GetVisibleRanges | Méthode | Aucun |
| RangeFromChild | Méthode | Aucun |
| RangeFromPoint | Méthode | Aucun |
| UIA_Text_TextChangedEventId | Événement | Aucun |
| UIA_Text_TextSelectionChangedEventId | Événement | Aucun |
Les propriétés et méthodes supplémentaires suivantes sont requises pour implémenter l’interface ITextProvider2 .
| Membres nécessaires | Type de membre | Notes |
|---|---|---|
| GetCaretRange | Méthode | Aucun |
| RangeFromAnnotation | Méthode | Aucun |
Membres requis pour ITextRangeProvider
Les propriétés et méthodes suivantes sont requises pour implémenter l’interface ITextRangeProvider .
| Membres nécessaires | Type de membre | Notes |
|---|---|---|
| AddToSelection | Méthode | Aucun |
| Clone | Méthode | Aucun |
| Comparer | Méthode | Aucun |
| CompareEndpoints | Méthode | Aucun |
| ExpandToEnclosingUnit | Méthode | Aucun |
| FindAttribute | Méthode | Aucun |
| FindText | Méthode | Aucun |
| GetAttributeValue | Méthode | Aucun |
| GetBoundingRectangles | Méthode | Aucun |
| GetChildren | Méthode | Aucun |
| GetEnclosingElement | Méthode | Aucun |
| Gettext | Méthode | Aucun |
| Déplacer | Méthode | Aucun |
| MoveEndpointByUnit | Méthode | Aucun |
| MoveEndpointByRange | Méthode | Aucun |
| Sélectionner | Méthode | Aucun |
| ScrollIntoView | Méthode | Aucun |
Les propriétés et méthodes supplémentaires suivantes sont requises pour implémenter l’interface ITextRangeProvider2 .
| Membres nécessaires | Type de membre | Notes |
|---|---|---|
| ShowContextMenu | Méthode | Consultez la section « Implémentation de ShowContextMenu » |
Le modèle de contrôle TextRange n’a aucun événement associé.
Plages de texte de prise en charge
Cette section décrit comment un fournisseur doit implémenter différentes méthodes des interfaces ITextRangeProvider et ITextRangeProvider2 pour prendre en charge le modèle de contrôle TextRange .
Manipulation d’une plage de texte par unité de texte
L’interface ITextRangeProvider fournit plusieurs méthodes pour manipuler et parcourir des plages de texte dans un contrôle textuel. Les méthodes ITextRangeProvider::Move, MoveEndpointByUnit et ExpandToEnclosingUnit déplacent une plage de texte ou l’un de ses points de terminaison par l’unité de texte spécifiée, comme caractère, mot, paragraphe, etc. Pour plus d’informations, consultez unités de texte UI Automation.
Malgré son nom, la méthode ITextRangeProvider::ExpandToEnclosingUnit n’étend pas nécessairement une plage de texte. Au lieu de cela, il « normalise » une plage de texte en déplaçant les points de terminaison afin que la plage englobe l’unité de texte spécifiée. La plage est développée si elle est plus petite que l’unité spécifiée, ou raccourcie si elle est plus longue que l’unité spécifiée. Il est essentiel que la méthode ExpandToEnclosingUnit normalise toujours les plages de texte de manière cohérente ; sinon, d’autres aspects de la manipulation de plage de texte par unité de texte seraient imprévisibles. Le diagramme suivant montre comment ExpandToEnclosingUnit normalise une plage de texte en déplaçant les points de terminaison de la plage.
Si la plage de texte commence au début d’une unité de texte et se termine au début de, ou avant, la limite d’unité de texte suivante, le point de terminaison est déplacé vers la limite d’unité de texte suivante (voir 1 et 2 dans le diagramme précédent).
Si la plage de texte commence au début d’une unité de texte et se termine à, ou après, la limite d’unité suivante, le point de terminaison de fin reste ou est déplacé vers l’arrière vers la limite d’unité suivante après le point de terminaison de début (voir 3 et 4 dans l’illustration précédente). S’il existe plusieurs limites d’unité de texte entre les points de terminaison de début et de fin, le point de terminaison est déplacé vers l’arrière vers la limite d’unité suivante après le point de terminaison de début, ce qui entraîne une plage de texte d’une longueur d’une unité de texte.
Si la plage de texte commence au milieu de l’unité de texte, le point de terminaison de départ est déplacé vers l’arrière vers le début de l’unité de texte et le point de terminaison est déplacé vers l’avant ou l’arrière, si nécessaire, vers la limite d’unité suivante après le point de terminaison de début (voir 5 à 8 dans le diagramme précédent).
Lorsque la méthode ITextRangeProvider::Move est appelée, le fournisseur normalise la plage de texte par l’unité de texte spécifiée, en utilisant la même logique de normalisation que la méthode ExpandToEnclosingUnit . Ensuite, le fournisseur déplace la plage vers l’arrière ou vers l’avant selon le nombre spécifié d’unités de texte. Lors du déplacement de la plage, le fournisseur doit ignorer les limites des objets incorporés dans le texte. (Toutefois, la limite d’unité elle-même peut être affectée par l’existence d’un objet incorporé). Le diagramme suivant montre comment la méthode Move déplace une plage de texte, unité par unité, sur des objets incorporés et des limites d’unité de texte.
La méthode ITextRangeProvider::MoveEndpointByUnit déplace l’un des points de terminaison vers l’avant ou vers l’arrière par l’unité de texte spécifiée, comme le montre l’illustration suivante.
La méthode ITextRangeProvider::MoveEndpointByRange permet à une application cliente de définir un point de terminaison d’une plage de texte au même emplacement que le point de terminaison spécifié d’une deuxième plage de texte.
Sélection de texte dans une plage de texte
L’interface ITextRangeProvider comprend plusieurs méthodes pour contrôler la sélection de texte dans un contrôle textuel.
La méthode ITextRangeProvider::Select doit sélectionner le texte qui correspond à une plage de texte et supprimer la sélection précédente, le cas échéant, du contrôle de texte. Si Select est appelé sur une plage de texte dégénérée, le fournisseur doit déplacer le point d’insertion vers l’emplacement de la plage de texte sans sélectionner de texte.
Si un contrôle prend en charge la sélection de plusieurs étendues de texte disjointes, les méthodes ITextRangeProvider::AddToSelection et RemoveFromSelection ajoutent des plages de texte à la collection de plages de texte sélectionnées et les suppriment. Si le contrôle ne prend en charge qu’une seule plage de texte sélectionnée à la fois, mais que l’opération de sélection entraîne la sélection de plusieurs plages de texte disjointes, le fournisseur doit renvoyer une erreur de E_INVALIDOPERATION ou doit étendre ou tronquer la sélection actuelle. La propriété ITextProvider::SupportedTextSelection doit indiquer si un contrôle prend en charge la sélection d’une ou de plusieurs étendues de texte, ou aucune.
Si un contrôle textuel prend en charge les insertions de texte, l’appel de ITextRangeProvider::AddToSelection ou RemoveFromSelection sur une plage de texte dégénérée dans le contrôle doit déplacer le point d’insertion, mais ne doit sélectionner aucun texte.
Acquisition de texte à partir d’une plage de texte
La méthode ITextRangeProvider::GetText doit retourner le texte brut d’une plage de texte. Le texte brut doit inclure tous les caractères de contrôle trouvés dans le texte source, tels que les retours chariot et la marque Unicode de gauche à droite (LRM). Le texte brut ne doit pas inclure de balises de balisage telles que du code HTML qui peuvent être présentes dans le texte source. En outre, tous les codes d’échappement dans le texte source doivent être convertis en équivalents en texte brut. Par exemple, « » doit être converti en un simple caractère d’espace.
Si un objet incorporé couvre une plage de texte, le texte brut doit inclure le texte interne de l’objet, mais pas le texte de remplacement (propriété name de l’objet incorporé), car il peut être incohérent avec le texte interne descriptif. Pour plus d’informations, consultez Comment UI Automation expose les objets incorporés.
Implémentation de ShowContextMenu
ITextRangeProvider2::ShowContextMenu doit toujours afficher le menu contextuel au point de fin de début de la plage. Cela doit être équivalent à ce qui se passerait si l’utilisateur appuyait sur la touche de menu contextuel ou MAJ + F10 avec le point d’insertion au début de la plage.
Si l’affichage du menu contextuel entraîne généralement le déplacement du point d’insertion vers un emplacement donné, il doit le faire pour appeler par programmation ShowContextMenu pour UI Automation prise en charge.
Interopérabilité avec system Caret
La prise en charge correcte du point d’insertion est essentielle pour de nombreuses applications clientes, y compris celles qui ne sont pas basées sur UI Automation. Dans le modèle de contrôle Texte , le point d’insertion est représenté par une plage de texte dégénérée (vide) à la position du caret système. Lorsque le point d’insertion se déplace, un contrôle doit déclencher l’événement TextSelectionChanged (UIA_Text_TextSelectionChangedEventId). Certaines applications clientes dépendent de cet événement pour surveiller l’emplacement du point d’insertion et pour suivre la sélection de texte.
Lorsqu’un contrôle contient du texte sélectionné, la conception actuelle du modèle de contrôle Texte ne permet pas d’associer directement l’emplacement du point d’insertion à une plage de texte particulière. Le fournisseur doit suivre la sélection de texte et définir l’emplacement du point d’insertion de manière appropriée. Étant donné que la sélection de texte s’effectue généralement en déplaçant le point d’insertion tout en maintenant la touche Maj ou Ctrl enfoncée, ou les deux, un fournisseur peut suivre la sélection du texte en vérifiant l’état de ces touches chaque fois que la sélection change.
Étant donné que l’infrastructure d’accessibilité fournit une prise en charge intégrée pour le caret système, mais pas pour un caret personnalisé, les contrôles textuels doivent utiliser le caret système chaque fois que possible. Les contrôles qui utilisent un caret personnalisé peuvent garantir que le caret est accessible en créant un caret système qui a les mêmes dimensions que le caret personnalisé et en positionnant le caret système au même emplacement dans l’interface utilisateur du contrôle que le caret personnalisé, c’est-à-dire au point d’insertion. En guise d’alternative, un contrôle qui utilise un caret personnalisé peut implémenter un fournisseur d’accessibilité Active Microsoft pour OBJID_CARET afin de fournir des informations d’accessibilité directement pour votre caret personnalisé.
Pour plus d’informations sur le système caret, consultez Carets.
Pour tester si votre contrôle expose correctement l’emplacement de la caret système, utilisez les outils Inspect et Accessible Event Watcher .
Les coordonnées d’écran du centre de l’image bitmap du système doivent toujours correspondre à l’emplacement du point d’insertion. De cette façon, un client peut utiliser les coordonnées de l’écran de caret dans un appel à ITextProvider::RangeFromPoint pour récupérer une plage de texte qui représente avec précision l’emplacement du point d’insertion.
Rubriques connexes