VisualTreeHelper.FindElementsInHostCoordinates Metodo

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)

Parametri

Restituisce

Set enumerabile di oggetti UIElement nella composizione dell'albero visivo nel punto specificato, elencato inverso di z-order.

Attributi

DefaultOverloadAttribute OverloadAttribute

Esempio

Si tratta di un metodo di utilità di esempio che determina se un elemento di un determinato Nome esiste ovunque nell'ordine z in un punto nell'interfaccia utente di un'app.

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;
}

Commenti

Il valore restituito non è un singolo elemento, è una raccolta. La raccolta può avere più elementi perché possono essere presenti più elementi dell'interfaccia utente sovrapposti tra loro in un ordine z. Le tecniche di hit testing convenzionali esposte dai gestori eventi di input, ad esempio il valore del mittente per un evento PointerPressed , rappresentano solo l'elemento più alto con l'ordine z più alto. I metodi FindElementsInHostCoordinates restituiscono l'intero stack di elementi che condividono tale punto o area nell'interfaccia utente dell'app, elencati inverso dell'ordine z. L'uso di FindElementsInHostCoordinates può quindi essere utile per esaminare i casi in cui sono stati intenzionalmente o involontariamente impilati elementi. È possibile correggere l'ordine per il rendering e il hit test oppure esaminare tale ordine per altri motivi.

FindElementsInHostCoordinates è utile per tre scenari: test di hit test di base, hit testing che filtrano per un elemento specifico e determinano se sono presenti elementi in un albero visivo che si sovrascrivono allo stesso punto.

Test di base degli hit test

Per i test di base, l'obiettivo è individuare l'elemento più alto nell'ordine z di un'interfaccia utente dell'app in un determinato punto nelle coordinate x-y. Oltre ad essere l'elemento che disegna la maggior parte dell'interfaccia utente di cui è stato eseguito il rendering, questo elemento è importante anche perché è l'origine evento segnalata se sono presenti interazioni utente, ad esempio eventi puntatore. È possibile che siano presenti scenari di test di hit test in cui si vuole conoscere l'elemento presente nella parte superiore dell'ordine z prima che si verifichi qualsiasi evento di input, in modo che sia possibile anticiparlo e correggere eventuali errori nel posizionamento in z-order.

Per questo scenario, è necessario passare il punto che si è interessati a hit-testing come valore del parametro intersectingPoint . Per il parametro sottoalbero , è possibile passarlo come Null. Oppure è possibile specificare il sottoalbero per essere un elemento che si sa è l'oggetto visivo radice di una pagina oppure è in caso contrario un elemento che si vuole essere l'arresto finale per il hit testing.

L'elemento che è superiore all'ordine z è sempre il primo elemento nell'elemento IEnumerable restituito degli elementi UIElement . Quindi per i test di base di hit test di solito si è interessati solo a quel primo elemento. Tutti gli elementi aggiuntivi nell'oggetto IEnumerable sono altri elementi che si trovano anche a quel punto, ma sono ancora indietro nell'ordine z e stanno disegnando sotto tale primo elemento. Gli elementi più indietro non segnalano se stessi come origine per un evento di input a quel punto, solo l'elemento più superiore sarebbe.

Test di hit test filtrati dall'elemento

