VisualTreeHelper.FindElementsInHostCoordinates Méthode

public:
 static IIterable<UIElement ^> ^ FindElementsInHostCoordinates(Point intersectingPoint, UIElement ^ subtree);

/// [Windows.Foundation.Metadata.DefaultOverload]
/// [Windows.Foundation.Metadata.Overload("FindElementsInHostCoordinatesPoint")]
 static IIterable<UIElement> FindElementsInHostCoordinates(Point const& intersectingPoint, UIElement const& subtree);

[Windows.Foundation.Metadata.DefaultOverload]
[Windows.Foundation.Metadata.Overload("FindElementsInHostCoordinatesPoint")]
public static IEnumerable<UIElement> FindElementsInHostCoordinates(Point intersectingPoint, UIElement subtree);

function findElementsInHostCoordinates(intersectingPoint, subtree)

Public Shared Function FindElementsInHostCoordinates (intersectingPoint As Point, subtree As UIElement) As IEnumerable(Of UIElement)

Paramètres

Retours

Ensemble énumérable d’objets UIElement dans la composition de l’arborescence visuelle au point spécifié, répertorié par ordre z inverse.

Attributs

DefaultOverloadAttribute OverloadAttribute

Exemples

Il s’agit d’un exemple de méthode utilitaire qui détermine si un élément d’un nom donné existe n’importe où dans l’ordre z à un point de l’interface utilisateur d’une application.

private bool DoesPointContainElement(Point testPoint, string elementName, UIElement referenceFrame)
{
    IEnumerable<UIElement> elementStack = 
      VisualTreeHelper.FindElementsInHostCoordinates(testPoint, referenceFrame);
    foreach (UIElement item in elementStack)
    {
        FrameworkElement feItem = item as FrameworkElement; 
//cast to FrameworkElement, need the Name property
        if (feItem != null)
        {
            if (feItem.Name.Equals(elementName))
            {
                 return true;
            }
        }
     }
     // elementName was not in this stack 
     return false;
}

Remarques

La valeur de retour n’est pas un seul élément, c’est une collection. La collection peut avoir plusieurs éléments, car plusieurs éléments d’interface utilisateur peuvent être empilés les uns sur les autres dans un ordre z. Les techniques conventionnelles de test d’accès exposées par les gestionnaires d’événements d’entrée, telles que la valeur de l’expéditeur d’un événement PointerPressed , ne comptent que pour l’élément le plus haut qui a l’ordre z le plus élevé. Les méthodes FindElementsInHostCoordinates retournent l’ensemble de la pile d’éléments qui partagent ce point ou cette zone dans l’interface utilisateur de l’application, répertoriés par ordre z inverse. L’utilisation de FindElementsInHostCoordinates peut donc être utile pour examiner les cas où vous avez intentionnellement ou involontairement empilé des éléments. Vous pouvez corriger l’ordre de rendu et de test d’accès, ou examiner cette commande pour d’autres raisons.

FindElementsInHostCoordinates est utile pour trois scénarios : test d’accès de base, test d’accès qui filtre pour un élément spécifique et détermine s’il existe des éléments dans une arborescence visuelle qui sont en cours de superposition au même point.

Test d’accès de base

Pour les tests d’accès de base, l’objectif est de découvrir quel élément est le plus élevé dans l’ordre z d’une interface utilisateur d’application à un point donné dans les coordonnées x-y. En plus d’être l’élément qui dessine le plus haut dans l’interface utilisateur rendue, cet élément est également important, car il s’agit de la source d’événements signalés s’il existe des interactions utilisateur telles que des événements de pointeur. Vous avez peut-être atteint des scénarios de test dans lesquels vous souhaitez savoir quel élément existe dans l’ordre z supérieur avant qu’un événement d’entrée ait lieu, afin de pouvoir l’anticiper et peut-être corriger les erreurs de placement de l’ordre z.

