Unités de texte UI Automation

  • Article

Cette rubrique décrit les unités de texte prises en charge par le modèle de contrôle Microsoft UI Automation TextRange. Les fournisseurs et les clients UI Automation utilisent des unités de texte pour spécifier la quantité de déplacement ou de modification de la taille d’une plage de texte.

Éléments d’API des unités de texte

L’API UI Automation inclut les méthodes suivantes qui nécessitent une unité de texte à spécifier :

L’énumération TextUnit définit les unités de texte prises en charge par les plages de texte UI Automation. Pour spécifier l’unité de texte, un membre de l’énumération TextUnit est spécifié dans un appel à une méthode ITextRangeProvider ou IUIAutomationTextRange. Les unités de texte, de la plus petite à la plus grande, sont les suivantes :

Si un contrôle textuel particulier ne prend pas en charge l’unité de texte spécifiée, le fournisseur doit répondre en substituant l’unité de texte immédiatement supérieure qui est prise en charge par le contrôle. Par exemple, si TextUnit_Paragraph est spécifié, mais n’est pas pris en charge, la méthode peut remplacer TextUnit_Page ou TextUnit_Document.

Les caractéristiques linguistiques du texte source peuvent rendre difficile pour un fournisseur de déterminer les délimitations de textes en fonction de l’unité de texte spécifiée. Pour obtenir de l’aide sur la détermination des délimitations de textes, un fournisseur peut utiliser des fonctions API Uniscribe telles que ScriptBreak. Pour plus d’informations, consultez Uniscribe sur le site Web MSDN.

Inclusivité des points de terminaison

Un point de terminaison d’unité de texte peut servir à la fois de point de terminaison de Début et de Fin pour les plages de texte adjacentes du même type. Si la fin d’une unité de texte est également le début d’une autre, la plage contenant le point de terminaison de Fin ne partage pas d’attributs ou d’objets de la plage adjacente contenant le point de terminaison de Début.

Par exemple, un flux de texte, « Hello world », contient deux unités de mots avec différents attributs de poids de police (normal et gras). Dans ce cas, le point de terminaison de Fin de l’unité de mots « Hello »et le point de terminaison de Début de l’unité de mots « world » sont les mêmes, ce qui entraîne les résultats suivants :

  • La plage de « Hello » ne partage pas l’attribut gras de l’unité de mots « world » et ne retourne pas la valeur d’attribut mixte pour l’attribut de texte de poids de police.
  • La plage de « world » a un poids de police unique (gras) et ne partage pas le poids de police de l’unité de mots précédente « Hello ».

Voici un autre exemple où un flux de texte contient deux unités de mot, dont l’un est un lien : [Foo]() Bar. Dans ce cas, le point de terminaison de Fin de l’unité de mots [Foo]() et le point de terminaison de Début de l’unité de mots « Bar » sont les mêmes, ce qui entraîne les résultats suivants :

  • Le lien appartient à la plage de texte contenant « Foo ».
  • Le lien est un enfant de la plage de texte « Foo » et est délimité par l’ITextProvider.
  • La plage de texte « Bar » n’a pas d’enfants et est délimitée par l’ITextProvider.

Notes supplémentaires :

Une plage dégénérée (vide) à la délimitation d’une unité de texte avec une plage de texte du même type prend les propriétés de l’unité de texte immédiatement adjacente.

Appeler IUIAutomationTextRange::ExpandToEnclosingUnit sur une plage dégénérée à une délimitation d’une unité de texte avec une plage de texte du même type étend la plage dégénérée à l’unité de texte suivante.

Descriptions des unités de texte

Cette section décrit chacune des unités de texte prises en charge par UI Automation.

Caractère

TextUnit_Character est une unité linguistique de texte qui représente un caractère unique. La définition linguistique d’un caractère varie selon la langue. Pour l’anglais américain, un caractère est généralement délimité par un espace ou un autre caractère, tel qu’un signe de ponctuation, un nombre ou une lettre.

Les caractères de contrôle tels que les retours chariot et la marque de gauche à droite (LTM) Unicode ne doivent pas être considérés comme des caractères, mais peuvent être inclus dans une plage de texte normalisée en fonction de l’unité de texte de caractères.