A volte si vuole sapere se esiste un elemento specifico in un determinato punto nell'interfaccia utente. In tal caso, è possibile specificare tale punto per intersecarePoint e specificare l'elemento che si sta cercando come parametro di sottoalbero . Se il valore restituito non è vuoto, significa che l'elemento esiste a quel punto nell'interfaccia utente. Se l'elemento è il primo elemento del valore restituito, significa che l'elemento è superiore all'ordine z in corrispondenza dell'intersecazione diPoint. Se nel valore restituito e nel sottoalbero non sono presenti altri elementi, gli altri elementi rappresentano il rendering degli elementi in corrispondenza dell'intersecazione diPoint che sono superiori nell'ordine z (visivamente, questi vengono visualizzati sopra l'elemento sottoalbero ). In questo caso il sottoalbero è l'ultimo elemento nell'oggetto IEnumerable restituito, non il primo.

Se il valore restituito è vuoto, significa che l'elemento sottoalbero non esiste, in qualsiasi valore dell'ordine z.

Cercare overdraw o esaminare l'albero visivo completo

Un'interfaccia utente può essere dinamica, soprattutto se si usano raccolte dal data binding per la popolazione dell'interfaccia utente. Pertanto, occasionalmente è necessario sapere quale elemento è attualmente in alto. È possibile prevedere punti nell'app in cui l'utente potrebbe interagire e verificare che le interazioni che si intende siano attualmente possibili. Per questo scenario, in genere si specifica un valore Point che rappresenta un punto noto, ad esempio (0,0) che è attualmente una coordinata valida all'interno della finestra dell'app. Per il parametro sottoalbero , è possibile passarlo come Null. Oppure è possibile specificare il sottoalbero per essere un elemento che si sa è l'oggetto visivo radice di una pagina oppure è in caso contrario un elemento che si vuole essere l'arresto finale per il hit testing.

Nel valore restituito, è possibile che ognuno degli elementi all'interno sia interessato. È quindi possibile usare tecniche specifiche del linguaggio per eseguire l'iterazione della raccolta ed eseguire la propria logica in ognuno di questi elementi. Tenere presente che il primo elemento di tale raccolta è quello che è superiore all'ordine z.

Se si sta programmando usando C# o Microsoft Visual Basic, il tipo di valore restituito di questo metodo viene proiettato come raccolta generica IEnumerable che contiene elementi UIElement . Se si sta programmando con estensioni del componente Visual C++ (C++/CX), il tipo restituito di questo metodo è IIterable<UIElement>.

Vedi anche

• Point
• Interazioni tramite mouse

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)

Parametri

Restituisce

Set enumerabile di oggetti UIElement che si trovano nella composizione della struttura ad albero visuale nella cornice Rect specificata.

Attributi

OverloadAttribute

Esempio

Dato questo interfaccia utente 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>

Ecco alcuni esempi di utilizzo e risultati di FindElementsInHostCoordinates usando valori di sottoalbero diversi:

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
}

Commenti

Il valore restituito non è un singolo elemento, è una raccolta. La raccolta può avere più elementi perché possono essere presenti più elementi dell'interfaccia utente sovrapposti tra loro in un ordine z e anche più elementi completamente o parzialmente nel frame intersectingRect . Le tecniche di hit testing convenzionali esposte dai gestori eventi di input, ad esempio il valore del mittente per un evento PointerPressed , rappresentano solo l'elemento più alto con l'ordine z più alto. I metodi FindElementsInHostCoordinates restituiscono l'intero stack di elementi che condividono tale punto o area nell'interfaccia utente dell'app, elencati dall'ordine dell'albero visivo (che in genere corrisponde all'inverso dell'ordine di dichiarazione XAML). L'uso di FindElementsInHostCoordinates può quindi essere utile per esaminare i casi in cui sono stati intenzionalmente o involontariamente impilati elementi. È possibile correggere l'ordine per il rendering e il hit test oppure esaminare tale ordine per altri motivi.

FindElementsInHostCoordinates su un'area è utile per due scenari: test di hit test di base e test di hit test che filtrano per un elemento specifico.

Test di base degli hit test

Per i test di hit test di base, l'obiettivo è individuare quale elemento è più alto nell'ordine z di un'interfaccia utente dell'app. Se si esegue il hit test per un'interazione del mouse, è possibile usare un punto, ma per i test di hit orientata al tocco è spesso appropriato usare un'area rettangolare. È possibile che siano presenti scenari di test di hit test in cui si vuole conoscere l'elemento presente nella parte superiore dell'ordine z prima che si verifichi qualsiasi evento touch. In alternativa, potrebbe essere presente un punto che si vuole espandere per essere un rettangolo per vedere cosa è vicino a un punto centrale e quale elemento potrebbe essere la destinazione prevista.

Per questo scenario, è necessario passare il rettangolo interessato a hit-testing come valore del parametro intersectingRect . Per il parametro sottoalbero , è possibile passarlo come Null. Oppure è possibile specificare il sottoalbero per essere un elemento che si sa è l'oggetto visivo radice di una pagina oppure è in caso contrario un elemento che si vuole essere l'arresto finale per il hit testing.

L'ordine dell'elemento nell'oggetto IEnumerable restituito degli elementi UIElement è contabile sia per lo spazio di coordinate nell'area che per l'ordine z. È quindi possibile ottenere i riscontri per gli elementi che non sono al massimo ordine z e quindi non potevano essere l'origine degli eventi di input. Per assicurarsi, è possibile eseguire un hit test filtrato dagli elementi per tutti gli elementi dell'elenco restituito a cui si è interessati, usando lo stesso elemento intersectingRect ma passando l'elemento di interesse come sottoalbero.