Pour ce scénario, vous devez passer le point qui vous intéresse dans le test d’accès comme valeur du paramètre intersectingPoint . Pour le paramètre de sous-arborescence , vous pouvez le passer comme null. Vous pouvez également spécifier la sous-arborescence comme un élément dont vous savez qu’il s’agit du visuel racine d’une page ou d’un élément que vous souhaitez être l’arrêt final pour les tests d’accès.

L’élément qui est le plus haut dans l’ordre z est toujours le premier élément de l’IEnumerable d’éléments UIElement retourné. Ainsi, pour les tests d’accès de base, vous n’êtes généralement intéressé que par ce tout premier élément. Tous les éléments supplémentaires dans IEnumerable sont d’autres éléments qui se trouvent également à ce stade, mais qui sont plus loin dans l’ordre z et qui dessinent sous ce premier élément. Les éléments plus en arrière ne se signalent pas en tant que source d’un événement d’entrée à ce stade, seul l’élément supérieur le ferait.

Test d’accès avec filtrage d’éléments

Parfois, vous souhaitez savoir si un élément spécifique existe à un certain point de l’interface utilisateur. Si c’est le cas, vous pouvez spécifier ce point pour l’intersection dePoint et spécifier l’élément que vous recherchez comme paramètre de sous-arborescence . Si la valeur de retour n’est pas vide, cela signifie que l’élément existe à ce stade de l’interface utilisateur. Si l’élément est le premier élément de la valeur de retour, cela signifie que l’élément est le plus haut dans l’ordre z à l’intersection dePoint. S’il existe d’autres éléments dans la valeur de retour et que la sous-arborescence n’est pas la première, les autres éléments représentent les éléments rendus à l’intersectionPoint qui sont plus élevés dans l’ordre z (visuellement, ces éléments sont affichés au-dessus de l’élément subtree ). Dans ce cas, la sous-arborescence est le dernier élément du IEnumerable retourné, et non le premier.

Si la valeur de retour est vide, cela signifie que l’élément subtree n’existait pas là, à une valeur d’ordre z.

Recherche d’un sur-dessin ou d’un regard sur l’arborescence visuelle complète

Une interface utilisateur peut être dynamique, en particulier si vous utilisez des collections de liaison de données pour la population de l’interface utilisateur. Il est donc parfois nécessaire de savoir quel élément est actuellement en haut. Vous pouvez anticiper des points dans l’application où l’utilisateur peut interagir et vérifier que les interactions que vous envisagez sont actuellement possibles. Pour ce scénario, vous spécifiez généralement une valeur point qui représente un point connu, comme (0,0) qui est actuellement une coordonnée valide qui se trouve dans la fenêtre de votre application. Pour le paramètre de sous-arborescence , vous pouvez le passer comme null. Vous pouvez également spécifier la sous-arborescence comme un élément dont vous savez qu’il s’agit du visuel racine d’une page ou d’un élément que vous souhaitez être l’arrêt final pour les tests d’accès.

Dans la valeur de retour, vous pouvez être intéressé par chacun des éléments dans. Vous pouvez donc utiliser foreach ou des techniques similaires spécifiques au langage pour itérer la collection et exécuter votre propre logique sur chacun de ces éléments. N’oubliez pas que le premier élément de cette collection est celui qui est le plus haut dans l’ordre z.

Si vous programmez à l’aide de C# ou de Microsoft Visual Basic, le type de valeur de retour de cette méthode est projeté sous la forme d’une collection générique IEnumerable qui contient des éléments UIElement . Si vous programmez à l’aide d’extensions de composant Visual C++ (C++/CX), le type de retour de cette méthode est IIterable<UIElement>.

Voir aussi

• Point
• Interactions avec la souris

public:
 static IIterable<UIElement ^> ^ FindElementsInHostCoordinates(Rect intersectingRect, UIElement ^ subtree);

/// [Windows.Foundation.Metadata.Overload("FindElementsInHostCoordinatesRect")]
 static IIterable<UIElement> FindElementsInHostCoordinates(Rect const& intersectingRect, UIElement const& subtree);

