VisualTreeHelper Classe

Définition

Espace de noms:

Microsoft.UI.Xaml.Media

Fournit des méthodes utilitaires qui peuvent être utilisées pour parcourir les relations d’objet (le long des axes enfants-objet ou parent-objet) dans l’arborescence visuelle de votre application.

public ref class VisualTreeHelper sealed

/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class VisualTreeHelper final

[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class VisualTreeHelper

Public NotInheritable Class VisualTreeHelper

Héritage

Object Platform::Object IInspectable VisualTreeHelper

Attributs

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Exemples

Voici un exemple de fonction utilitaire qui peut copier une liste d’éléments enfants d’un type particulier à partir d’une arborescence visuelle. Il utilise les méthodes de traversée de base GetChildrenCount et GetChild. Il utilise la récursivité afin que les éléments puissent être trouvés quel que soit le niveau d’imbrication dans les conteneurs intermédiaires. Il utilise également une méthode d’extension IsSubclassOf de System.Reflection qui étend la comparaison de types pour considérer les sous-types comme une correspondance pour un type.

internal static void FindChildren<T>(List<T> results, DependencyObject startNode)
  where T : DependencyObject
{
    int count = VisualTreeHelper.GetChildrenCount(startNode);
    for (int i = 0; i < count; i++)
    {
        DependencyObject current = VisualTreeHelper.GetChild(startNode, i);
        if ((current.GetType()).Equals(typeof(T)) || (current.GetType().GetTypeInfo().IsSubclassOf(typeof(T))))
        {
            T asType = (T)current;
            results.Add(asType);
        }
        FindChildren<T>(results, current);
    }
}

Remarques

Arborescence visuelle

L’objectif de la classe VisualTreeHelper est d’aider à la découverte d’objets que vous recherchez dans l’arborescence runtime des objets, mais il n’existe pas d’API de relation d’objet plus directe disponible pour votre scénario. Parfois, vous ne connaissez pas le type exact ou le nom de l’objet. Vous savez peut-être qu’un objet spécifique apparaît quelque part dans l’arborescence, mais vous ne connaissez pas la position exacte. Pour ces types de scénarios, VisualTreeHelper est utile, car vous pouvez rechercher de manière récursive tous les objets de l’arborescence visuelle, puis examiner cet ensemble et rechercher une correspondance en fonction de vos critères.

L’arborescence visuelle d’une application peut être conceptualisée en tant que représentation filtrée de l’arborescence d’objets plus grande des objets et des propriétés d’une application. Seuls les objets qui ont une implication de rendu sont présents dans une arborescence visuelle. Par exemple, une classe de collection ne fait pas partie de l’arborescence visuelle. Au lieu de cela, l’arborescence visuelle extrait n’importe quelle collection dans un concept « enfants ».

Toutefois, l’arborescence visuelle peut également inclure des objets qui ne sont pas représentés en tant qu’éléments XAML dans le balisage XAML d’une page. Cela est dû au fait que l’arborescence visuelle ajoute des objets qui sont les parties composites des contrôles. Ces parties de contrôle peuvent provenir d’un modèle de contrôle appliqué, généralement XAML à partir d’un élément de dictionnaire de ressources ou d’un présentateur.

Le balisage XAML et une arborescence visuelle ne correspondent pas exactement à node-for-node, car XAML est conçu pour le balisage et la facilité d’utilisation pendant la définition de balisage, de sorte qu’il a parfois des éléments supplémentaires. Par exemple, XAML a des éléments de propriété, qui définissent les valeurs de propriété si un élément est trouvé imbriqué dans un autre. Dans une arborescence visuelle, cela ressemblerait simplement à une propriété sur un objet défini par un autre objet. XAML a également un concept de propriété de contenu, où la propriété définie n’est pas explicitement désignée dans le balisage. Pour plus d’informations sur la terminologie spécifique et les règles pour XAML, consultez la vue d’ensemble du code XAML.

L’arborescence visuelle est utilisée en interne pour le processus de rendu de l’interface utilisateur, mais la connaissance de la structure de l’arborescence visuelle est importante pour certains scénarios, tels que l’écriture ou le remplacement d’un modèle de contrôle, ou l’analyse de la structure et des parties d’un contrôle au moment de l’exécution. Pour ces scénarios, le Windows Runtime fournit l’API VisualTreeHelper qui peut examiner l’arborescence visuelle de manière plus généralisée. (Vous pouvez éventuellement construire une telle arborescence à l’aide de propriétés parent et enfants spécifiques à l’objet également, mais vous devrez connaître exactement les propriétés prises en charge par chaque élément, et c’est difficile à découvrir ou à gérer.)

Vous combinez généralement plusieurs appels d’API VisualTreeHelper pour écrire vos propres fonctions d’assistance qui examinent l’arborescence visuelle de manière spécifique aux scénarios de votre propre application.

Parcourir une arborescence visuelle

La traversée de l’arborescence d’objets (parfois connue sous le nom de marche de l’arbre) est une technique courante dans les modèles d’objets. Vous utilisez des propriétés qui référencent des objets enfants (en général, il s’agit de collections) ou des relations parentes à un objet conteneur (généralement cela est effectué à partir d’une collection et retourne la collection elle-même). Comme description approximative du processus, vous appelez une succession de propriétés enfants et de propriétés parentes, ou peut-être des méthodes d’assistance, pour parcourir les axes de l’arborescence d’objets jusqu’à ce que vous récupériez une valeur qui contient l’objet que vous recherchiez. En règle générale, vous devez être en mesure de construire votre contenu en XAML afin que vous n’ayez pas besoin d’interroger la structure de l’arborescence de manière approfondie. Pour éviter de devoir parcourir l’arborescence, vous devez donner aux éléments XAML une valeur pour l’attribut x :Name Name / dans le balisage XAML qui les crée. Cela crée une référence immédiate qui est disponible pour l’accès au code au moment de l’exécution, et c’est une technique beaucoup moins sujette aux erreurs pour obtenir des références d’objet que la marche à pied de l’arborescence. Sinon, si vous créez des objets par le biais du code plutôt que du code XAML, vous devez déclarer des champs privés ou des variables qui conservent la référence d’objet au moment de l’exécution. Il n’est généralement pas nécessaire de parcourir l’arborescence pour rechercher des objets créés dans votre propre code.

Toutefois, il existe des cas où il n’est pas possible ou pratique de donner un nom à un objet et de conserver une référence d’objet dans l’étendue. L’un de ces scénarios est si vous ajoutez du contenu dynamique fourni par l’utilisateur ou fourni par la liaison de données, ou à l’aide de modèles d’affichage et d’objets métier. Dans ces cas, vous ne pouvez pas toujours prédire le nombre d’éléments ajoutés ou la structure d’un contrôle et de ses enfants. Un autre scénario consiste à examiner un modèle appliqué pour un contrôle ou une section composite d’un contenu de contrôle ou de présentateur.

La traversée de l’arborescence vers le bas (loin de la racine) plusieurs niveaux peut être effectuée à l’aide de GetChildrenCount pour les valeurs non nulles, puis GetChild pour demander un index spécifique. Vous devrez peut-être utiliser des techniques try/catch ou l’équivalent si vous essayez de convertir des éléments en tant que sous-types UIElement spécifiques. En règle générale, l’API VisualTreeHelper retourne des éléments sous la forme d’un DependencyObject et vous devez le caster pour effectuer tout ce qui est utile (même pour une opération aussi simple que la vérification de sa valeur Name ).

Méthodes

Nom	Description
DisconnectChildrenRecursive(UIElement)	Supprime explicitement toutes les références d’un UIElement cible, avec l’objectif de nettoyer les cycles de référence.
FindElementsInHostCoordinates(Point, UIElement, Boolean)	Récupère un ensemble d’objets situés dans un point de coordonnées x-y spécifié d’une interface utilisateur d’application. L’ensemble d’objets représente les composants d’une arborescence visuelle qui partagent ce point.
FindElementsInHostCoordinates(Point, UIElement)	Récupère un ensemble d’objets situés dans un point de coordonnées x-y spécifié d’une interface utilisateur d’application. L’ensemble d’objets représente les composants d’une arborescence visuelle qui partagent ce point.
FindElementsInHostCoordinates(Rect, UIElement, Boolean)	Récupère un ensemble d’objets situés dans un cadre Rect spécifié d’une interface utilisateur d’application. L’ensemble d’objets représente les composants d’une arborescence visuelle qui partagent une zone rectangulaire et peut inclure des éléments qui sursinsent.
FindElementsInHostCoordinates(Rect, UIElement)	Récupère un ensemble d’objets situés dans un cadre Rect spécifié d’une interface utilisateur d’application. L’ensemble d’objets représente les composants d’une arborescence visuelle qui partagent une zone rectangulaire et peut inclure des éléments qui sursinsent.
GetChild(DependencyObject, Int32)	À l’aide de l’index fourni, obtient un objet enfant spécifique de l’objet fourni en examinant l’arborescence visuelle.
GetChildrenCount(DependencyObject)	Retourne le nombre d’enfants qui existent dans la collection enfant d’un objet dans l’arborescence visuelle.
GetOpenPopups(Window)	Récupère une collection de tous les contrôles contextuels ouverts à partir de la fenêtre cible.
GetOpenPopupsForXamlRoot(XamlRoot)	Récupère une collection de tous les contrôles contextuels ouverts à partir du xamlRoot cible.
GetParent(DependencyObject)	Renvoie l’objet parent d’un objet dans l’arborescence visuelle.

Voir aussi

• Modèles de contrôle XAML
• Étendues de noms XAML