Test di hit test filtrati dall'elemento

A volte si vuole sapere se esiste un elemento specifico all'interno di un'area dell'interfaccia utente. In tal caso, è possibile specificare tale area per intersectingRect e specificare l'elemento che si sta cercando come parametro del sottoalbero . Se il valore restituito non è vuoto, significa che l'elemento esiste in tale area. Quando si esegue il hit testing di un'area, l'ordine nel set restituito non è utile per determinare l'ordine z perché il set include elementi con più coordinate x-y. Il set ha una combinazione di elementi che disegnano a varie coordinate x-y e anche elementi che potrebbero essere completamente o parzialmente ritirati. Per esaminare realmente una situazione di sovrapposizione, usare gli overload di FindElementsInHostCoordinates che usano un point, in modo che le coordinate x-y e l'ordine della struttura ad albero visuale non siano più un fattore. Vedere FindElementsInHostCoordinates(Point,UIElement).

Se il valore restituito è vuoto, significa che l'elemento sottoalbero non esiste nell'area.

Se si esegue la programmazione con C# o Microsoft Visual Basic, il tipo di valore restituito di questo metodo viene proiettato come raccolta generica IEnumerable che contiene elementi UIElement . Se si programmano usando estensioni del componente Visual C++ (C++/CX), il tipo restituito di questo metodo è IIterable<UIElement>.

Vedi anche

• Interazioni tramite mouse

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)

Parametri

Restituisce

Set enumerabile di oggetti UIElement che vengono determinati per essere posizionati nella composizione della struttura ad albero visuale nel punto specificato, elencato dall'inverso dell'ordine z.

Attributi

DefaultOverloadAttribute OverloadAttribute

Esempio

Data questa interfaccia utente 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>

Ecco alcuni esempi di utilizzo e risultati di FindElementsInHostCoordinates, usando valori di sottoalbero diversi:

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
}

Commenti

Un elemento è considerato hit testable se occupa spazio nel layout e "produce input penna". Per gli elementi con un oggetto Brush, qualsiasi pennello non Null viene considerato un elemento che produce input penna, anche se brush non produce pixel visibili. Ad esempio, un oggetto SolidColorBrush con il relativo colore impostato su Transparent produce ancora input penna. Solo un pennello Null non produce input penna. La proprietà Opacity non viene considerata. L'elemento produce ancora input penna anche se è Opacità è 0.

Quando il parametro includeAllElements è impostato su true, gli elementi che non producono input penna vengono considerati per l'hit test. In questo caso, purché l'elemento soddisfi i requisiti spaziali (il punto interseca i limiti dell'elemento), i relativi predecessori vengono inclusi nei risultati.

Vedi anche

• Point
• FindElementsInHostCoordinates(Point, UIElement)
• FindElementsInHostCoordinates(Rect, UIElement)
• FindElementsInHostCoordinates(Rect, UIElement, Boolean)
• Interazioni tramite mouse

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)

Parametri

Restituisce

Set enumerabile di oggetti UIElement che vengono determinati per essere posizionati nella composizione della struttura ad albero visuale nel frame Rect specificato.

Attributi

OverloadAttribute

Esempio

Data questa interfaccia utente 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>

Ecco alcuni esempi di utilizzo e risultati di FindElementsInHostCoordinates, usando valori di sottoalbero diversi:

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
}

Commenti

Un elemento è considerato hit testable se occupa spazio nel layout e "produce input penna". Per gli elementi con un oggetto Brush, qualsiasi pennello non Null viene considerato un elemento che produce input penna, anche se brush non produce pixel visibili. Ad esempio, un oggetto SolidColorBrush con il relativo colore impostato su Transparent produce ancora input penna. Solo un pennello Null non produce input penna. La proprietà Opacity non viene considerata. L'elemento produce ancora input penna anche se è Opacità è 0.

Quando il parametro includeAllElements è impostato su true, gli elementi che non producono input penna vengono considerati per l'hit test. In questo caso, purché l'elemento soddisfi i requisiti spaziali (il rect interseca i limiti degli elementi), quindi vengono inclusi nei risultati i relativi predecessori.

Vedi anche

• FindElementsInHostCoordinates(Point, UIElement)
• FindElementsInHostCoordinates(Rect, UIElement)
• FindElementsInHostCoordinates(Point, UIElement, Boolean)
• Interazioni tramite mouse