Freigeben über

VisualTreeHelper.FindElementsInHostCoordinates Methode

  • Referenz

Definition

Namespace:
Microsoft.UI.Xaml.Media

Überlädt

FindElementsInHostCoordinates(Point, UIElement)

Ruft eine Gruppe von Objekten ab, die sich innerhalb eines angegebenen x-y-Koordinatenpunkts einer App-Benutzeroberfläche befinden. Der Satz von -Objekten stellt die Komponenten einer visuellen Struktur dar, die diesen Punkt gemeinsam nutzen.
FindElementsInHostCoordinates(Rect, UIElement)

Ruft eine Gruppe von Objekten ab, die sich in einem angegebenen Rect-Frame einer App-Benutzeroberfläche befinden. Der Satz von -Objekten stellt die Komponenten einer visuellen Struktur dar, die einen rechteckigen Bereich gemeinsam nutzen, und kann Elemente enthalten, die überzeichnet werden.
FindElementsInHostCoordinates(Point, UIElement, Boolean)

Ruft eine Gruppe von Objekten ab, die sich innerhalb eines angegebenen x-y-Koordinatenpunkts einer App-Benutzeroberfläche befinden. Der Satz von -Objekten stellt die Komponenten einer visuellen Struktur dar, die diesen Punkt gemeinsam nutzen.
FindElementsInHostCoordinates(Rect, UIElement, Boolean)

Ruft eine Gruppe von Objekten ab, die sich in einem angegebenen Rect-Frame einer App-Benutzeroberfläche befinden. Der Satz von -Objekten stellt die Komponenten einer visuellen Struktur dar, die einen rechteckigen Bereich gemeinsam nutzen, und kann Elemente enthalten, die überzeichnet werden.

FindElementsInHostCoordinates(Point, UIElement)

Bearbeiten

Ruft eine Gruppe von Objekten ab, die sich innerhalb eines angegebenen x-y-Koordinatenpunkts einer App-Benutzeroberfläche befinden. Der Satz von -Objekten stellt die Komponenten einer visuellen Struktur dar, die diesen Punkt gemeinsam nutzen.

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)

Parameter

intersectingPoint
Point

Der Als Bestimmungspunkt zu verwendende Punkt. Dieser Punkt verwendet den Koordinatenraum des App-Fensters, nicht eines bestimmten Elements (und nicht der Unterstruktur , falls angegeben).

subtree
UIElement

Ein Objekt, nach dem gesucht werden soll. Wenn das Unterstrukturobjekt in der Gesamtmenge von Elementen vorhanden ist, die an den angegebenen sich überschneidendenPoint-Koordinaten vorhanden sind, enthält der Rückgabewert nur das Unterstrukturobjekt und alle Objekte, die eine höhere z-Reihenfolge als die Unterstruktur aufweisen, die durch Inverse der z-Reihenfolge aufgelistet sind. Wenn das Unterstrukturobjekt bei überschneidendenPoint-Koordinaten nicht vorhanden ist, ist der Rückgabewert leer.

Gibt zurück

IIterable<UIElement>

IEnumerable<UIElement>

Ein aufzählbarer Satz von UIElement-Objekten in der visuellen Strukturkomposition am angegebenen Punkt, der nach Inverse der Z-Reihenfolge aufgeführt wird.

Attribute
DefaultOverloadAttribute OverloadAttribute

Beispiele

Dies ist eine Beispiel-Hilfsprogrammmethode, die bestimmt, ob ein Element eines bestimmten Namens an einer beliebigen Stelle in der z-Reihenfolge an einem Punkt auf der Benutzeroberfläche einer App vorhanden ist.

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

Hinweise

