Comment UI Automation expose des objets incorporés

Cette rubrique décrit comment Microsoft UI Automation utilise les motifs de contrôle Text et TextRange pour exposer des objets intégrés (éléments enfants ou descendants) dans un document texte ou un conteneur.

Pour UI Automation, un objet intégré est tout élément ayant des limites non textuelles, comme une image, un lien hypertexte, un tableau ou un type de document (feuille de calcul Microsoft Excel, fichier Microsoft Windows Media, etc.).

Objets incorporés et arborescence UI Automation

Les objets intégrés sont traités comme des éléments individuels dans la vue de contrôle de l’arborescence UI Automation. Ils sont exposés comme des enfants du conteneur de texte afin qu’ils puissent être accessibles via le même modèle d’objet que les autres contrôles dans UI Automation.

Le tableau suivant liste des exemples d’éléments conteneurs et non conteneurs.

L’image suivante montre un conteneur de texte (document) avec un tableau et une image intégrés.

La vue du contenu UI Automation du document précédent est montrée dans le diagramme suivant.

« Compatible » et « Non-Compatible » objets intégrés

Certains fournisseurs de UI Automation utilisent le même stockage de texte pour chaque objet TextPattern qu’ils contiennent. Les objets pris en charge par le même stockage de texte que leur conteneur sont appelés « objets intégrés compatibles ». Ces objets peuvent eux-mêmes être des objets TextPattern et, dans ce cas, leurs plages de texte sont comparables aux plages de texte obtenues de leur conteneur. Cela permet aux fournisseurs d’exposer les informations client sur les objets TextPattern individuels comme s’ils étaient un seul grand fournisseur de texte.

Cependant, les fournisseurs peuvent utiliser des stockages de texte différents pour différents objets TextPattern intégrés dans un conteneur TextPattern. Les objets non pris en charge par le stockage de texte du conteneur sont appelés « objets intégrés non compatibles ». Ces types d’objets intégrés peuvent ou non être basés sur TextPattern.

Le tableau suivant répertorie certains exemples d’objets intégrés compatibles et non compatibles.

Exposition des objets intégrés

Les motifs de contrôle Text et TextRange exposent des propriétés et des méthodes qui facilitent la navigation et l’interrogation des objets intégrés.

Le contenu textuel (ou texte interne) d’un conteneur de texte et d’un objet incorporé, tel qu’un lien hypertexte ou 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 le texte pour le réciter, l’interpréter ou l’analyser d’une manière ou d’une autre, la plage de texte doit être vérifiée pour les cas particuliers, tels qu’un tableau avec du contenu textuel ou d’autres objets intégrés. Appelez IUIAutomationTextRange::GetChildren pour obtenir une interface IUIAutomationElement pour chaque objet intégré, puis appelez IUIAutomationTextPattern::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é.

Le diagramme suivant montre un flux de texte avec des objets intégrés et leurs étendues de plage.

Objets intégrés et TextUnit

Un objet ITextProvider peut être traversé par un TextUnit spécifié. Les fournisseurs contenant des objets intégrés peuvent être traversés de la même manière, mais les objets intégrés affectent la traversée. Voici quelques points à connaître :

• Tout objet intégré non compatible est représenté par le caractère de remplacement U+FFFC dans le stockage de texte du motif TextPattern de l’élément conteneur. Il est également considéré à la fois comme une unité de caractère et une unité de mot.
• Les objets intégrés compatibles peuvent être constitués de plusieurs caractères et mots.
• L’élément englobant est l’élément le plus bas qui couvre toute la plage de texte.
• Les éléments enfants d’une plage sont également des éléments enfants d’un élément conteneur qui est partiellement ou complètement inclus dans la plage.
• Idéalement (surtout dans le cas d’éléments conteneurs comme Table), une limite de mot ne dépasse pas la limite de l’objet. Dans l’exemple suivant, l’unité de mot « Bar » ne contient aucune position de texte en dehors de la balise </td> (<br \> ne fait pas partie du mot « Bar »).

<table style="width:100%">
  <tr>
    <th>Name</th>
    <th>Notes</th>
  </tr>
  <tr>
    <td>Eve Jackson</td>
    <td>Foo Bar</td>
  </tr>
</table>
<br/>

• En général, <br \> est traité comme un mot individuel tel qu’il ne dépasse pas une limite de ligne.
• Une exception à la règle précédente est lorsqu’une unité de texte Word contient des objets complets en son sein. Par exemple, <p>Hello <a href="#">link</a> here.</p>, qui inclut des conteneurs en ligne, contient les mots « Hello », « link » et « here. » Où « link » a un objet TextPattern comme élément englobant et un objet lien comme son enfant.
• Dans le cas des unités de caractère, l’objet est l’élément englobant (les unités de texte comme celle-ci ne devraient pas avoir d’enfants).
• Les objets d’annotation ne doivent pas être représentés comme des objets intégrés. Par exemple, la présence d’autres spécificateurs d’auteur dans un document co-écrit.
• Les objets intégrés occupent au moins une position de curseur, l’annotation est juste des métadonnées.
• Chaque limite d’objet (début et fin) est représentée par une rupture de format dans la plage de document TextPattern.
• Pour HTML, chaque balise html ne se traduit pas nécessairement par un objet UI Automation. Par exemple, le contenu dans les balises emphasis ne doit pas nécessairement être représenté comme un élément mais plutôt comme un flux de texte où UIA_IsItalicAttributeId retourne TRUE.
• Le point de départ est inclusif et est le point préféré tandis que le point de fin est exclusif. Cela est utile lorsque la plage est dégénérée et que les points de début et de fin appartiennent à la même position pour cette plage.

Comparer les objets intégrés

