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

Valori restituiti

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

Attributi

DefaultOverloadAttribute OverloadAttribute

Esempio

Si tratta di un metodo di utilità di esempio che determina se un elemento di un determinato Nome esiste in qualsiasi punto dell'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 inversamente dall'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 l'hit testing oppure esaminare tale ordine per altri motivi.

FindElementsInHostCoordinates è utile per tre scenari: hit testing di base, hit testing che filtra per un elemento specifico e determina se sono presenti elementi in una struttura ad albero visuale che si sovrapattino allo stesso punto.

Hit testing di base

Per l'hit testing 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 a essere l'elemento che disegna la parte superiore nell'interfaccia utente sottoposta a rendering, questo elemento è importante anche perché è l'origine evento segnalata se sono presenti interazioni utente, ad esempio eventi puntatore. Potrebbero essere presenti scenari di hit testing in cui si vuole conoscere l'elemento presente nell'ordine z superiore prima che si verifichi qualsiasi evento di input, in modo da poterlo prevedere e correggere eventuali errori nel posizionamento in ordine z.

Per questo scenario, è necessario passare il punto a cui si è interessati come valore del parametro intersectingPoint . Per il parametro del sottoalbero , è possibile passarlo come null. In alternativa, è possibile specificare un sottoalbero come elemento noto come l'oggetto visivo radice di una pagina oppure un elemento che si vuole essere l'arresto finale per l'hit testing.

L'elemento più in alto nell'ordine z è sempre il primo elemento nell'oggetto IEnumerable restituito degli elementi UIElement . Quindi, per l'hit testing di base si è in genere interessati solo a questo primo elemento. Tutti gli elementi aggiuntivi nell'oggetto IEnumerable sono altri elementi che si trovano anche in quel punto, ma sono più 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ù in alto.

Hit testing filtrato a livello di elemento

A volte vuoi sapere se un elemento specifico esiste in un determinato punto dell'interfaccia utente. In tal caso, è possibile specificare tale punto per intersecarePoint e specificare l'elemento che si sta cercando come parametro del sottoalbero . Se il valore restituito non è vuoto, significa che l'elemento esiste a quel punto nell'interfaccia utente. Se l'elemento è il primo elemento nel valore restituito, significa che l'elemento è in primo piano nell'ordine z in corrispondenza di IntersectingPoint. Se sono presenti altri elementi nel valore restituito e nel sottoalbero non è prima, gli altri elementi rappresentano il rendering degli elementi in corrispondenza di IntersectingPoint 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 corrispondenza di un valore z order.

Ricerca di sovrapposizioni o analisi della struttura ad albero visuale completa

Un'interfaccia utente può essere dinamica, soprattutto se si usano raccolte di data binding per il popolamento dell'interfaccia utente. Quindi occasionalmente c'è bisogno di sapere quale elemento è attualmente in cima. Potresti prevedere punti nell'app in cui l'utente potrebbe interagire e verificare che le interazioni che intendi 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 del sottoalbero , è possibile passarlo come null. In alternativa, è possibile specificare un sottoalbero come elemento noto come l'oggetto visivo radice di una pagina oppure un elemento che si vuole essere l'arresto finale per l'hit testing.

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

Se si esegue la programmazione con C#, il tipo di valore restituito di questo metodo viene proiettato come raccolta generica IEnumerable che contiene elementi UIElement . Se si esegue la programmazione con C++, il tipo restituito di questo metodo è IIterable<UIElement>.

Vedi anche

• Point
• Interazioni del 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

Valori restituiti

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

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);
    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 impilati uno sull'altro in un ordine z e anche più elementi completamente o parzialmente nella cornice 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 in base all'ordine della struttura ad albero visuale (in genere uguale all'inversa 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 l'hit testing oppure esaminare tale ordine per altri motivi.

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

Hit testing di base

Per l'hit testing di base, l'obiettivo è individuare l'elemento più alto nell'ordine z di un'interfaccia utente dell'app. Se si esegue un hit testing per un'interazione con il mouse, è possibile usare un punto, ma per i hit test orientati al tocco è spesso appropriato usare un'area rettangolare. Potresti avere scenari di hit testing in cui vuoi sapere quale elemento esiste nell'ordine z superiore prima che si verifichi qualsiasi evento tocco. Oppure potresti avere un punto che vuoi espandere in modo che sia un rettangolo per vedere cosa si trova vicino a un punto centrale e quale elemento potrebbe essere la destinazione desiderata.

Per questo scenario, è necessario passare il rettangolo a cui si è interessati come valore del parametro intersectingRect . Per il parametro del sottoalbero , è possibile passarlo come null. In alternativa, è possibile specificare un sottoalbero come elemento noto come l'oggetto visivo radice di una pagina oppure un elemento che si vuole essere l'arresto finale per l'hit testing.

L'ordine dell'elemento nell'oggetto IEnumerable restituito degli elementi UIElement rappresenta sia lo spazio delle coordinate nell'area che per l'ordine z. È quindi possibile ottenere riscontri per gli elementi che non sono all'ordine z più alto e quindi non possono 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.

Hit testing filtrato a livello di elemento

A volte vuoi 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 un punto qualsiasi dell'area. Quando si esegue il hit testing di un'area, l'ordine nel set di restituzione non è utile per determinare l'ordine z perché il set include elementi con più coordinate x-y. Il set include una combinazione di elementi che disegnano in varie coordinate x-y e anche elementi che potrebbero essere completamente o parzialmente ritirati. Per esaminare effettivamente una situazione di overdraw, usare gli overload di FindElementsInHostCoordinates che usano un punto, 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 del sottoalbero non esisteva nell'area.

Se si esegue la programmazione con C#, il tipo di valore restituito di questo metodo viene proiettato come raccolta generica IEnumerable che contiene elementi UIElement . Se si esegue la programmazione con C++, il tipo restituito di questo metodo è IIterable<UIElement>.

Vedi anche

• Interazioni del 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

Valori restituiti

Set enumerabile di oggetti UIElement che vengono determinati per essere posizionati nella composizione della struttura ad albero visuale nel punto specificato, elencato inversamente dall'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 sia lo spazio nel layout che "produce input penna". Per gli elementi che hanno 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 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 è Opacity è 0.

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

Vedi anche

• FindElementsInHostCoordinates(Point, UIElement)
• FindElementsInHostCoordinates(Rect, UIElement)
• FindElementsInHostCoordinates(Rect, UIElement, Boolean)
• Point
• Interazioni del 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

Valori restituiti

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 sia lo spazio nel layout che "produce input penna". Per gli elementi che hanno 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 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 è Opacity è 0.

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

Vedi anche

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