Der Rückgabewert ist kein einzelnes Element, er ist eine Auflistung. Die Auflistung kann mehr als ein Element enthalten, da mehrere UI-Elemente in einer z-Reihenfolge übereinander gestapelt sein können. Die herkömmlichen Treffertestverfahren, die von den Eingabeereignishandlern verfügbar gemacht werden, z. B . der Absenderwert für ein PointerPressed-Ereignis , berücksichtigen nur das oberste Element, das die höchste z-Reihenfolge aufweist. FindElementsInHostCoordinates-Methoden geben den gesamten Stapel von Elementen zurück, die diesen Punkt oder Bereich auf der App-Benutzeroberfläche gemeinsam nutzen, die nach Inverse der z-Reihenfolge aufgelistet sind. Die Verwendung von FindElementsInHostCoordinates kann daher nützlich sein, um Fälle zu untersuchen, in denen Sie Elemente absichtlich oder unbeabsichtigt gestapelt haben. Sie können die Reihenfolge für rendering und Treffertests korrigieren oder diese Reihenfolge aus anderen Gründen untersuchen.

FindElementsInHostCoordinates ist für drei Szenarien nützlich: grundlegende Treffertests, Treffertests, die nach einem bestimmten Element filtern, und bestimmen, ob Elemente in einer visuellen Struktur vorhanden sind, die am selben Punkt überzeichnet werden.

Grundlegende Treffertests

Für grundlegende Treffertests besteht das Ziel darin, zu ermitteln, welches Element in der z-Reihenfolge einer App-Benutzeroberfläche an einem bestimmten Punkt in x-y-Koordinaten am höchsten ist. Dieses Element ist nicht nur das Element, das am höchsten auf der gerenderten Benutzeroberfläche zeichnet, es ist auch wichtig, da es die gemeldete Ereignisquelle ist, wenn Benutzerinteraktionen wie Zeigerereignisse vorhanden sind. Möglicherweise haben Sie Testszenarien getroffen, in denen Sie wissen möchten, welches Element in der obersten Z-Reihenfolge vorhanden ist, bevor ein Eingabeereignis stattfindet, sodass Sie es antizipieren und möglicherweise Fehler bei der Platzierung der Z-Reihenfolge korrigieren können.

In diesem Szenario sollten Sie den Punkt, den Sie für Treffertests interessieren, als Wert des IntersectingPoint-Parameters übergeben. Für den Unterstrukturparameter können Sie ihn als NULL übergeben. Oder Sie können eine Unterstruktur als Element angeben, von dem Sie wissen, dass es sich um das Stammvisual einer Seite handelt, oder um ein Element, das Sie als letzten Stopp für Treffertests verwenden möchten.

Das Element, das in der z-Reihenfolge an oberster Stelle steht, ist immer das erste Element in der zurückgegebenen IEnumerable von UIElement-Elementen . Für grundlegende Treffertests interessieren Sie sich also in der Regel nur für das erste Element. Alle zusätzlichen Elemente in der IEnumerable sind andere Elemente, die sich ebenfalls an diesem Punkt befinden, sich aber weiter zurück in der Z-Reihenfolge befinden und unter diesem ersten Element zeichnen. Die Elemente weiter hinten würden sich zu diesem Zeitpunkt nicht als Quelle für ein Eingabeereignis melden, nur das oberste Element.

Elementgefilterte Treffertests

Manchmal möchten Sie wissen, ob ein bestimmtes Element an einem bestimmten Punkt auf der Benutzeroberfläche vorhanden ist. In diesem Fall können Sie diesen Punkt für intersectingPoint angeben und das gesuchte Element als Unterstrukturparameter angeben. Wenn der Rückgabewert nicht leer ist, bedeutet dies, dass das Element zu diesem Zeitpunkt auf der Benutzeroberfläche vorhanden ist. Wenn das Element das erste Element im Rückgabewert ist, bedeutet dies, dass das Element in der z-Reihenfolge an intersectingPoint an oberster Stelle steht. Wenn im Rückgabewert andere Elemente vorhanden sind und die Unterstruktur nicht zuerst ist, stellen die anderen Elemente die Elemente dar, die an IntersectingPoint gerendert werden, die in z-Reihenfolge höher sind (visuell werden diese über dem Unterstrukturelement gerendert). In diesem Fall ist die Unterstruktur das letzte Element in der zurückgegebenen IEnumerable, nicht das erste.

Wenn der Rückgabewert leer ist, bedeutet dies, dass das Unterstrukturelement dort bei keinem z-order-Wert vorhanden war.

