Vue d'ensemble de TextPattern et des objets incorporés

Article
08/10/2011

Remarque
Cette documentation s'adresse aux développeurs .NET Framework qui veulent utiliser les classes UI Automation managées définies dans l'espace de noms System.Windows.Automation.Pour obtenir les informations les plus récentes sur UI Automation, consultez API Windows Automation : UI Automation (page éventuellement en anglais).

Cette vue d'ensemble décrit comment Microsoft UI Automation expose des objets incorporés ou des éléments enfants dans un document texte ou un conteneur.

Dans UI Automation, un objet incorporé est un élément qui a des limites non textuelles ; par exemple, une image, un lien hypertexte, une table ou un type de document tel qu'une feuille de calcul Microsoft Excel ou un fichier Microsoft Windows Media. Cette notion est différente de la définition standard, où un élément est créé dans une application et incorporé, ou lié, dans une autre. La modification de l'objet dans son application d'origine est sans importance dans le contexte UI Automation.

Cette rubrique comprend les sections suivantes.

Objets incorporés et arborescence UI Automation
Exposition d'objets incorporés à l'aide de TextPattern et de TextPatternRange
Scénarios courants
Rubriques connexes

Objets incorporés et arborescence UI Automation

Les objets incorporés sont traités comme des éléments individuels de l'affichage de contrôle de l'arborescence UI Automation. Ils sont exposés en tant qu'enfants du conteneur de texte afin de pouvoir être accédés via le même modèle que les autres contrôles dans UI Automation.

Exemple d'un conteneur de texte avec des objets incorporés table, image et lien hypertexte

Table imbriquée avec une image dans un conteneur de texte

Exemple de l'affichage du contenu pour une partie du conteneur de texte précédent

Vue Contenu pour l'exemple précédent

Exposition d'objets incorporés à l'aide de TextPattern et de TextPatternRange

Utilisés conjointement, la classe du TextPattern modèle de contrôle et la classe TextPatternRange exposent des méthodes et des propriétés qui facilitent la navigation et l'interrogation des objets incorporés.

Le contenu textuel (ou texte) d'un conteneur de texte et d'un objet incorporé, tel qu'un lien hypertexte ou qu'une cellule de tableau, est exposé en tant que flux de texte unique et continu dans l'affichage de contrôle et l'affichage du contenu de l'arborescence UI Automation ; le contour des objets est ignoré. Si un client UI Automation récupère du texte à des fins de récitation, interprétation, ou analyse de quelque façon que ce soit, vous devrez vérifier les cas spéciaux de la plage de texte, tels qu'un tableau avec du contenu textuel ou d'autres objets incorporés. Vous pouvez le faire en appelant GetChildren pour obtenir un AutomationElement pour chaque objet incorporé, puis RangeFromChild pour obtenir une plage de texte pour chaque élément. Cette action se répète jusqu'à ce que tout le contenu textuel ait été récupéré.

Exemple d'un flux de texte avec des objets incorporés et leurs amplitudes

Plages de texte sur lesquelles s'étendent des objets imbriqués.

Lorsqu'il est nécessaire de parcourir le contenu d'une plage de texte, il faut effectuer une série d'étapes en arrière-plan pour assurer la bonne exécution de la méthode Move.

La plage de texte est normalisée : elle est réduite en une plage dégénérée au niveau du point de terminaison Start, rendant le point de terminaison End superflu. Cette étape est nécessaire pour supprimer toute ambiguïté dans des situations où une plage de texte couvre les limites d'une TextUnit. Par exemple, « {L'U}RL https://www.microsoft.com/france est incorporée dans le texte », où « { » et « } » sont les points de terminaison de la plage de texte.
La plage obtenue est déplacée vers l'arrière de la DocumentRange au début de la limite de TextUnit demandée.
La plage est avancée ou reculée dans DocumentRange du nombre demandé de limites TextUnit.
La plage est ensuite étendue à partir d'une plage à l'état dégénéré en déplaçant le point de terminaison End d'une limite de TextUnit demandée.

Exemples de la manière dont est ajustée une plage de texte pour Move() et ExpandToEnclosingUnit()

Ajustements de plage par Move & ExpandToEnclosingUnit

Scénarios courants

Les sections suivantes présentent les exemples de scénarios les plus courants qui impliquent des objets incorporés.

Légende des exemples :

{ = Start

} = End

Hyperlink

Exemple 1 - Plage de texte contenant un lien hypertexte textuel incorporé