[Windows.Foundation.Metadata.Overload("FindElementsInHostCoordinatesRect")]
public static IEnumerable<UIElement> FindElementsInHostCoordinates(Rect intersectingRect, UIElement subtree);

function findElementsInHostCoordinates(intersectingRect, subtree)

Public Shared Function FindElementsInHostCoordinates (intersectingRect As Rect, subtree As UIElement) As IEnumerable(Of UIElement)

Paramètres

Retours

Ensemble énumérable d’objets UIElement qui se trouvent dans la composition de l’arborescence visuelle dans le cadre Rect spécifié.

Attributs

OverloadAttribute

Exemples

Compte tenu de cette interface utilisateur XAML :

<Canvas Name="canvas">
  <Rectangle Name="outermost" Fill="Red" Width="200" Height="200"/>
  <Rectangle Canvas.Left="40" Canvas.Top="40" Name="hidden" Fill="Green" Width="120" Height="120"/>
  <Rectangle Canvas.Left="40" Canvas.Top="40" Name="shown" Fill="Orange" Width="120" Height="120"/>
  <Rectangle Canvas.Left="80" Canvas.Top="80" Name="center" Fill="Yellow" Width="40" Height="40"/>
  <Rectangle Canvas.Left="190" Canvas.Top="190" Name="bottomright" Fill="Pink" Width="10" Height="10"/>
</Canvas>

Voici quelques exemples d’utilisations et de résultats de FindElementsInHostCoordinates, en utilisant différentes valeurs de sous-arborescence :

private void Test(object sender, RoutedEventArgs e)
{
    IEnumerable<UIElement> hits;
    hits =  VisualTreeHelper.FindElementsInHostCoordinates(
      new Rect(75,75,50,50), canvas);
    foreach (UIElement element in hits)
    {
        //run logic here, such as log the results 
    }
// results in the following set of elements, listed by Name:
// center - the last declared XAML element is first returned, if within the area
// shown - renders, underneath 'center' in part of the area but visible on the edges
// hidden - entirely under 'shown', not visible but part of the area, an overdraw
// outermost - draws under all the above
// canvas - the 'subtree' value, and the last element reported

    hits = VisualTreeHelper.FindElementsInHostCoordinates(
      new Rect(75,75,50,50), center);
    foreach (UIElement element in hits) {
        //run logic here, such as log the results
    }
// results in only 'center', because it was 'subtree' and it's also topmost

    hits = VisualTreeHelper.FindElementsInHostCoordinates(
      new Rect(75,75,50,50), bottomright);
// results in an empty set, 'bottomright' isn't in the specified rect
}

Remarques

La valeur de retour n’est pas un seul élément, c’est une collection. La collection peut avoir plusieurs éléments, car plusieurs éléments d’interface utilisateur peuvent être empilés les uns sur les autres dans un ordre z, ainsi que plusieurs éléments entièrement ou partiellement dans le cadre intersectingRect . Les techniques conventionnelles de test d’accès exposées par les gestionnaires d’événements d’entrée, telles que la valeur de l’expéditeur d’un événement PointerPressed , ne comptent que pour l’élément le plus haut qui a l’ordre z le plus élevé. Les méthodes FindElementsInHostCoordinates retournent l’ensemble de la pile d’éléments qui partagent ce point ou cette zone dans l’interface utilisateur de l’application, répertoriés par ordre d’arborescence visuelle (qui est généralement identique à l’inverse de l’ordre de déclaration XAML). L’utilisation de FindElementsInHostCoordinates peut donc être utile pour examiner les cas où vous avez intentionnellement ou involontairement empilé des éléments. Vous pouvez corriger l’ordre de rendu et de test d’accès, ou examiner cette commande pour d’autres raisons.

FindElementsInHostCoordinates sur une zone est utile pour deux scénarios : le test d’accès de base et le test d’accès qui filtre pour un élément spécifique.

Test d’accès de base

