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 objet-enfant 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é pour 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 de vous aider à découvrir des objets que vous recherchez dans l’arborescence d’objets runtime, mais il n’existe pas d’API de relation objet plus directe disponible pour votre scénario. Parfois, vous ne connaissez pas le type ou le nom exact de l’objet. Ou peut-être savez-vous qu’un objet spécifique apparaît quelque part dans l’arborescence, mais que 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 dans 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 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 toute collection en 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. En effet, 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 à nœud à nœud, car XAML est conçu pour le balisage et la facilité d’utilisation lors de la définition du balisage, il a donc parfois des éléments supplémentaires. Par exemple, XAML a des éléments de propriété, qui définissent des 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é en cours de définition 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 Vue d’ensemble DU 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, comme 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érale. (Vous pouvez théoriquement construire une telle arborescence à l’aide de propriétés parent et enfants spécifiques à l’objet, mais vous devez savoir exactement quelles propriétés chaque élément prend en charge, ce qui 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.

Traversée d’une arborescence visuelle

Le passage de l’arborescence d’objets (parfois connu familièrement 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 (généralement des collections) ou des relations parentes à un objet contenant (généralement, cela se fait à 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 de méthodes d’assistance, pour parcourir les axes de l’arborescence d’objets jusqu’à récupérer 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 de sorte que vous n’avez pas besoin d’interroger la structure de l’arborescence de manière approfondie. Pour éviter d’avoir à 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 disponible pour l’accès au code au moment de l’exécution. Il s’agit d’une technique beaucoup moins sujette aux erreurs pour obtenir des références d’objets que l’arborescence. Si vous créez des objets par le biais de code plutôt que de XAML, vous devez également 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 consiste à ajouter 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 ce 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 du contenu d’un contrôle ou d’un présentateur.

La traversée de l’arborescence vers le bas (loin de la racine) de plusieurs niveaux peut être effectuée à l’aide de GetChildrenCount pour des valeurs différentes de zéro, puis de GetChild pour demander un index spécifique. Vous devrez peut-être utiliser des techniques try/catch ou l’équivalent si vous essayez de caster 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 faire tout ce qui est utile (même pour une opération aussi simple que la vérification de sa valeur Name ).

Méthodes

DisconnectChildrenRecursive(UIElement)	Supprime explicitement toutes les références d’un UIElement cible, dans le but de nettoyer les cycles de référence.
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(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(Rect, UIElement)	Récupère un ensemble d’objets qui se trouvent 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 peuvent inclure des éléments qui suressent.
FindElementsInHostCoordinates(Rect, UIElement, Boolean)	Récupère un ensemble d’objets qui se trouvent 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 peuvent inclure des éléments qui suressent.
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ôles XAML
• Namescopes XAML