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-порядка.

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

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

Проверка попадания с фильтром элементов

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

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

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

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

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

При программировании с помощью C# или Microsoft Visual Basic тип возвращаемого значения этого метода проецируется как универсальная коллекция IEnumerable , содержащая элементы UIElement . При программировании с помощью расширений компонентов Visual C++ (C++/CX) этот метод возвращает тип 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 , которые находятся в композиции визуального дерева в заданном прямоугольнике .

Атрибуты

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
}

Комментарии

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

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

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

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

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

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

Проверка попадания с фильтром элементов

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

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

При программировании с помощью C# или Microsoft Visual Basic тип возвращаемого значения этого метода проецируется как универсальная коллекция IEnumerable , содержащая элементы UIElement . При программировании с помощью расширений компонентов Visual C++ (C++/CX) этот метод возвращает тип 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
}

Комментарии

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

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

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

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

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 , которые, как определено, находятся в композиции визуального дерева в заданном прямоугольнике .

Атрибуты

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
}

Комментарии

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

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

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

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