Pour les tests d’accès de base, l’objectif est de découvrir quel élément est le plus élevé dans l’ordre z d’une interface utilisateur d’application. Si vous effectuez des tests d’accès pour une interaction avec la souris, vous pouvez utiliser un point, mais pour les tests d’accès orientés tactiles, il est souvent approprié d’utiliser une zone rectangulaire. Vous avez peut-être atteint des scénarios de test dans lesquels vous souhaitez savoir quel élément existe dans l’ordre z supérieur avant qu’un événement tactile ne se produise. Ou vous pouvez avoir un point que vous souhaitez développer pour être un rectangle pour voir ce qui se trouve près d’un point central et quel élément peut être la cible prévue.

Pour ce scénario, vous devez passer le rectangle qui vous intéresse comme valeur du paramètre intersectingRect . Pour le paramètre de sous-arborescence , vous pouvez le passer comme null. Vous pouvez également spécifier la sous-arborescence comme un élément dont vous savez qu’il s’agit du visuel racine d’une page ou d’un élément que vous souhaitez être l’arrêt final pour les tests d’accès.

L’ordre de l’élément dans l’IEnumerable des éléments UIElement retourné tient compte de l’espace de coordonnées dans la zone et de l’ordre z. Il est donc possible d’obtenir des résultats pour les éléments qui ne sont pas dans l’ordre z le plus élevé et qui ne peuvent donc pas être la source des événements d’entrée. Pour vous en assurer, vous pouvez effectuer un test d’accès filtré par élément pour tous les éléments de la liste retournée qui vous intéressent, en utilisant le même intersectingRect , mais en passant l’élément d’intérêt comme sous-arborescence.

Test d’accès avec filtrage d’éléments

Parfois, vous souhaitez savoir si un élément spécifique existe dans une zone de l’interface utilisateur. Si c’est le cas, vous pouvez spécifier cette zone d’intersectionRect et spécifier l’élément que vous recherchez comme paramètre de sous-arborescence . Si la valeur de retour n’est pas vide, cela signifie que l’élément existe quelque part dans cette zone. Lorsque vous testez une zone, l’ordre dans le jeu de retour n’est pas aussi utile pour déterminer l’ordre z, car le jeu inclut des éléments à plusieurs coordonnées x-y. L’ensemble a un mélange d’éléments dessinant à différentes coordonnées x-y et aussi d’éléments qui peuvent être entièrement ou partiellement retirés. Pour vraiment examiner une situation de overdraw, utilisez les surcharges de FindElementsInHostCoordinates qui utilisent un point, afin que les coordonnées x-y et l’ordre d’arborescence visuel ne soient plus un facteur. Consultez FindElementsInHostCoordinates(Point,UIElement).

Si la valeur de retour est vide, cela signifie que l’élément subtree n’existait pas dans la zone.

Si vous programmez à l’aide de C# ou de Microsoft Visual Basic, le type de valeur de retour de cette méthode est projeté sous la forme d’une collection générique IEnumerable qui contient des éléments UIElement . Si vous programmez à l’aide d’extensions de composant Visual C++ (C++/CX), le type de retour de cette méthode est IIterable<UIElement>.

Voir aussi

• Interactions avec la souris

public:
 static IIterable<UIElement ^> ^ FindElementsInHostCoordinates(Point intersectingPoint, UIElement ^ subtree, bool includeAllElements);

/// [Windows.Foundation.Metadata.DefaultOverload]
/// [Windows.Foundation.Metadata.Overload("FindAllElementsInHostCoordinatesPoint")]
 static IIterable<UIElement> FindElementsInHostCoordinates(Point const& intersectingPoint, UIElement const& subtree, bool const& includeAllElements);

[Windows.Foundation.Metadata.DefaultOverload]
[Windows.Foundation.Metadata.Overload("FindAllElementsInHostCoordinatesPoint")]
public static IEnumerable<UIElement> FindElementsInHostCoordinates(Point intersectingPoint, UIElement subtree, bool includeAllElements);