Suchen nach Überzeichnung oder Betrachten der vollständigen visuellen Struktur

Eine Benutzeroberfläche kann dynamisch sein, insbesondere wenn Sie Sammlungen aus der Datenbindung für die Benutzeroberflächenbefüllung verwenden. Daher müssen Sie gelegentlich wissen, welches Element sich derzeit an der Spitze befindet. Möglicherweise erwarten Sie Punkte in der App, an denen der Benutzer interagiert, und überprüfen, ob die von Ihnen gewünschten Interaktionen derzeit möglich sind. In diesem Szenario geben Sie in der Regel einen Punktwert an, der einen bekannten Punkt darstellt, z. B. (0,0), der derzeit eine gültige Koordinate ist, die sich in Ihrem App-Fenster befindet. Für den Unterstrukturparameter können Sie ihn als NULL übergeben. Oder Sie können eine Unterstruktur als Element angeben, von dem Sie wissen, dass es sich um das Stammvisual einer Seite handelt, oder um ein Element, das Sie als letzten Stopp für Treffertests verwenden möchten.

Hinweis

Wenn Sie NULL für unterstruktur übergeben, sehen Sie möglicherweise, dass die visuelle Struktur Elemente enthält, die nicht durch XAML auf Seitenebene definiert sind, z. B. ein Frame-Element und ContentPresenter. Diese stammen aus dem typischen App-Initialisierungscode, der in den meisten Microsoft Visual Studio-Projektvorlagen für eine UWP-App vorhanden ist. Dadurch wird zunächst der Frame als Window.Content-Wert erstellt. Die visuelle Struktur, wie sie von findElementsInHostCoordinates-Methoden gezeigt wird, erstreckt sich bis zu Window.Content, es sei denn, Sie filtern sie anderweitig mit einem Untergeordnetenstrukturelement wie einem Page-Stamm .

Beim Rückgabewert sind Sie möglicherweise an den einzelnen Elementen interessiert. Sie können foreach oder ähnliche sprachspezifische Techniken verwenden, um die Auflistung zu durchlaufen und ihre eigene Logik für jedes dieser Elemente auszuführen. Denken Sie daran, dass das erste Element in dieser Auflistung das element ist, das in z-Reihenfolge an oberster Stelle steht.

Wenn Sie mit C# oder Microsoft Visual Basic programmieren, wird der Rückgabewerttyp dieser Methode als generische IEnumerable-Auflistung projiziert, die UIElement-Elemente enthält. Wenn Sie mit Visual C++-Komponentenerweiterungen (C++/CX) programmieren, ist der Rückgabetyp dieser Methode IIterable.

Weitere Informationen

Gilt für:

FindElementsInHostCoordinates(Rect, UIElement)

Bearbeiten

Ruft eine Gruppe von Objekten ab, die sich in einem angegebenen Rect-Frame einer App-Benutzeroberfläche befinden. Der Satz von -Objekten stellt die Komponenten einer visuellen Struktur dar, die einen rechteckigen Bereich gemeinsam nutzen, und kann Elemente enthalten, die überzeichnet werden.

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)

Parameter

intersectingRect
Rect

Der Rect , der als Bestimmungsbereich verwendet werden soll. Dieser Frame verwendet den Koordinatenraum des App-Fensters, nicht eines bestimmten Elements (und nicht der Unterstruktur , falls angegeben).

subtree
UIElement

Ein Objekt, nach dem gesucht werden soll. Wenn das Unterstrukturobjekt in der Gesamtmenge von Elementen vorhanden ist, die innerhalb des angegebenen intersectingRect vorhanden sind, enthält der Rückgabewert nur das Unterstrukturobjekt und die Elemente, die über dem Raum zeichnen. Wenn das Unterstrukturobjekt nicht innerhalb des intersectingRect-Frames vorhanden ist, ist der Rückgabewert leer.

Gibt zurück

IIterable<UIElement>

IEnumerable<UIElement>

Ein aufzählbarer Satz von UIElement-Objekten , die sich in der visuellen Strukturkomposition im angegebenen Rect-Frame befinden.