Les signes de ponctuation et les caractères de séparation de mots tels que les espaces doivent être considérés comme des caractères.

Format

TextUnit_Format est utilisé pour positionner la délimitation d’une plage de texte en fonction des attributs de mise en forme du texte. Par exemple, si une plage de texte est actuellement positionnée sur un caractère unique d’un mot, spécifier TextUnit_Format dans un appel à IUIAutomationTextRange::ExpandToEnclosingUnit étend la plage de texte pour inclure tout le texte qui partage tous les mêmes attributs que le caractère unique. La plage de texte résultante peut ou non inclure l’intégralité du mot. En outre, utiliser l’unité de texte de format n’étend pas une plage de texte sur la délimitation d’un objet incorporé tel qu’une image ou un lien hypertexte.

Contrairement aux autres unités de texte, qui incluent les unités de texte plus petites qu’elles-mêmes, TextUnit_Format peut être plus petite ou plus grande que les autres unités. Par exemple, si un document entier partage les mêmes attributs de texte et ne contient aucun objet incorporé,étendre une plage de texte par TextUnit_Format créerait une nouvelle plage qui englobe l’ensemble du document, tout comme étendre la plage de texte par TextUnit_Word créerait une plage plus petite.

Word

TextUnit_Word est une unité linguistique de texte qui représente un mot entier unique. La définition linguistique d’un mot varie selon la langue. Pour l’anglais américain, les mots sont généralement délimités par des espaces ou des caractères de ponctuation.

Lorsque TextUnit_Word est utilisé pour définir la délimitation d’une plage de texte, la plage de texte résultante doit inclure tous les caractères de séparation de mot présents à la fin du mot, mais avant le début du mot suivant.

Line

TextUnit_Line est une unité de texte qui représente une seule ligne de texte telle qu’elle est présentée dans la fenêtre d’affichage du contrôle. Lorsque vous utilisez TextUnit_Line pour définir la délimitation d’une plage de texte, un fournisseur doit définir la délimitation immédiatement après le point où un caractère de contrôle interrompt la ligne ou où la fenêtre d’affichage du contrôle inclut le texte dans un wrapper sur une nouvelle ligne. La délimitation doit être définie à l’endroit où commence une nouvelle ligne.

Paragraphe

TextUnit_Paragraph est une unité linguistique de texte qui représente un paragraphe complet. Un paragraphe doit commencer juste avant le premier caractère d’un paragraphe et doit généralement se terminer juste après le dernier caractère. Toutes les lignes vides qui suivent un paragraphe doivent être fusionnées dans le paragraphe, sauf indication contraire dans la source du texte. En règle générale, la délimitation de fin d’un paragraphe marque également la délimitation de fin d’une unité de texte TextUnit_Line.

Page

TextUnit_Page représente une page de texte complète d’un document. Les délimitations d’une page doivent être définies aux points immédiats où une page démarre et se termine.

Document

TextUnit_Document représente l’intégralité du contenu d’un document, tel qu’il est pris en charge par le modèle de contrôle Texte. Aucun texte ne doit exister en dehors d’une plage de texte contenant un document. Tous les objets insérés dans un document, tels que les notes d’annotation qui franchissent une délimitation de page, doivent être traités comme des objets incorporés du document et non dans le contenu du texte du document.

Autres plages potentielles

La spécification actuelle du modèle de contrôle TextRange ne permet ni d’ajouter de nouvelles valeurs d’unités de texte à l’énumération TextUnit, ni de redéfinir les valeurs d’unités de texte existantes. Pour exposer d’autres plages potentielles, telles que des en-têtes et des annotations, un fournisseur doit exposer ces plages en tant qu’objets incorporés avec une plage de texte associée. De cette façon, vous pouvez également ajouter la prise en charge des modèles de contrôle appropriés. Cette solution est plus flexible et extensible que la définition de nouvelles unités de texte.

Référence

TextPatternRangeEndpoint

ITextRangeProvider::GetChildren

Conceptuel

Prise en charge d’UI Automation pour le contenu textuel

Utilisation des contrôles textuels