function findElementsInHostCoordinates(intersectingPoint, subtree, includeAllElements)

Public Shared Function FindElementsInHostCoordinates (intersectingPoint As Point, subtree As UIElement, includeAllElements As Boolean) As IEnumerable(Of UIElement)

Paramètres

Retours

Ensemble énumérable d’objets UIElement qui sont déterminés pour être situés dans la composition de l’arborescence visuelle au point spécifié, répertoriés par inverse de l’ordre z.

Attributs

DefaultOverloadAttribute OverloadAttribute

Exemples

Compte tenu de cette interface utilisateur XAML :

<Canvas Name="canvas">
  <Rectangle Name="outermost" Fill="Red" Width="200" Height="200"/>
  <Rectangle Canvas.Left="40" Canvas.Top="40" Name="hidden" Fill="Green" Width="120" Height="120"/>
  <Rectangle Canvas.Left="40" Canvas.Top="40" Name="shown" Fill="Orange" Width="120" Height="120"/>
  <Rectangle Canvas.Left="80" Canvas.Top="80" Name="center" Fill="Yellow" Width="40" Height="40"/>
  <Rectangle Canvas.Left="190" Canvas.Top="190" Name="bottomright" Fill="Pink" Width="10" Height="10"/>
</Canvas>

Voici quelques exemples d’utilisations et de résultats de FindElementsInHostCoordinates, en utilisant différentes valeurs de sous-arborescence :

private void Test(object sender, RoutedEventArgs e)
{
    IEnumerable<UIElement> hits;
    hits =  VisualTreeHelper.FindElementsInHostCoordinates(
      new Point(100,100), canvas, true);
    foreach (UIElement element in hits)
    {
        //run logic here, such as log the results 
    }
// results in the following set of elements, listed by Name:
// center - the element that is topmost in z-order at 100,100
// shown - also renders at 100,100 but is underneath 'center'
// hidden - is entirely underneath 'shown', 
//   and lower in z-order because 'hidden' declared before 'shown' in XAML
// outermost - draws under all the above at 100,100
// canvas - the 'subtree' value, so that's the last element reported

    hits = VisualTreeHelper.FindElementsInHostCoordinates(
      new Point(100, 100), center, true);
    foreach (UIElement element in hits) {
        //run logic here, such as log the results
    }
// results in 'center', because it is 'subtree' and also topmost

    hits = VisualTreeHelper.FindElementsInHostCoordinates(
      new Point(100, 100), bottomright, true);
// results in an empty set, 'bottomright' doesn't render at 100,100
}

Remarques

Un élément est considéré comme testable s’il occupe à la fois de l’espace dans la disposition et « produit de l’encre ». Pour les éléments qui ont un pinceau, tout pinceau non null est considéré comme quelque chose qui produit de l’encre, même si le pinceau ne produit pas de pixels visibles. Par exemple, un SolidColorBrush dont la couleur est définie sur Transparent produit toujours de l’encre. Seul un pinceau null ne produit pas d’encre. La propriété Opacity n’est pas prise en compte. L’élément produit toujours de l’encre même si l’opacité est 0.

Lorsque le paramètre includeAllElements a la valeur true, les éléments qui ne produisent pas d’encre sont pris en compte pour les tests d’accès. Dans ce cas, tant que l’élément répond aux exigences spatiales (le point croise les limites de l’élément), il et ses ancêtres sont inclus dans les résultats.

Voir aussi

• Point
• FindElementsInHostCoordinates(Point, UIElement)
• FindElementsInHostCoordinates(Rect, UIElement)
• FindElementsInHostCoordinates(Rect, UIElement, Boolean)
• Interactions avec la souris

public:
 static IIterable<UIElement ^> ^ FindElementsInHostCoordinates(Rect intersectingRect, UIElement ^ subtree, bool includeAllElements);

