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.).
Remarque
Cela diffère de la définition du Component Object Model (COM) OLE (veuillez consulter la section Embedded Objects), où un élément est créé dans une application et intégré ou lié dans une autre application. Le fait que l’objet puisse être édité dans son application d’origine est sans importance dans le contexte de UI Automation.
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éments conteneurs
Éléments non conteneurs
- Calendrier
- Combobox
- DataGrid
- Document
- Modifier
- Groupe
- En-tête
- HeaderItem
- Liste
- Menu
- MenuBar
- Volet
- SplitButton
- Onglet
- Table
- Barre d'outils
- Tree
- TreeItem
- Fenêtre
- Lien
- CheckBoxes
- Bouton
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.
| Objets | Objets intégrés compatibles | Objets intégrés non compatibles |
|---|---|---|
| Objets non TextPattern intégrés | Bouton dans Microsoft Edge Table de données dans Microsoft Edge |
Bouton dans RichTextBlock dans le framework XAML de Microsoft Images avec texte alternatif dans Microsoft Edge ListView avec ListItems dans RichTextBlock dans le framework XAML de Microsoft |
| Objets TextPattern intégrés | Contrôle de saisie de type « texte » dans Microsoft Edge Tableau dans un document Word |
Élément TextBox dans un document Microsoft Word |
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é.
Remarque
Une plage dégénérée (ou réduite) est celle où le point de départ et le point de fin sont identiques. Les plages dégénérées sont souvent utilisées pour indiquer la position du curseur de texte via les méthodes ITextProvider GetSelection et GetCaretRange.
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.
| Méthode appelée | Result |
|---|---|
| IUIAutomationTextRange::GetText | Retourne la chaîne « L’URL https://www.microsoft.com est intégrée dans le texte ». |
| IUIAutomationTextRange::GetEnclosingElement | Retourne l’élément UI Automation le plus interne qui englobe la plage de texte, dans ce cas, l’élément d’automatisation qui représente le fournisseur de texte lui-même. |
| IUIAutomationTextRange::GetChildren | Retourne un élément UI Automation représentant le contrôle de lien hypertexte. |
| IUIAutomationTextPattern::RangeFromChild, où l’élément UI Automation a été retourné par la méthode précédente IUIAutomationTextRange::GetChildren. | Retourne la plage qui représente "https://www.microsoft.com". |
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.
| Méthode appelée | Result |
|---|---|
| IUIAutomationTextRange::GetText | Retourne la chaîne « www ». |
| IUIAutomationTextRange::GetEnclosingElement | Retourne l’élément UI Automation le plus interne qui englobe la plage de texte; dans ce cas, le contrôle de lien hypertexte. |
| IUIAutomationTextRange::GetChildren | Retourne NULL car la plage de texte ne couvre pas toute la chaîne URL. |
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.
| Méthode appelée | Result |
|---|---|
| IUIAutomationTextRange::GetText | Retourne la chaîne « L'URL ». |
| IUIAutomationTextRange::GetEnclosingElement | Retourne l’élément UI Automation le plus interne qui englobe la plage de texte, dans ce cas, l’élément qui représente le fournisseur de texte lui-même. |
| IUIAutomationTextRange::Move | Déplace la plage de texte vers « https:// » car le texte de l’hyperlien est constitué de mots individuels. Dans ce cas, le lien hypertexte n'est pas traité comme un objet unique. L’URL {http} est intégrée dans le texte. |
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.
| Méthode appelée | Result |
|---|---|
| IUIAutomationTextRange::GetText | Retourne la chaîne « L’image est intégrée dans le texte ». Tout texte ALT associé à l’image n’est pas inclus dans le flux de texte. |
| IUIAutomationTextRange::GetEnclosingElement | Retourne l’élément UI Automation le plus interne qui englobe la plage de texte, dans ce cas, l’élément qui représente le fournisseur de texte lui-même. |
| IUIAutomationTextRange::GetChildren | Retourne un élément UI Automation représentant le contrôle de l’image. |
| IUIAutomationTextPattern::RangeFromChild où l’élément UI Automation a été retourné par la méthode précédente IUIAutomationTextRange::GetChildren. | Retourne la plage dégénérée. |
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.
| Méthode appelée | Result |
|---|---|
| IUIAutomationTextRange::GetText | Retourne la chaîne « L'image ». |
| IUIAutomationTextRange::GetEnclosingElement | Retourne l’élément UI Automation le plus interne qui englobe la plage de texte, dans ce cas, l’élément qui représente le fournisseur de texte lui-même. |
| IUIAutomationTextRange::Move avec des paramètres de (TextUnit_Word, 2). | Déplace la plage de texte vers « est ». Comme seuls les objets intégrés basés sur le texte sont considérés comme faisant partie du flux de texte, l’image dans cet exemple n’affecte pas IUIAutomationTextRange::Move ou sa valeur de retour, dans ce cas, 2. |
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.
| Méthode appelée | Result |
|---|---|
| IUIAutomationGridPattern::GetItem avec des paramètres (1,1). | Retourne l’élément UI Automation représentant le contenu de la cellule du tableau. Dans ce cas, l’élément est un contrôle de texte. |
| IUIAutomationTextPattern::RangeFromChild où l’élément UI Automation est l’objet retourné par la méthode précédente IUIAutomationGridPattern::GetItem. | Retourne « Y ». |
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.