VisualTreeHelper.FindElementsInHostCoordinates Метод

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)

Параметры

Возвращаемое значение

Перечисляемый набор объектов UIElement в состав визуального дерева в указанной точке, указанный в обратном порядке z-порядка.

Атрибуты

DefaultOverloadAttribute OverloadAttribute

Примеры

Это пример метода служебной программы, который определяет, существует ли элемент заданного имени в любом месте z-порядка в точке в пользовательском интерфейсе приложения.

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

Комментарии

Возвращаемое значение не является одним элементом, это коллекция. Коллекция может иметь несколько элементов, так как в z-порядке может быть несколько элементов пользовательского интерфейса. Обычные методы тестирования попаданий, предоставляемые обработчиками входных событий, например значение отправителя для события PointerPressed , учитывают только самый верхний элемент, имеющий самый высокий z-порядок. Методы FindElementsInHostCoordinates возвращают весь стек элементов, совместно использующих эту точку или область в пользовательском интерфейсе приложения, перечисленные в обратном порядке z-порядка. Таким образом, использование FindElementsInHostCoordinates может быть полезно для изучения случаев, когда вы намеренно или непреднамеренно стекали элементы. Вам может потребоваться исправить порядок отрисовки и тестирования попаданий или проверить этот порядок по другим причинам.

FindElementsInHostCoordinates удобно использовать для трех сценариев: базовое тестирование попаданий, тестирование попаданий, фильтрующее для определенного элемента, и определение наличия элементов в визуальном дереве, перерасходе которых выполняется в той же точке.

Базовое тестирование попаданий

Для базового тестирования попаданий цель состоит в том, чтобы определить, какой элемент является самым высоким в порядке z пользовательского интерфейса приложения в заданной точке в координатах x-y. Помимо того, что элемент, который рисует самую верхнюю часть в отрисованном пользовательском интерфейсе, этот элемент также важен, так как это сообщаемый источник событий, если существуют пользовательские взаимодействия, такие как события указателя. Возможно, вы столкнулись с сценариями тестирования, в которых вы хотите знать, какой элемент существует в верхнем z-порядке, прежде чем происходит любое событие ввода, чтобы вы могли ожидать его и, возможно, исправлять ошибки в размещении z-order.

В этом сценарии необходимо передать точку, которую вы хотите проверить в качестве значения параметра intersectingPoint . Для параметра поддерев можно передать его как null. Или можно указать поддерев , чтобы быть некоторым элементом, который вы знаете, является корневым визуальным элементом страницы или иным образом элемент, который вы хотите быть окончательной остановкой для тестирования попаданий.

Элемент, который является самым верхним в z-порядке, всегда является первым элементом в возвращаемом IEnumerable элементов UIElement . Поэтому для базового тестирования хитов вы обычно заинтересованы только в этом самом первом элементе. Все дополнительные элементы в IEnumerable являются другими элементами, которые также находятся в этом моменте, но еще больше возвращаются в z-порядке и рисуются под этим первым элементом. Элементы еще больше не сообщают себя в качестве источника для входного события в этой точке, только самый верхний элемент будет.

Тестирование попаданий, отфильтрованное элементом

Иногда необходимо знать, существует ли определенный элемент в определенной точке пользовательского интерфейса. Если это так, можно указать эту точку для пересеченияPoint и указать элемент, который вы ищете в качестве параметра поддерев . Если возвращаемое значение не является пустым, это означает, что элемент существует на этом этапе в пользовательском интерфейсе. Если элемент является первым элементом в возвращаемом значении, это означает, что элемент является самым верхним в порядке z при пересеченииPoint. Если в возвращаемом значении есть другие элементы и поддерев не первый, другие элементы представляют элементы, отрисовываемые при пересечении Точек , которые выше в z-порядке (визуально эти отрисовки поверх элемента поддерев ). В этом случае поддерев является последним элементом возвращаемого IEnumerable, а не первого.

Если возвращаемое значение пусто, это означает, что элемент поддерев не существовал, при любом значении z-порядка.

Ищете перерисовку или посмотрите на полное визуальное дерево

