Modèle de contrôle ItemContainer

Décrit des instructions et des conventions pour l’implémentation d’IItemContainerProvider, y compris des informations sur les méthodes. Le modèle de contrôle ItemContainer est utilisé pour prendre en charge la virtualisation des éléments.

Les contrôles qui contiennent un grand nombre d’éléments enfants peuvent utiliser la virtualisation pour gérer efficacement les éléments. Avec la virtualisation, le contrôle conserve toutes les informations en mémoire pour un sous-ensemble d’éléments à un moment donné. En règle générale, le sous-ensemble inclut uniquement les éléments actuellement visibles par l’utilisateur. Les informations complètes sur les éléments virtualisés restants sont conservées dans le stockage et sont chargées en mémoire, ou réalisées, à mesure que le contrôle en a besoin, par exemple, à mesure que de nouveaux éléments deviennent visibles par l’utilisateur.

Par exemple, le diagramme suivant montre une zone de liste qui contient des milliers d’éléments virtualisés. Étant donné que le contrôle conserve des informations complètes uniquement pour les éléments enfants actuellement visibles, le fournisseur peut exposer les éléments Microsoft UI Automation uniquement pour les éléments 100 à 127.

Les contrôles qui utilisent la virtualisation représentent un défi, car seuls les éléments réalisés (dé virtualisés) sont entièrement disponibles en tant qu’éléments UI Automation dans l’arborescence UI Automation. Les éléments virtualisés n’existent pas dans l’arborescence. Les informations les concernant ne sont donc pas disponibles.

Pour fournir des informations sur les éléments virtualisés, les fournisseurs implémentent le modèle de contrôle ItemContainer , qui expose l’interface IItemContainerProvider . La méthode FindItemByProperty recherche les éléments enfants en fonction de la valeur d’une propriété particulière, telle que Name, AutomationId ou IsSelected. Si un élément est virtualisé, FindItemByProperty récupère un élément d’espace réservé UI Automation pour l’élément. Un élément d’espace réservé est une implémentation de l’interface IRawElementProviderSimple qui prend en charge uniquement le modèle de contrôle VirtualizedItem .

La méthode IVirtualizedItemProvider::Realize permet à un client de demander la réalisation d’un élément virtualisé, exposant ainsi un élément UI Automation complet pour l’élément afin que toutes les propriétés et modèles requis soient disponibles.

Bien que l’objectif principal du modèle de contrôle ItemContainer soit de prendre en charge les scénarios de conteneur virtualisé, il peut être implémenté par n’importe quel conteneur qui récupère les éléments enfants par nom, que le conteneur utilise ou non la virtualisation.

Cette rubrique contient les sections suivantes.

• Conventions et directives d'implémentation
• Membres obligatoires pour IItemContainerProvider
• Rubriques connexes

Conventions et directives d'implémentation

Lors de l’implémentation du modèle de contrôle ItemContainer , notez les instructions et conventions suivantes :

• Tout contrôle pouvant contenir des éléments virtualisés doit prendre en charge le modèle de contrôle ItemContainer . Tout conteneur qui prend en charge la récupération d’éléments en fonction d’une valeur de propriété peut prendre en charge ce modèle, que le conteneur utilise ou non la virtualisation.
• Lorsqu’un conteneur est virtualisé, d’autres modèles de contrôles tels que Selection, Table et Grid peuvent être affectés. Par exemple, la méthode ISelectionProvider::GetSelection peut prendre en charge uniquement les éléments qui se trouvent dans la fenêtre d’affichage, ou uniquement les éléments sélectionnés qui ne sont actuellement pas virtualisés.
• Le modèle de contrôle Scroll ne doit pas être affecté par la virtualisation.
• Aucune information sur le nombre d’éléments ou l’index n’est disponible pour les éléments virtualisés. Un contrôle virtualisé peut utiliser la propriété DescribedBy ou ItemStatus pour fournir ces informations, si nécessaire.
• Les développeurs de contrôles doivent documenter et publier les détails de toutes les propriétés et modèles de contrôle UI Automation affectés par l’utilisation de la virtualisation. Bien que les modèles de contrôle ItemContainer et VirtualizedItem offrent une prise en charge de base, ils peuvent ne pas prendre en charge certains comportements de virtualisation.

