Utilisation de IUIAutomationTextRange pour accéder et manipuler une plage de texte
Cette rubrique explique comment utiliser les propriétés et les méthodes de l’interface IUIAutomationTextRange pour accéder et manipuler le contenu textuel d’un contrôle textuel.
Qu’est-ce qu’une plage de texte ?
Le modèle objet texte Microsoft UI Automation est basé sur le concept de la plage de texte. Une plage de texte est un objet qui expose l’interface IUIAutomationTextRange et représente une étendue de texte contiguë dans un contrôle textuel. Chaque plage de texte a à la fois un point de terminaison de départ et un point de terminaison, et tout le contenu textuel entre les deux points de terminaison est considéré comme faisant partie de la plage. Une plage de texte dont le point de terminaison de début et le point de terminaison se trouvent au même emplacement est appelée plage de texte dégénérée (ou vide). Une plage de texte dégénérée est utilisée pour marquer un emplacement spécifique dans le texte d’un contrôle, comme l’emplacement du point d’insertion de texte.
Acquisition d’objets de plage de texte
Les applications clientes acquièrent des objets de plage de texte à l’aide des propriétés et des méthodes de l’interface IUIAutomationTextPattern . La propriété IUIAutomationTextRangePattern::D ocumentRange récupère une plage de texte qui représente l’intégralité du contenu textuel d’un contrôle textuel, tandis que d’autres méthodes acquièrent des plages de texte qui représentent une partie du contenu, comme le texte sélectionné, le texte visible ou un objet incorporé dans le texte.
Les méthodes IUIAutomationTextRangePattern::GetVisibleRanges et GetSelection peuvent récupérer des tableaux d’objets de plage de texte. Si un contrôle est partiellement masqué par une fenêtre ou un autre objet qui se chevauche, GetVisibleRanges retourne un tableau contenant un objet de plage de texte pour chaque ligne de texte partiellement visible. De même, si un contrôle textuel prend en charge la sélection de plusieurs étendues de texte disjointes, GetSelection retourne un tableau qui contient un objet de plage de texte pour chaque étendue sélectionnée.
La méthode IUIAutomationTextRangePattern::RangeFromChild permet à une application cliente de récupérer une plage de texte qui entoure un objet incorporé dans le contenu textuel. Le client spécifie le pointeur d’interface IUIAutomationElement d’un objet incorporé, tel qu’une image, une table ou un lien hypertexte, et la méthode retourne une plage de texte qui entoure l’objet. Toutefois, si aucun texte n’est associé à l’objet incorporé, la méthode retourne une plage de texte dégénérée.
Une application cliente peut utiliser la méthode IUIAutomationTextRangePattern::RangeFromPoint pour récupérer une plage de texte pour le texte visible ou l’objet incorporé qui est le plus proche des coordonnées d’écran spécifiées.
Sélection de texte dans une plage de texte
L’interface IUIAutomationTextRange comprend un certain nombre de méthodes qui permettent à une application cliente de contrôler la sélection de texte dans un contrôle textuel.
Les applications clientes peuvent utiliser la méthode IUIAutomationTextRange::Select pour sélectionner le texte qui correspond à une plage de texte et pour supprimer la sélection précédente, le cas échéant, du contrôle de texte. L’appel Sélectionner avec une plage de texte dégénérée déplace 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, un client peut utiliser les méthodes IUIAutomationTextRange::AddToSelection et RemoveFromSelection pour ajouter des plages de texte à la collection de plages de texte sélectionnées et les supprimer. 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, la méthode retourne une erreur E_INVALIDOPERATION ou étend ou tronque la sélection actuelle. Une application cliente peut découvrir si un contrôle prend en charge la sélection d’une ou de plusieurs étendues de texte, ou aucune du tout, en vérifiant la propriété IUIAutomationTextPattern::SupportedTextSelection .
Si un contrôle textuel prend en charge les insertions de texte, l’appel de IUIAutomationTextRange::AddToSelection ou RemoveFromSelection sur une plage de texte dégénérée dans le contrôle déplace le point d’insertion, mais ne sélectionne aucun texte.
Récupération de texte à partir d’une plage de texte
Les applications clientes peuvent utiliser la méthode IUIAutomationTextRange::GetText pour récupérer le texte brut d’une plage de texte. Le texte brut inclut 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 n’inclut pas 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 sont convertis en équivalents en texte brut. Par exemple, « » est converti en un simple caractère d’espace.
Si un objet incorporé couvre une plage de texte, le texte brut inclut le texte interne de l’objet, mais pas le texte de remplacement (propriété name de l’objet incorporé). Pour plus d’informations, consultez Comment UI Automation expose les objets incorporés.
La méthode IUIAutomationTextRange::FindText recherche une chaîne particulière dans une plage de texte et, si elle est trouvée, retourne une nouvelle plage de texte qui englobe la chaîne.
Récupération d’attributs de texte à partir d’une plage de texte
Les attributs de texte déterminent le style de mise en forme du texte dans un contrôle textuel et incluent des éléments tels que la couleur de premier plan, le style de puce, la taille de police, etc. UI Automation prend en charge un certain nombre d’attributs de texte et définit un identificateur pour chaque attribut pris en charge. Une application cliente peut interroger une plage de texte pour obtenir la valeur d’un attribut de texte particulier en spécifiant un identificateur d’attribut dans un appel à la méthode IUIAutomationTextRange::GetAttributeValue , ainsi qu’un pointeur vers une structure VARIANT qui reçoit la valeur de l’attribut. Pour plus d’informations sur chaque attribut de texte pris en charge par UI Automation, consultez Identificateurs d’attribut de texte.
La valeur récupérée par GetAttributeValue représente la valeur de l’attribut sur l’ensemble de la plage de texte. Si tout le texte de la plage partage la même valeur pour l’attribut spécifié, cette valeur est retournée par GetAttributeValue. Toutefois, si la valeur de l’attribut varie d’une plage de texte à l’autre, GetAttributeValue retourne un pointeur IUnknown vers un objet de jeton statique appelé objet ReservedMixedAttribute . Pour déterminer si la valeur d’un attribut varie d’une plage de texte, une application cliente doit comparer les résultats de GetAttributeValue à l’objet ReservedMixedAttribute récupéré à partir de la propriété IUIAutomation::ReservedMixedAttributeValue .
Un contrôle textuel n’est pas nécessaire pour prendre en charge tous les attributs de texte UI Automation. Si un client appelle la méthode IUIAutomationTextRange::GetAttributeValue et transmet l’identificateur d’un attribut non pris en charge, la méthode retourne un pointeur IUnknown vers un objet de jeton statique appelé objet ReservedNotSupported . Pour déterminer si un attribut particulier est pris en charge, une application cliente doit comparer les résultats de GetAttributeValue à l’objet ReservedNotSupported récupéré à partir de la propriété IUIAutomation::ReservedNotSupportedValue .
Les applications clientes peuvent utiliser la méthode IUIAutomationTextRange::FindAttribute pour rechercher du texte qui a un attribut de texte particulier dans une plage de texte. Si elle est trouvée, la méthode retourne une nouvelle plage de texte qui englobe le texte correspondant. Notez que FindAttribute renvoie une plage de texte pour le texte correspondant, même si le texte n’est pas visible.
Récupération d’objets incorporés à partir d’une plage de texte
Une plage de texte peut inclure des objets incorporés tels que des tableaux, des images, des liens hypertexte, etc. Une application cliente peut récupérer une collection de tous les objets incorporés dans une plage en appelant la méthode IUIAutomationTextRange::GetChildren . Les objets incorporés qui chevauchent la plage, mais qui ne sont pas entièrement enfermés par celle-ci, sont également inclus dans la collection. Si la plage ne contient aucun objet incorporé, GetChildren récupère une collection vide.
Bien qu’elle dépende du fournisseur du contrôle textuel, la méthode GetChildren ne retourne généralement aucun enfant des éléments incorporés. Par exemple, si une plage de texte contient une table qui contient un certain nombre de cellules enfants, la méthode GetChildren retourne généralement uniquement l’élément table et non les éléments de cellule.
Pour des raisons de performances ou d’architecture, GetChildren peut ne pas être en mesure de récupérer des objets IUIAutomationElement pour tous les objets incorporés dans une plage de texte. Au lieu de cela, le fournisseur peut retourner une collection qui inclut des éléments virtualisés. Pour plus d’informations, consultez Utilisation d’éléments virtualisés.
Manipulation d’une plage de texte
L’interface IUIAutomationTextRange fournit plusieurs méthodes pour manipuler et parcourir des plages de texte dans un contrôle textuel. Les méthodes IUIAutomationTextRange::Move, MoveEndpointByUnit et ExpandToEnclosingUnit déplacent une plage de texte ou l’un de ses points de terminaison en fonction de l’unité de texte spécifiée, par exemple caractère, mot, paragraphe, etc. Pour plus d’informations, consultez unités de texte UI Automation.
Malgré son nom, la méthode 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 exactement 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. 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 l’illustration précédente).
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 d’une 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 vers 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 l’illustration précédente).
Lorsque la méthode IUIAutomationTextRange::Move est appelée, le fournisseur normalise la plage de texte par l’unité de texte spécifiée. 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 ignore 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 IUIAutomationTextRange::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. L’illustration suivante montre comment un point de terminaison progresse.
La méthode IUIAutomationTextRange::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.
Défilement d’une plage de texte dans l’affichage
La méthode IUIAutomationTextRange::ScrollIntoView fait défiler une plage de texte afin que le texte soit visible dans la fenêtre d’affichage du contrôle textuel. Lors de l’appel de ScrollIntoView, un client peut spécifier si le texte doit être aligné sur le haut ou le bas de la fenêtre d’affichage.
Récupération de l’élément englobant d’une plage de texte
Une application cliente peut utiliser la méthode IUIAutomationTextRange::GetEnclosingElement pour récupérer le pointeur d’interface IUIAutomation de l’élément le plus interne qui entoure une plage de texte. L’élément englobant est généralement le fournisseur de texte qui fournit la plage de texte. Toutefois, si le fournisseur de texte prend en charge des éléments enfants tels que des tables ou des liens hypertexte, l’élément englobant peut être un descendant du fournisseur de texte.
Comparaison et clonage de plages de texte
L’interface IUIAutomationTextRange comprend deux méthodes pour comparer des plages de texte. La méthode IUIAutomationTextRange::Compare compare les points de terminaison de début et de fin de deux plages de texte et retourne TRUE si les deux points de terminaison sont identiques. La méthode IUIAutomationTextRange::CompareEndpoints compare le point de début ou le point de terminaison des deux plages. La valeur de retour est zéro si les points de terminaison sont les mêmes, ou une valeur positive ou négative qui indique les positions relatives des deux points de terminaison.
Les applications clientes peuvent utiliser la méthode IUIAutomationTextRange::Clone pour créer une copie exacte de la plage de texte. La nouvelle plage de texte peut être manipulée indépendamment de la plage de texte d’origine.
Récupération des annotations
Une plage de texte peut inclure des annotations si le contrôle textuel les prend en charge. 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 UI Automation. Pour plus d’informations, consultez Identificateurs de type d’annotation.
Certains types d’annotations sont représentés par un élément Automation qui prend en charge le modèle de contrôle Annotation (interface IUIAutomationAnnotationPattern ). D’autres types d’annotations sont exposés via le modèle de contrôle TextRange . Par exemple, un fournisseur peut exposer un indicateur d’erreur d’orthographe simple en faisant en sorte que la méthode IUIAutomationTextRange::GetAttributeValue retourne un attribut de texte AnnotationTypes de AnnotationType_SpellingError et une valeur null pour l’attribut texte AnnotationObjects .
Récupération des types d’annotations à partir d’une plage de texte
Vous pouvez récupérer une liste des types d’annotations présents dans une plage de texte à l’aide de la méthode IUIAutomationTextRange::GetAttributeValue . Lors de l’appel de la méthode, spécifiez un ID d’attribut de texte de UIA_AnnotationTypesAttributeId et un pointeur vers un paramètre de type VARIANT. Lorsque la méthode retourne, le paramètre VARIANT contient une liste d’identificateurs de type d’annotation, un pour chaque type d’annotation dans la plage de texte. Pour plus d’informations, consultez Identificateurs de type d’annotation.
Récupération de toutes les annotations d’une plage de texte
Pour récupérer les annotations d’une plage de texte, appelez la méthode IUIAutomationTextRange::GetAttributeValue , en spécifiant un ID d’attribut de texte de UIA_AnnotationObjectsAttributeId et un pointeur vers un paramètre de type VARIANT. Lorsque la méthode retourne, le paramètre VARIANT contient une interface IUIAutomationElementArray qui représente un tableau d’éléments Automation, un pour chaque annotation dans la plage de texte. La propriété IUIAutomationElementArray::Length indique le nombre d’éléments dans le tableau, et la méthode IUIAutomationElementArray::GetElement récupère l’interface IUIAutomationElement pour un élément particulier.
Récupération d’informations sur une annotation particulière
Pour récupérer des informations sur une annotation particulière, récupérez d’abord l’interface IUIAutomationElement pour l’élément d’annotation, comme décrit dans la section précédente. Ensuite, récupérez l’interface IUIAutomationAnnotationPattern pour l’annotation en appelant la méthode IUIAutomationElement::GetCurrentPatternAs avec un ID de modèle de contrôle de UIA_AnnotationPatternId, un identificateur d’interface de IID_IUIAutomationAnnotationPattern et l’adresse d’une variable qui reçoit le pointeur IUIAutomationAnnotation pour l’annotation . Interrogez les propriétés de l’interface IUIAutomationAnnotation pour récupérer le nom et l’ID de type d’annotation, le nom de l’auteur de l’annotation, la date et l’heure de l’annotation et l’interface IUIAutomationElement pour l’élément annoté.
Récupération du texte cible d’annotation
En règle générale, une annotation s’applique à un sous-ensemble du texte d’une plage de texte. Après avoir récupéré l’interface IUIAutomationElement pour une annotation, vous pouvez passer l’interface à la méthode IUIAutomationTextRange2::RangeFromAnnotation pour récupérer une plage de texte qui contient le texte qui est la cible de l’annotation.
Récupération de styles visuels
Un fournisseur implémente le modèle de contrôle Styles pour décrire un élément d’interface utilisateur qui a un style, une couleur de remplissage, un modèle de remplissage ou une forme spécifique. Cela est particulièrement utile lors de la description d’éléments dans un document, qui ont fréquemment de tels styles. Des styles comme celui-ci contiennent souvent des informations utiles pour les clients handicapés; par exemple, les styles peuvent décrire une chaîne donnée comme titre d’un document, ou un objet d’organigramme donné comme un diamant ou un cercle.
Vous pouvez utiliser la méthode IUIAutomationTextRange::GetAttributeValue pour récupérer les noms et les identificateurs des styles visuels utilisés dans une plage de texte. Utilisez l’attribut texte UIA_StyleNameAttributeId pour récupérer les noms de style et UIA_StyleIdAttributeId pour récupérer les identificateurs de style.
Un contrôle textuel qui prend en charge les styles visuels peut implémenter le modèle de contrôle Styles pour permettre aux clients d’accéder aux informations sur un style visuel utilisé par le contrôle. Les clients accèdent au modèle de contrôle Styles via l’interface IUIAutomationStylesPattern . Vous pouvez récupérer cette interface en appelant la méthode IUIAutomationElement::GetCurrentPattern ou GetCurrentPatternAs , en spécifiant UIA_StylesPatternId comme identificateur de modèle de contrôle.
L’interface IUIAutomationStylesPattern comprend des propriétés et des méthodes qui fournissent les informations suivantes sur un style visuel :
- Nom du style visuel, par exemple « Normal » ou « Titre 1 ».
- Identificateur du style visuel. Pour plus d’informations, consultez Identificateurs de style.
- Couleur utilisée pour remplir le contrôle textuel.
- Couleur du motif utilisé pour remplir le contrôle textuel.
- Forme du contrôle textuel.
- Propriétés étendues ; c’est-à-dire une liste de noms et de valeurs de style spécifiques au contrôle.
Appel de menus contextuels à partir de plages de texte
À compter de Windows 8.1, les plages de texte peuvent prendre en charge l’interface IUIAutomationTextRange2. Cette interface prend en charge la méthode ShowContextMenu . Vous pouvez appeler cette méthode pour appeler n’importe quel menu contextuel associé à une plage de texte. Le scénario pour cela est la correction automatique des plages de texte ou la sélection de candidats IME. Dans ce cas, un menu contextuel qui prend en charge l’interaction utilisateur s’affiche.
Rubriques connexes