Пользовательский интерфейс может быть динамическим, особенно если вы используете коллекции из привязки данных для заполнения пользовательского интерфейса. Поэтому иногда необходимо знать, какой элемент сейчас находится на вершине. Возможно, вы ожидаете точек в приложении, где пользователь может взаимодействовать и проверять, что предполагаемое взаимодействие в настоящее время возможно. В этом сценарии обычно указывается значение точки , представляющее определенную известную точку, например (0,0), которая в настоящее время является допустимой координатой в окне приложения. Для параметра поддерев можно передать его как null. Или можно указать поддерев , чтобы быть некоторым элементом, который вы знаете, является корневым визуальным элементом страницы или иным образом элемент, который вы хотите быть окончательной остановкой для тестирования попаданий.

В возвращаемом значении вы можете быть заинтересованы в каждом из элементов внутри. Таким образом, вы можете использовать методы foreach или аналогичные методы, относящиеся к языку, для итерации коллекции и выполнения собственной логики для каждого из этих элементов. Помните, что первый элемент в этой коллекции является самым верхним в z-порядке.

При программировании с помощью C#возвращаемый тип значения этого метода проецируется как универсальная коллекция IEnumerable , содержащая элементы UIElement . Если вы используете C++, возвращаемый тип этого метода — IIterable<UIElement>.

См. также раздел

• Point
• Взаимодействие с мышью

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)

Параметры

Возвращаемое значение

Перечислимый набор объектов UIElement , входящих в состав визуального дерева в указанном кадре Rect .

Атрибуты

OverloadAttribute

Примеры

Учитывая этот пользовательский интерфейс 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>

Ниже приведены некоторые примеры использования и результаты из FindElementsInHostCoordinates с использованием различных значений поддерев :

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
}

Комментарии

Возвращаемое значение не является одним элементом, это коллекция. Коллекция может иметь несколько элементов, так как в кадре intersectRect может быть несколько элементов пользовательского интерфейса, стекаемых друг на друга в z-порядке, а также несколько элементов полностью или частично в кадре intersectRect . Обычные методы тестирования попаданий, предоставляемые обработчиками входных событий, например значение отправителя для события PointerPressed , учитывают только самый верхний элемент, имеющий самый высокий z-порядок. Методы FindElementsInHostCoordinates возвращают весь стек элементов, общий доступ к этой точке или области в пользовательском интерфейсе приложения, указанный в порядке визуального дерева (который обычно совпадает с порядком объявления XAML). Таким образом, использование FindElementsInHostCoordinates может быть полезно для изучения случаев, когда вы намеренно или непреднамеренно стекали элементы. Вам может потребоваться исправить порядок отрисовки и тестирования попаданий или проверить этот порядок по другим причинам.

FindElementsInHostCoordinates по области полезно для двух сценариев: базовое тестирование попаданий и тестирование попаданий, которое фильтрует для определенного элемента.

Базовое тестирование попаданий

Для базового тестирования попаданий цель состоит в том, чтобы определить, какой элемент является самым высоким в порядке z пользовательского интерфейса приложения. Если вы тестируете нажатие на взаимодействие с мышью, вы можете использовать точку, но для сенсорно-ориентированного тестирования попадания часто подходит для использования прямоугольной области. Возможно, вы столкнулись с сценариями тестирования, в которых вы хотите знать, какой элемент существует в верхнем порядке z-порядка, прежде чем происходит любое событие сенсорного ввода. Или у вас может быть точка, которую вы хотите развернуть, чтобы быть прямоугольником, чтобы увидеть, что находится рядом с центром и какой элемент может быть целевым объектом.

Для этого сценария необходимо передать прямоугольник, который вы хотите проверить в качестве значения параметра intersectingRect . Для параметра поддерев можно передать его как null. Или можно указать поддерев , чтобы быть некоторым элементом, который вы знаете, является корневым визуальным элементом страницы или иным образом элемент, который вы хотите быть окончательной остановкой для тестирования попаданий.

Порядок элементов в возвращаемом IEnumerable элементов UIElement определяет как пространство координат в области, так и для z-порядка. Таким образом, можно получить хиты для элементов, которые не находятся в самом высоком порядке z-порядка и поэтому не могут быть источником входных событий. Чтобы убедиться, что вы можете выполнить тест с фильтрацией элементов для всех элементов из возвращаемого списка, используя тот же пересекающийсяRect , но передав элемент интереса как поддерев.