Les objets TextPattern imbriqués qui sont dans une relation enfant similaire et partagent le même stockage de texte de support sont appelés comparables. Dans ce cas, les plages de l’un ou l’autre des objets TextPattern peuvent être comparées en utilisant ITextRangeProvider::Compare et ITextRangeProvider::CompareEndpoints. Les deux résultent en une valeur numérique valide spécifiant leur position relative.

Un objet non TextPattern intégré dans un objet TextPattern est comparable au TextPattern si l’objet a une plage valide dans le TextPattern (ITextProvider::RangeFromChild) et que le contenu derrière la plage de texte n’est pas vide et n’est pas un caractère de remplacement.

Objets TextPattern intégrés et l’unité Document

Pour les objets TextPattern intégrés, l’unité Document ne reconnaît que le contenu contenu dans cet élément.

Hiérarchie des éléments TextPattern de Word

• L’élément document implémente TextPattern et Document retourne toute la plage du document Word.
• Les pages individuelles du document implémentent TextPattern et Document retourne le contenu de ces pages individuelles (même si les pages partagent le même stockage de texte avec tout le TextPattern du document).

Page Web et contrôles de saisie de texte dans Edge

• L’élément Pane de la page Web principale implémente TextPattern et expose tout le contenu de la page Web.
• Les contrôles de saisie de texte individuels prennent en charge TextPattern où une plage de document représente le texte contenu dans chaque champ de saisie (même s’ils partagent le même stockage de texte avec toute la page Web).

Scénarios courants

Cette section présente des exemples de scénarios courants impliquant des objets intégrés : hyperliens, images et tableaux. Dans les exemples suivants, l’accolade gauche ({) représente le point de départ de la plage de texte et l’accolade droite (}) représente le point de fin.

Exemple HyperLink 1 : Une plage de texte contenant un lien hypertexte intégré

La plage de texte suivante contient un lien hypertexte intégré.

{L’URL https://www.microsoft.com est intégré dans le texte}.

Appeler les méthodes IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren, et IUIAutomationTextPattern::RangeFromChild entraîne les comportements décrits dans le tableau suivant.

Exemple HyperLink 2 : Une plage de texte couvrant partiellement un lien hypertexte intégré

La plage de texte suivante couvre partiellement un lien hypertexte intégré.

L’URL https://{www} est intégrée dans le texte.

Appeler les méthodes IUIAutomationTextRange::GetText, GetEnclosingElement, et GetChildren entraîne les comportements décrits dans le tableau suivant.

Exemple HyperLink 3 : Une plage de texte couvrant partiellement le contenu d’un conteneur de texte

La plage de texte suivante couvre 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} https://www.microsoft.com est intégrée dans le texte.

Appeler les méthodes IUIAutomationTextRange::GetText, GetEnclosingElement, et Move entraîne les comportements décrits dans le tableau suivant.

Exemple Image 1 : Une plage de texte contenant une image intégrée

La plage de texte suivante contient une image intégrée d’une navette.

{L’image est incorporée dans le texte}.

Appeler les méthodes IUIAutomationTextRange::GetText, GetEnclosingElement, GetChildren, et IUIAutomationTextPattern::RangeFromChild entraîne les comportements décrits dans le tableau suivant.

Exemple Image 2 : Une plage de texte couvrant partiellement le contenu d’un conteneur de texte

La plage de texte suivante couvre 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} est incorporée dans du texte.

Appeler les méthodes IUIAutomationTextRange::GetText, GetEnclosingElement, et Move entraîne les comportements décrits dans le tableau suivant.

Table

Exemple de tableau 1 : Obtient le conteneur de texte à partir du contenu d’une cellule

Le tableau suivant obtient le conteneur de texte à partir du contenu d’une cellule.

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

Appeler les méthodes IUIAutomationGridPattern::GetItem, IUIAutomationTextPattern::RangeFromChild, et IUIAutomationTextRange::GetEnclosingElement entraîne les comportements décrits dans le tableau suivant.

Méthode appelée	Result
IUIAutomationGridPattern::GetItem avec des paramètres (0, 0).	Retourne l’élément UI Automation qui représente le contenu de la cellule du tableau, dans ce cas, l’élément est un contrôle de texte.
iuiautomationtextpattern::rangefromchild	retourne la plage de l’image .
GetEnclosingElement pour l’objet retourné par la méthode précédente IUIAutomationTextPattern::RangeFromChild.	Retourne l’élément UI Automation représentant la cellule du tableau. Dans ce cas, l’élément est un contrôle de texte qui prend en charge le motif de contrôle TableItem.
IUIAutomationTextRange::GetEnclosingElement pour l’objet retourné par la méthode précédente GetEnclosingElement.	Retourne l’élément UI Automation représentant le tableau.
IUIAutomationTextRange::GetEnclosingElement pour l’objet retourné par la méthode précédente GetEnclosingElement.	Retourne l’élément UI Automation qui représente le fournisseur de texte lui-même.

Exemple de tableau 2 : Obtient le contenu textuel d’une cellule

Le tableau de l’exemple précédent obtient le contenu textuel d’une cellule.

Appeler les méthodes IUIAutomationGridPattern::GetItem et IUIAutomationTextPattern::RangeFromChild entraîne les comportements décrits dans le tableau suivant.

Lors du déplacement dans un document par TextUnit_Line, si la plage de texte entre dans un tableau intégré, chaque ligne de texte dans une cellule doit être traitée comme une ligne.

Rubriques connexes

Conceptuel

• À propos des motifs de contrôle Text et TextRange
• Attributs de texte UI Automation
• Vue d'ensemble des modèles de contrôle UI Automation
• Prise en charge d’UI Automation pour le contenu textuel