Attribute
OverloadAttribute

Beispiele

Anhand dieser XAML-Benutzeroberfläche:

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

Hier sind einige Beispielverwendungen und Ergebnisse von FindElementsInHostCoordinates, die verschiedene Unterstrukturwerte verwenden:

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
}

Hinweise

Der Rückgabewert ist kein einzelnes Element, er ist eine Auflistung. Die Auflistung kann mehr als ein Element aufweisen, da mehrere UI-Elemente in einer z-Reihenfolge übereinander gestapelt sein können, und auch mehrere Elemente, die vollständig oder teilweise im intersectingRect-Frame übereinander gestapelt sind. Die herkömmlichen Treffertestverfahren, die von den Eingabeereignishandlern verfügbar gemacht werden, z. B . der Absenderwert für ein PointerPressed-Ereignis , berücksichtigen nur das oberste Element, das die höchste z-Reihenfolge aufweist. FindElementsInHostCoordinates-Methoden geben den gesamten Stapel von Elementen zurück, die diesen Punkt oder Bereich auf der App-Benutzeroberfläche gemeinsam nutzen, die nach visueller Strukturreihenfolge aufgelistet sind (was normalerweise mit der Umgekehrtkeit der XAML-Deklarationsreihenfolge identisch ist). Die Verwendung von FindElementsInHostCoordinates kann daher nützlich sein, um Fälle zu untersuchen, in denen Sie Elemente absichtlich oder unbeabsichtigt gestapelt haben. Sie können die Reihenfolge für rendering und Treffertests korrigieren oder diese Reihenfolge aus anderen Gründen untersuchen.

FindElementsInHostCoordinates über einen Bereich ist für zwei Szenarien nützlich: grundlegende Treffertests und Treffertests, die nach einem bestimmten Element filtern.

Grundlegende Treffertests

Für grundlegende Treffertests besteht das Ziel darin, zu ermitteln, welches Element in der Z-Reihenfolge einer App-Benutzeroberfläche am höchsten ist. Wenn Sie Treffertests für eine Mausinteraktion durchführen, verwenden Sie möglicherweise einen Punkt, aber für touchorientierte Treffertests ist es häufig angebracht, einen rechteckigen Bereich zu verwenden. Möglicherweise haben Sie Testszenarien getroffen, in denen Sie wissen möchten, welches Element in der obersten Z-Reihenfolge vorhanden ist, bevor ein Touchereignis stattfindet. Oder Sie haben einen Punkt, den Sie erweitern möchten, um ein Rechteck zu sein, um zu sehen, was sich in der Nähe eines Mittelpunkts befindet und welches Element das beabsichtigte Ziel sein könnte.

In diesem Szenario sollten Sie das Rechteck, für das Sie treffertesten möchten, als Wert des parameters intersectingRect übergeben. Für den Unterstrukturparameter können Sie ihn als NULL übergeben. Oder Sie können eine Unterstruktur als Element angeben, von dem Sie wissen, dass es sich um das Stammvisual einer Seite handelt, oder um ein Element, das Sie als letzten Stopp für Treffertests verwenden möchten.

Die Reihenfolge des Elements in der zurückgegebenen IEnumerable von UIElement-Elementen berücksichtigt sowohl den Koordinatenraum im Bereich als auch die Z-Reihenfolge. So ist es möglich, Treffer für Elemente zu erhalten, die nicht die höchste Z-Reihenfolge aufweisen und daher nicht die Quelle von Eingabeereignissen sein können. Um sicherzustellen, können Sie einen elementgefilterten Treffertest für alle Elemente aus der zurückgegebenen Liste durchführen, die Sie interessieren, indem Sie denselben intersectingRect verwenden, aber das interessante Element als Unterstruktur übergeben.

Elementgefilterte Treffertests