Тестирование попаданий, отфильтрованное элементом

Иногда необходимо знать, существует ли определенный элемент в пределах области пользовательского интерфейса. Если это так, можно указать эту область для intersectingRect и указать элемент, который вы ищете в качестве параметра поддерев . Если возвращаемое значение не является пустым, это означает, что элемент существует где-то в этой области. При тестировании области порядок в возвращаемом наборе не так полезен для определения z-порядка, так как набор включает элементы с несколькими координатами x-y. Набор содержит сочетание элементов с различными координатами x-y, а также элементами, которые могут быть полностью или частично перевернуты. Чтобы действительно изучить ситуацию переполнения, используйте перегрузки FindElementsInHostCoordinates , которые используют точку, чтобы координаты x-y и порядок визуального дерева больше не являются фактором. См. раздел FindElementsInHostCoordinates(Point,UIElement).

Если возвращаемое значение пусто, это означает, что элемент поддерев не существовал в области.

При программировании с помощью C#возвращаемый тип значения этого метода проецируется как универсальная коллекция IEnumerable , содержащая элементы UIElement . Если вы используете C++, возвращаемый тип этого метода — IIterable<UIElement>.

См. также раздел

• Взаимодействие с мышью

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)

Параметры

Возвращаемое значение

Перечисляемый набор объектов UIElement , которые определяются как расположенные в состав визуального дерева в указанной точке, перечисленные в обратном порядке z-порядка.

Атрибуты

DefaultOverloadAttribute OverloadAttribute

Примеры

Учитывая этот пользовательский интерфейс 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>

Ниже приведены некоторые примеры использования и результаты из FindElementsInHostCoordinates с использованием различных значений поддерев :

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
}

Комментарии

Элемент считается тестируемым, если он занимает пространство в макете и создает рукописный ввод. Для элементов, имеющих кисть, любая непустая кисть считается то, что создает рукописный ввод, даже если кисть не создает видимые пиксели. Например, SolidColorBrush с цветом, заданным для прозрачного , по-прежнему создает рукописный ввод. Только пустая кисть не создает рукописный ввод. Свойство Opacity не считается. Элемент по-прежнему создает рукописный ввод, даже если он непрозрачность равен 0.

Если для параметра includeAllElements задано значение true, элементы, которые не создают рукописный ввод, считаются для хит-тестирования. В этом случае, если элемент соответствует пространственным требованиям (точка пересекает границы элемента), то он и его предки включены в результаты.

См. также раздел

• FindElementsInHostCoordinates(Point, UIElement)
• FindElementsInHostCoordinates(Rect, UIElement)
• FindElementsInHostCoordinates(Rect, UIElement, Boolean)
• Point
• Взаимодействие с мышью

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)

Параметры

Возвращаемое значение

Перечислимый набор объектов UIElement , которые определяются в состав визуального дерева в указанном кадре Rect .

Атрибуты

OverloadAttribute

Примеры

Учитывая этот пользовательский интерфейс 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>

Ниже приведены некоторые примеры использования и результаты из FindElementsInHostCoordinates с использованием различных значений поддерев :

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
}

Комментарии

Элемент считается тестируемым, если он занимает пространство в макете и создает рукописный ввод. Для элементов, имеющих кисть, любая непустая кисть считается то, что создает рукописный ввод, даже если кисть не создает видимые пиксели. Например, SolidColorBrush с цветом, заданным для прозрачного , по-прежнему создает рукописный ввод. Только пустая кисть не создает рукописный ввод. Свойство Opacity не считается. Элемент по-прежнему создает рукописный ввод, даже если он непрозрачность равен 0.

Если для параметра includeAllElements задано значение true, элементы, которые не создают рукописный ввод, считаются для хит-тестирования. В этом случае, если элемент соответствует пространственным требованиям (прямоугольник пересекает границы элемента), то он и его предки включены в результаты.

См. также раздел

• FindElementsInHostCoordinates(Point, UIElement)
• FindElementsInHostCoordinates(Rect, UIElement)
• FindElementsInHostCoordinates(Point, UIElement, Boolean)
• Взаимодействие с мышью