Les instructions et exigences suivantes s’appliquent à la méthode IItemContainerProvider::FindItemByProperty .

• Bien qu’il ne soit pas obligatoire, Microsoft recommande vivement que FindItemByProperty prend en charge les propriétés Name, AutomationId et IsSelected .
• FindItemByProperty peut être lent s’il doit parcourir plusieurs objets pour en trouver un correspondant.
• FindItemByProperty peut être appelé à plusieurs reprises pour rechercher des éléments dans l’ordre. Les éléments peuvent être dans n’importe quel ordre tant que chaque élément n’est retourné qu’une seule fois.
• FindItemByProperty peut être implémenté pour rechercher uniquement les éléments qui apparaissent dans la vue de contrôle ou de contenu de l’arborescence UI Automation. Les éléments qui apparaissent uniquement en mode brut peuvent être ignorés pour éviter de récupérer plusieurs éléments qui ne représentent qu’une partie d’un « élément » pour l’utilisateur.
• Lorsque les critères de recherche correspondent à un élément virtualisé, le fournisseur peut retourner un élément d’espace réservé qui prend en charge le modèle de contrôle VirtualizedItem . Les instructions suivantes s’appliquent aux éléments d’espace réservé :
  • La récupération d’un élément d’espace réservé pour un élément virtualisé ne doit pas entraîner de modifications de l’interface utilisateur.
  • L’élément d’espace réservé doit être un homologue d’autres éléments enfants (un événement de modification de structure est requis).
  • Lorsque cela est possible, le fournisseur peut créer un élément Automation complet au lieu d’un espace réservé.
• Lorsque les critères de recherche correspondent à un élément non virtualisé, le fournisseur doit retourner l’élément réel, et non un espace réservé.
• Quand aucun élément n’est trouvé, IItemContainerProvider::FindItemByProperty doit définir le paramètre pFound sur NULL et retourner S_OK.
• Lorsque le paramètre propertyId a la valeur 0, le fournisseur doit retourner l’élément suivant après pStartAfter.
• Si le paramètre pStartAfter a la valeur NULL et que propertyId a la valeur 0, le fournisseur doit retourner le premier élément du conteneur.
• Lorsque le paramètre propertyId est 0, le paramètre value est ignoré.

Les instructions et exigences suivantes s’appliquent aux éléments d’espace réservé pour les éléments virtualisés dans l’arborescence UI Automation.

• Bien que les fournisseurs soient encouragés à prendre en charge davantage de propriétés et de modèles de contrôle pour un élément d’espace réservé, seul le modèle de contrôle VirtualizedItem est requis.
• Le fournisseur peut invalider un élément d’espace réservé précédent quand IItemContainerProvider::FindItemByProperty est appelé à nouveau. (Si un client doit réaliser l’élément d’espace réservé, il doit le faire immédiatement ; sinon, l’élément peut être invalidé si FindItemByProperty est appelé à nouveau ou si la fenêtre d’affichage change pour une raison quelconque.)
• Les actions de l’interface utilisateur telles que le défilement ou le redimensionnement peuvent entraîner la modification de la fenêtre d’affichage du conteneur et la visibilité d’un nouvel ensemble d’éléments enfants. Dans ce cas, les éléments d’espace réservé précédemment récupérés peuvent ne pas être disponibles dans l’arborescence UI Automation.
• Le fournisseur ne doit pas virtualiser les éléments d’interface utilisateur disponibles à l’écran dans la fenêtre d’affichage de l’objet conteneur.

Membres obligatoires pour IItemContainerProvider

La méthode suivante est requise pour implémenter l’interface IItemContainerProvider .

Le modèle de contrôle ItemContainer n’a pas de propriétés ou d’événements associés.

Rubriques connexes

Types de contrôles et leurs modèles de contrôle pris en charge

Vue d'ensemble des modèles de contrôle UI Automation

Vue d’ensemble de l’arborescence UI Automation

Modèle de contrôle VirtualizedItem