{L'URL est incorporée dans le texte}.

Méthode appelée	Résultat
GetText	Retourne la chaîne « L'URL https://www.microsoft.com est incorporée dans le texte ».
GetEnclosingElement	Retourne le AutomationElement le plus profond qui englobe la plage de texte ; dans ce cas, il s'agit de l'AutomationElement qui représente le fournisseur de texte lui-même.
GetChildren	Retourne un AutomationElement représentant le contrôle hypertexte.
RangeFromChild où AutomationElement est l'objet retourné par la méthode GetChildren précédente.	Retourne la plage qui représente « https://www.microsoft.com ».

Exemple 2 - Plage de texte couvrant partiellement un lien hypertexte textuel incorporé

L'URL http://{ } est incorporée dans le texte.

Méthode appelée	Résultat
GetText	Retourne la chaîne « www ».
GetEnclosingElement	Retourne le AutomationElement le plus profond qui englobe la plage de texte ; dans ce cas, il s'agit du contrôle hypertexte.
GetChildren	Retourne null étant donné que la plage de texte ne couvre pas entièrement la chaîne d'URL.

Exemple 3 - Plage de texte couvrant partiellement le contenu d'un conteneur de texte. Le conteneur de texte a un lien hypertexte textuel incorporé qui ne fait pas partie de la plage de texte.

{L'URL} est incorporée dans le texte.

Méthode appelée	Résultat
GetText	Retourne la chaîne « L'URL ».
GetEnclosingElement	Retourne le AutomationElement le plus profond qui englobe la plage de texte ; dans ce cas, il s'agit de l'AutomationElement qui représente le fournisseur de texte lui-même.
Move avec les paramètres de (TextUnit.Word, 1).	Déplace la plage de texte vers « http » car le texte du lien hypertexte est composé de mots individuels. Dans ce cas, le lien hypertexte n'est pas traité comme un objet unique. L'URL {http} est incorporée dans le texte.

GetText

Retourne la chaîne « L'URL ».

GetEnclosingElement

Retourne le AutomationElement le plus profond qui englobe la plage de texte ; dans ce cas, il s'agit de l'AutomationElement qui représente le fournisseur de texte lui-même.

Move avec les paramètres de (TextUnit.Word, 1).

Déplace la plage de texte vers « http » car le texte du lien hypertexte est composé de mots individuels. Dans ce cas, le lien hypertexte n'est pas traité comme un objet unique.

L'URL {http} est incorporée dans le texte.

Image

Exemple 1 - Plage de texte contenant une image incorporée

{L'image Exemple d'image incorporée est incorporée dans le texte}.

Méthode appelée	Résultat
GetText	Retourne la chaîne « L' est incorporée dans le texte ». Tout le texte alternatif associé à l'image n'est pas censé être inclus dans le flux de texte.
GetEnclosingElement	Retourne le AutomationElement le plus profond qui englobe la plage de texte ; dans ce cas, il s'agit de l'AutomationElement qui représente le fournisseur de texte lui-même.
GetChildren	Retourne un AutomationElement représentant le contrôle image.
RangeFromChild où AutomationElement est l'objet retourné par la méthode GetChildren précédente.	Retourne la plage dégénérée qui représente « ».

Exemple 2 - Plage de texte couvrant partiellement le contenu d'un conteneur de texte. Le conteneur de texte comporte une image incorporée qui ne fait pas partie de la plage de texte.

{L'image} Exemple d'image incorporée est incorporée dans le texte.

Méthode appelée	Résultat
GetText	Retourne la chaîne « L'image ».
GetEnclosingElement	Retourne le AutomationElement le plus profond qui englobe la plage de texte ; dans ce cas, il s'agit de l'AutomationElement qui représente le fournisseur de texte lui-même.
Move avec les paramètres de (TextUnit.Word, 1).	Déplace la plage de texte vers « est ». Étant donné que seuls les objets incorporés basés sur du texte sont considérés comme faisant partie du flux de texte, l'image de cet exemple n'affecte ni Move, ni sa valeur de retour (dans ce cas, 1).

Table

Tableau utilisé pour les exemples

Cellule avec l'image	Cellule avec le texte
	X
	Y
Image pour Z	Z

Exemple d'image incorporée

Exemple d'image incorporée 2

Exemple d'image incorporée 3

Image pour Z

Exemple 1 - Obtenir le conteneur de texte à partir du contenu d'une cellule.

Méthode appelée	Résultat
GetItem avec des paramètres (0,0)	Retourne le AutomationElement représentant le contenu de la cellule du tableau ; dans ce cas, l'élément est un contrôle de texte.
RangeFromChild où AutomationElement est l'objet retourné par la méthode GetItem précédente.	Retourne la plage qui couvre l'image .
GetEnclosingElement pour l'objet retourné par la méthode RangeFromChild précédente.	Retourne le AutomationElement représentant la cellule du tableau ; dans ce cas, l'élément est un contrôle de texte qui prend en charge TableItemPattern.
GetEnclosingElement pour l'objet retourné par la méthode GetEnclosingElement précédente.	Retourne le AutomationElement représentant le tableau.
GetEnclosingElement pour l'objet retourné par la méthode GetEnclosingElement précédente.	Retourne le AutomationElement qui représente le fournisseur de texte lui-même.

Exemple 2 - Obtenir le contenu textuel d'une cellule.

Méthode appelée	Résultat
GetItem avec des paramètres (1,1).	Retourne le AutomationElement représentant le contenu de la cellule du tableau ; dans ce cas, l'élément est un contrôle de texte.
RangeFromChild où AutomationElement est l'objet retourné par la méthode GetItem précédente.	Retourne « Y ».