/// [Windows.Foundation.Metadata.Overload("FindAllElementsInHostCoordinatesRect")]
 static IIterable<UIElement> FindElementsInHostCoordinates(Rect const& intersectingRect, UIElement const& subtree, bool const& includeAllElements);

[Windows.Foundation.Metadata.Overload("FindAllElementsInHostCoordinatesRect")]
public static IEnumerable<UIElement> FindElementsInHostCoordinates(Rect intersectingRect, UIElement subtree, bool includeAllElements);

function findElementsInHostCoordinates(intersectingRect, subtree, includeAllElements)

Public Shared Function FindElementsInHostCoordinates (intersectingRect As Rect, subtree As UIElement, includeAllElements As Boolean) As IEnumerable(Of UIElement)

Paramètres

Retours

Ensemble énumérable d’objets UIElement qui sont déterminés pour se trouver dans la composition de l’arborescence visuelle dans le cadre Rect spécifié.

Attributs

OverloadAttribute

Exemples

Compte tenu de cette interface utilisateur XAML :

<Canvas Name="canvas">
  <Rectangle Name="outermost" Fill="Red" Width="200" Height="200"/>
  <Rectangle Canvas.Left="40" Canvas.Top="40" Name="hidden" Fill="Green" Width="120" Height="120"/>
  <Rectangle Canvas.Left="40" Canvas.Top="40" Name="shown" Fill="Orange" Width="120" Height="120"/>
  <Rectangle Canvas.Left="80" Canvas.Top="80" Name="center" Fill="Yellow" Width="40" Height="40"/>
  <Rectangle Canvas.Left="190" Canvas.Top="190" Name="bottomright" Fill="Pink" Width="10" Height="10"/>
</Canvas>

Voici quelques exemples d’utilisations et de résultats de FindElementsInHostCoordinates, en utilisant différentes valeurs de sous-arborescence :

private void Test(object sender, RoutedEventArgs e)
{
    IEnumerable<UIElement> hits;
    hits =  VisualTreeHelper.FindElementsInHostCoordinates(
      new Rect(75,75,50,50), canvas, true);
    foreach (UIElement element in hits)
    {
        //run logic here, such as log the results 
    }
// results in the following set of elements, listed by Name:
// center - the last declared XAML element is first returned, if within the area
// shown - renders, underneath 'center' in part of the area but visible on the edges
// hidden - entirely under 'shown', not visible but part of the area, an overdraw
// outermost - draws under all the above
// canvas - the 'subtree' value, and the last element reported

    hits = VisualTreeHelper.FindElementsInHostCoordinates(
      new Rect(75,75,50,50), center, true);
    foreach (UIElement element in hits) {
        //run logic here, such as log the results
    }
// results in only 'center', because it was 'subtree' and it's also topmost

    hits = VisualTreeHelper.FindElementsInHostCoordinates(
      new Rect(75,75,50,50), bottomright, true);
// results in an empty set, 'bottomright' isn't in the specified rect
}

Remarques

Un élément est considéré comme testable s’il occupe à la fois de l’espace dans la disposition et « produit de l’encre ». Pour les éléments qui ont un pinceau, tout pinceau non null est considéré comme quelque chose qui produit de l’encre, même si le pinceau ne produit pas de pixels visibles. Par exemple, un SolidColorBrush dont la couleur est définie sur Transparent produit toujours de l’encre. Seul un pinceau null ne produit pas d’encre. La propriété Opacity n’est pas prise en compte. L’élément produit toujours de l’encre même si l’opacité est 0.

Lorsque le paramètre includeAllElements a la valeur true, les éléments qui ne produisent pas d’encre sont pris en compte pour les tests d’accès. Dans ce cas, tant que l’élément répond aux exigences spatiales (le rect croise les limites de l’élément), il et ses ancêtres sont inclus dans les résultats.

Voir aussi

• FindElementsInHostCoordinates(Point, UIElement)
• FindElementsInHostCoordinates(Rect, UIElement)
• FindElementsInHostCoordinates(Point, UIElement, Boolean)
• Interactions avec la souris