Manchmal möchten Sie wissen, ob ein bestimmtes Element in einem Bereich der Benutzeroberfläche vorhanden ist. In diesem Fall können Sie diesen Bereich für intersectingRect angeben und das gesuchte Element als Unterstrukturparameter angeben. Wenn der Rückgabewert nicht leer ist, bedeutet dies, dass das Element irgendwo in diesem Bereich vorhanden ist. Wenn Sie einen Bereich testen, ist die Reihenfolge im Rückgabesatz nicht so nützlich, um Z-Reihenfolge zu bestimmen, da der Satz Elemente mit mehr als einer x-y-Koordinate enthält. Das Set enthält eine Mischung aus Elementen, die auf verschiedenen xy-Koordinaten zeichnen, und auch Elementen, die vollständig oder teilweise überzeichnet werden können. Um eine Überzeichnungssituation wirklich zu untersuchen, verwenden Sie die Überladungen von FindElementsInHostCoordinaten , die einen Punkt verwenden, sodass die x-y-Koordinaten und die visuelle Strukturreihenfolge kein Faktor mehr sind. Siehe FindElementsInHostCoordinates(Point,UIElement).

Wenn der Rückgabewert leer ist, bedeutet dies, dass das Unterstrukturelement im Bereich nicht vorhanden war.

Wenn Sie mit C# oder Microsoft Visual Basic programmieren, wird der Rückgabewerttyp dieser Methode als generische IEnumerable-Auflistung projiziert, die UIElement-Elemente enthält. Wenn Sie mit Visual C++-Komponentenerweiterungen (C++/CX) programmieren, ist der Rückgabetyp dieser Methode IIterable.

Weitere Informationen

Gilt für:

FindElementsInHostCoordinates(Point, UIElement, Boolean)

Bearbeiten

Ruft eine Gruppe von Objekten ab, die sich innerhalb eines angegebenen x-y-Koordinatenpunkts einer App-Benutzeroberfläche befinden. Der Satz von -Objekten stellt die Komponenten einer visuellen Struktur dar, die diesen Punkt gemeinsam nutzen.

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)

Parameter

intersectingPoint
Point

Der Als Bestimmungspunkt zu verwendende Punkt. Dieser Punkt verwendet den Koordinatenraum des App-Fensters, nicht eines bestimmten Elements (und nicht der Unterstruktur , falls angegeben).

subtree
UIElement

Ein Objekt, nach dem gesucht werden soll. Wenn das Unterstrukturobjekt in der Gesamtmenge von Elementen vorhanden ist, die an den angegebenen sich überschneidendenPoint-Koordinaten vorhanden sind, enthält der Rückgabewert nur das Unterstrukturobjekt und alle Objekte, die eine höhere z-Reihenfolge als die Unterstruktur aufweisen, die durch Inverse der z-Reihenfolge aufgelistet sind. Wenn das Unterstrukturobjekt bei überschneidendenPoint-Koordinaten nicht vorhanden ist, ist der Rückgabewert leer.

includeAllElements
Boolean

bool

true , um alle Elemente einzuschließen, die sich überschneiden, einschließlich der Elemente, die für tests als unsichtbar gelten. false , um nur sichtbare, treffertestbare Elemente zu finden. Die Standardeinstellung ist false.

Gibt zurück

IIterable<UIElement>

IEnumerable<UIElement>

Ein aufzählbarer Satz von UIElement-Objekten , die bestimmt werden, dass sie sich in der visuellen Strukturkomposition an dem angegebenen Punkt befinden, der durch Inverse der z-Reihenfolge aufgelistet wird.

Attribute
DefaultOverloadAttribute OverloadAttribute

Beispiele

Anhand dieser XAML-Benutzeroberfläche:

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

Hier sind einige Beispielverwendungen und Ergebnisse von FindElementsInHostCoordinates, die verschiedene Unterstrukturwerte verwenden:

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
}

Hinweise

Ein Element gilt als Treffertest, wenn es sowohl Platz im Layout belegt als auch Freihand erzeugt. Für Elemente, die über einen Pinsel verfügen, wird jeder Pinsel ohne Null als Freihand betrachtet, auch wenn der Pinsel keine sichtbaren Pixel erzeugt. Beispielsweise erzeugt ein SolidColorBrush , dessen Farbe auf Transparent festgelegt ist, weiterhin Freihand. Nur ein NULL-Pinsel erzeugt keine Freihand. Die Deckkrafteigenschaft wird nicht berücksichtigt. Das Element erzeugt weiterhin Freihand, auch wenn die Deckkraft 0 ist.

