VisualTreeHelper Classe

  • Référence

Définition

Espace de noms:
Windows.UI.Xaml.Media
Modifier

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

public ref class VisualTreeHelper sealed
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 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(Windows.Foundation.UniversalApiContract), 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

Configuration requise pour Windows

Famille d’appareils
Windows 10 (introduit dans 10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduit dans v1.0)

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 de faciliter la découverte des objets que vous recherchez dans l’arborescence d’objets runtime, mais il n’existe pas d’API de relation objet-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 comme une 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. 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é, qui est 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 lors de la définition du balisage, de sorte qu’il a parfois des éléments supplémentaires. Par exemple, XAML contient des éléments de propriété, qui définissent des valeurs de propriété si un élément est 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 de XAML.

L’arborescence visuelle est utilisée en interne pour le processus de rendu de l’interface utilisateur, mais il est important de connaître la structure de l’arborescence visuelle 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 d’une 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 devrez 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

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 objet. Vous utilisez des propriétés qui référencent des objets enfants (généralement des collections) ou des relations parentes avec un objet conteneur (généralement, cette opération est effectuée à partir d’une collection et retourne la collection elle-même). En guise de 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 de telle sorte que vous n’avez pas besoin d’interroger la structure de l’arborescence de manière intensive. 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 qui est disponible pour l’accès au code au moment de l’exécution, et il s’agit d’une technique beaucoup moins sujette aux erreurs pour obtenir des références d’objet que la marche à pied de l’arborescence. Si vous créez des objets via du code plutôt que 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 trouver 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 d’un contenu de contrôle ou de présentateur.

La traversée de l’arborescence vers le bas (loin de la racine) peut être effectuée à l’aide de GetChildrenCount pour les 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 effectuer quelque chose d’utile (même pour une opération aussi simple que la vérification de sa valeur Name ).

Remarques pour les versions précédentes

Windows 8

Threading de l’interface utilisateur

Windows 8 permis les appels de fonction VisualTreeHelper qui référençant des objets sur le thread d’interface utilisateur incorrect (et non le thread actuel). À compter de Windows 8.1, la fonction lève une exception si elle n’est pas appelée à partir du thread d’interface utilisateur actuel. La prise en compte de ce nouveau comportement doit être un scénario de migration d’application très rare ; il est difficile d’obtenir des éléments d’interface utilisateur entre les threads en premier lieu.

Les applications qui ont été compilées pour Windows 8 mais qui s’exécutent sur Windows 8.1 utilisent le comportement Windows 8.1 et lèvent spécifiquement sur l’appel de fonction VisualTreeHelper plutôt que sur tout code d’application en aval qui utilise un objet cross-thread.

Interface utilisateur de l’application pour le clavier visuel

Windows 8 avait une logique implémentée en interne qui associerait un ScrollViewer à l’interface utilisateur globale de l’application chaque fois que l’utilisateur appelle le clavier visuel. Ce clavier visuel est une fonctionnalité d’accessibilité spécifique que les utilisateurs demandent via le Centre d’ergonomie. Il n’est pas identique au clavier souple qui peut apparaître dans l’interface utilisateur de l’application pour les contrôles d’entrée de texte, si le système ne détecte aucun périphérique clavier. Le ScrollViewer interne fait ici pour permettre de faire défiler la zone où se trouve l’application, si le défilement est forcé, car le clavier prend de l’espace dans l’interface utilisateur.

À compter de Windows 8.1, le système a toujours le comportement de l’interface utilisateur/disposition lorsque le clavier visuel s’affiche, mais il n’utilise plus ce ScrollViewer créé en interne. Au lieu de cela, il utilise un contrôle interne dédié que le code d’application ne peut pas modifier ou inspecter.

La plupart des aspects de ce changement de comportement n’affectent pas du tout les applications. Toutefois, votre application a peut-être anticipé ce comportement en fournissant un style implicite pour ScrollViewer destiné à modifier la disposition, ou en parcourant l’arborescence avec VisualTreeHelper pour trouver ce ScrollViewer créé en interne et le modifier au moment de l’exécution. Pour une application compilée pour Windows 8.1 ce code ne sera pas utile.

Les applications qui ont été compilées pour Windows 8, mais qui sont exécutées dans Windows 8.1, continuent d’appliquer le comportement Windows 8.

Historique des versions

Version de Windows Version du SDK Valeur ajoutée
1903 18362 GetOpenPopupsForXamlRoot

Méthodes

DisconnectChildrenRecursive(UIElement)

Supprime explicitement toutes les références d’un élément 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 frame 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 suressindent.
FindElementsInHostCoordinates(Rect, UIElement, Boolean)

Récupère un ensemble d’objets qui se trouvent dans un frame 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 suressindent.
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)

Retourne l’objet parent d’un objet dans l’arborescence visuelle.

S’applique à

Voir aussi