Wenn der includeAllElements-Parameter auf true festgelegt ist, werden Elemente, die keine Freihand erzeugen, für Treffertests berücksichtigt. In diesem Fall, solange das Element die räumlichen Anforderungen erfüllt (der Punkt überschneidet die Elementgrenzen), werden es und seine Vorgänger in die Ergebnisse einbezogen.

Hinweis

Einige spezielle Elemente, wie SwapChainPanel und MediaPlayerElement, verfügen nicht über einen Pinsel, können aber trotzdem Freihand erzeugen.

Weitere Informationen

Gilt für:

FindElementsInHostCoordinates(Rect, UIElement, Boolean)

Bearbeiten

Ruft eine Gruppe von Objekten ab, die sich in einem angegebenen Rect-Frame einer App-Benutzeroberfläche befinden. Der Satz von -Objekten stellt die Komponenten einer visuellen Struktur dar, die einen rechteckigen Bereich gemeinsam nutzen, und kann Elemente enthalten, die überzeichnet werden.

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)

Parameter

intersectingRect
Rect

Der Rect , der als Bestimmungsbereich verwendet werden soll. Dieser Frame verwendet den Koordinatenraum des App-Fensters, nicht eines bestimmten Elements (und nicht der Unterstruktur , falls angegeben).

subtree
UIElement

Ein Objekt, nach dem gesucht werden soll. Wenn das Unterstrukturobjekt in der Gesamtmenge von Elementen vorhanden ist, die innerhalb des angegebenen intersectingRect vorhanden sind, enthält der Rückgabewert nur das Unterstrukturobjekt und die Elemente, die über dem Raum zeichnen. Wenn das Unterstrukturobjekt nicht innerhalb des intersectingRect-Frames vorhanden ist, ist der Rückgabewert leer.

includeAllElements
Boolean

bool

true , um alle Elemente einzuschließen, die sich überschneiden, einschließlich der Elemente, die für tests als unsichtbar gelten. false , um nur sichtbare, treffertestbare Elemente zu finden. Die Standardeinstellung ist false.

Gibt zurück

IIterable<UIElement>

IEnumerable<UIElement>

Ein aufzählbarer Satz von UIElement-Objekten , die bestimmt werden, dass sie sich in der visuellen Strukturkomposition im angegebenen Rect-Frame befinden.

Attribute
OverloadAttribute

Beispiele

Anhand dieser XAML-Benutzeroberfläche:

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

Hier sind einige Beispielverwendungen und Ergebnisse von FindElementsInHostCoordinates, die verschiedene Unterstrukturwerte verwenden:

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
}

Hinweise

Ein Element gilt als Treffertest, wenn es sowohl Platz im Layout belegt als auch Freihand erzeugt. Für Elemente, die über einen Pinsel verfügen, wird jeder Pinsel ohne Null als Freihand betrachtet, auch wenn der Pinsel keine sichtbaren Pixel erzeugt. Beispielsweise erzeugt ein SolidColorBrush , dessen Farbe auf Transparent festgelegt ist, weiterhin Freihand. Nur ein NULL-Pinsel erzeugt keine Freihand. Die Deckkrafteigenschaft wird nicht berücksichtigt. Das Element erzeugt weiterhin Freihand, auch wenn die Deckkraft 0 ist.

Wenn der includeAllElements-Parameter auf true festgelegt ist, werden Elemente, die keine Freihand erzeugen, für Treffertests berücksichtigt. In diesem Fall, solange das Element die räumlichen Anforderungen erfüllt (das Rect überschneidet die Elementgrenzen), werden es und seine Vorgänger in die Ergebnisse einbezogen.

Hinweis

Einige spezielle Elemente, wie SwapChainPanel und MediaPlayerElement, verfügen nicht über einen Pinsel, können aber trotzdem Freihand erzeugen.

Weitere Informationen

Gilt für: