VisualTreeHelper.FindElementsInHostCoordinates Método

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)

Parâmetros

Retornos

Um conjunto enumerável de objetos UIElement na composição de árvore visual no ponto especificado, listado pelo inverso da ordem z.

Atributos

DefaultOverloadAttribute OverloadAttribute

Exemplos

Este é um método utilitário de exemplo que determina se um elemento de um determinado Nome existe em qualquer lugar na ordem z em um Ponto na interface do usuário de um aplicativo.

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

Comentários

O valor retornado não é um único elemento, é uma coleção. A coleção pode ter mais de um elemento porque pode haver vários elementos de interface do usuário empilhados uns sobre os outros em uma ordem z. As técnicas convencionais de teste de ocorrência expostas pelos manipuladores de eventos de entrada, como o valor do remetente para um evento PointerPressed , representam apenas o elemento mais alto que tem a ordem z mais alta. Os métodos FindElementsInHostCoordinates retornam toda a pilha de elementos que compartilham esse ponto ou área na interface do usuário do aplicativo, listados pelo inverso da ordem z. O uso de FindElementsInHostCoordinates pode, portanto, ser útil para examinar casos em que você empilhou elementos intencionalmente ou não. Talvez você queira corrigir a ordem de renderização e teste de ocorrência ou examinar essa ordem por outros motivos.

FindElementsInHostCoordinates é útil para três cenários: teste de clique básico, teste de clique que está filtrando um elemento específico e determinando se há elementos em uma árvore visual que estão superando no mesmo ponto.

Teste de clique básico

Para o teste de clique básico, o objetivo é descobrir qual elemento é mais alto na ordem z de uma interface do usuário do aplicativo em um determinado ponto em coordenadas x-y. Além de ser o elemento que mais desenha na interface do usuário renderizada, esse elemento também é importante porque é a fonte de evento relatada se houver interações do usuário, como eventos de ponteiro. Você pode ter cenários de teste de ocorrência em que deseja saber qual elemento existe na ordem z superior antes que qualquer evento de entrada ocorra, para que você possa antecipá-lo e talvez corrigir quaisquer erros no posicionamento da ordem z.

Para esse cenário, você deve passar o ponto em que está interessado no teste de ocorrência como o valor do parâmetro intersectingPoint . Para o parâmetro subárvore , você pode passá-lo como nulo. Ou você pode especificar a subárvore para ser um elemento que você sabe que é o visual raiz de uma página ou, de outra forma, é algum elemento que você deseja ser a parada final para teste de clique.

O elemento que é superior na ordem z é sempre o primeiro elemento no IEnumerable retornado dos itens UIElement . Portanto, para testes básicos de clique, você geralmente só está interessado nesse primeiro item. Quaisquer itens adicionais no IEnumerable são outros elementos que também estão nesse ponto, mas estão mais atrás na ordem z e estão desenhando abaixo desse primeiro item. Os elementos mais para trás não se reportariam como a origem de um evento de entrada nesse ponto, apenas o elemento superior seria.

Teste de clique filtrado por elemento

Às vezes, você deseja saber se um elemento específico existe em um determinado ponto da interface do usuário. Nesse caso, você pode especificar esse ponto para intersectingPoint e especificar o elemento que você está procurando como o parâmetro de subárvore . Se o valor retornado não estiver vazio, isso significa que o elemento existe nesse ponto da interface do usuário. Se o elemento for o primeiro item no valor retornado, isso significa que o elemento é superior na ordem z em intersectingPoint. Se houver outros itens no valor retornado e a subárvore não for a primeira, os outros itens representarão os elementos renderizados em intersectingPoint que são mais altos na ordem z (visualmente, esses renderizam na parte superior do elemento subárvore ). Nesse caso, a subárvore é o último elemento no IEnumerable retornado, não o primeiro.

Se o valor retornado estiver vazio, isso significa que o elemento subárvore não existia lá, em nenhum valor de ordem z.

Procurando a sobrecarga ou olhando para a árvore visual completa

Uma interface do usuário pode ser dinâmica, especialmente se você estiver usando coleções de associação de dados para a população de interface do usuário. Portanto, ocasionalmente, há a necessidade de saber qual elemento está atualmente na parte superior. Você pode estar antecipando pontos no aplicativo em que o usuário pode interagir e verificar se as interações que você pretende são possíveis no momento. Para esse cenário, você normalmente especifica um valor Point que representa algum ponto conhecido, como (0,0) que atualmente é uma coordenada válida dentro da janela do aplicativo. Para o parâmetro subárvore , você pode passá-lo como nulo. Ou você pode especificar a subárvore para ser um elemento que você sabe que é o visual raiz de uma página ou, de outra forma, é algum elemento que você deseja ser a parada final para teste de clique.

No valor retornado, você pode estar interessado em cada um dos itens dentro. Portanto, você pode usar técnicas específicas de linguagem foreach ou semelhantes para iterar a coleção e executar sua própria lógica em cada um desses elementos. Lembre-se de que o primeiro elemento nessa coleção é aquele que é superior na ordem z.

Se você estiver programando usando C# ou Microsoft Visual Basic, o tipo de valor retornado desse método será projetado como uma coleção genérica IEnumerable que contém itens UIElement . Se você estiver programando usando extensões de componente do Visual C++ (C++/CX), o tipo de retorno desse método será IIterable<UIElement>.

Confira também

• Point
• Interações por 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)

Parâmetros

Retornos

Um conjunto enumerável de objetos UIElement que estão na composição de árvore visual no quadro Rect especificado.

Atributos

OverloadAttribute

Exemplos

Considerando essa interface do usuário 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>

Aqui estão alguns exemplos de usos e resultados de FindElementsInHostCoordinates, usando diferentes valores de subárvores :

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
}

Comentários

O valor retornado não é um único elemento, é uma coleção. A coleção pode ter mais de um elemento porque pode haver vários elementos de interface do usuário empilhados uns sobre os outros em uma ordem z e também vários elementos totalmente ou parcialmente no quadro intersectingRect . As técnicas convencionais de teste de ocorrência expostas pelos manipuladores de eventos de entrada, como o valor do remetente para um evento PointerPressed , representam apenas o elemento mais alto que tem a ordem z mais alta. Os métodos FindElementsInHostCoordinates retornam toda a pilha de elementos que compartilham esse ponto ou área na interface do usuário do aplicativo, listados por ordem de árvore visual (que geralmente é o mesmo que inverso da ordem de declaração XAML). O uso de FindElementsInHostCoordinates pode, portanto, ser útil para examinar casos em que você empilhou elementos intencionalmente ou não. Talvez você queira corrigir a ordem de renderização e teste de ocorrência ou examinar essa ordem por outros motivos.

FindElementsInHostCoordinates em uma área é útil para dois cenários: teste de clique básico e teste de clique que está filtrando para um elemento específico.

Teste de clique básico

Para testes de clique básicos, a meta é descobrir qual elemento é mais alto na ordem z de uma interface do usuário do aplicativo. Se você estiver testando cliques para uma interação com o mouse, poderá usar um ponto, mas para testes de clique orientados a toque, geralmente é apropriado usar uma área retangular. Você pode ter cenários de teste de ocorrência em que deseja saber qual elemento existe na ordem z superior antes que qualquer evento de toque ocorra. Ou você pode ter um ponto que deseja expandir para ser um retângulo para ver o que está perto de um ponto central e qual elemento pode ser o destino pretendido.

Para esse cenário, você deve passar o retângulo em que está interessado em testar cliques como o valor do parâmetro intersectingRect . Para o parâmetro subárvore , você pode passá-lo como nulo. Ou você pode especificar a subárvore para ser um elemento que você sabe que é o visual raiz de uma página ou, de outra forma, é algum elemento que você deseja ser a parada final para teste de clique.

A ordem do elemento no IEnumerable retornado dos itens UIElement é responsável pelo espaço de coordenadas na área e pela ordem z. Portanto, é possível obter ocorrências para itens que não estão na ordem z mais alta e, portanto, não poderia ser a origem dos eventos de entrada. Para ter certeza, você pode fazer um teste de clique filtrado por elemento para todos os itens da lista retornada em que você está interessado, usando o mesmo intersectingRect , mas passando o elemento de interesse como subárvore.

Teste de clique filtrado por elemento

Às vezes, você deseja saber se existe um elemento específico dentro de uma área da interface do usuário. Nesse caso, você pode especificar essa área para intersectingRect e especificar o elemento que você está procurando como o parâmetro de subárvore . Se o valor retornado não estiver vazio, isso significa que o elemento existe em algum lugar nessa área. Quando você está testando uma área, a ordem no conjunto de retorno não é tão útil para determinar a ordem z porque o conjunto inclui elementos em mais de uma coordenada x-y. O conjunto tem uma combinação de elementos desenhando em várias coordenadas x-y e também elementos que podem ser totalmente ou parcialmente sacados. Para realmente examinar uma situação de sobrecarga, use as sobrecargas de FindElementsInHostCoordinates que usam um Point, para que as coordenadas x-y e a ordem da árvore visual não sejam mais um fator. Consulte FindElementsInHostCoordinates(Point,UIElement).

Se o valor retornado estiver vazio, isso significa que o elemento de subárvore não existia na área.

Se você estiver programando usando C# ou Microsoft Visual Basic, o tipo de valor retornado desse método será projetado como uma coleção genérica IEnumerable que contém itens UIElement . Se você estiver programando usando extensões de componente do Visual C++ (C++/CX), o tipo de retorno desse método será IIterable<UIElement>.

Confira também

• Interações por 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)

Parâmetros

Retornos

Um conjunto enumerável de objetos UIElement que são determinados como localizados na composição de árvore visual no ponto especificado, listado pelo inverso da ordem z.

Atributos

DefaultOverloadAttribute OverloadAttribute

Exemplos

Considerando essa interface do usuário 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>

Aqui estão alguns exemplos de usos e resultados de FindElementsInHostCoordinates, usando diferentes valores de subárvore :

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
}

Comentários

Um elemento será considerado testável por clique se ocupar espaço no layout e "produzir tinta". Para elementos que têm um Brush, qualquer Pincel não nulo é considerado algo que produz tinta, mesmo que o Pincel não produza pixels visíveis. Por exemplo, um SolidColorBrush com sua cor definida como Transparente ainda produz tinta. Somente um pincel nulo não produz tinta. A propriedade Opacity não é considerada. O elemento ainda produz tinta, mesmo que a opacidade seja 0.

Quando o parâmetro includeAllElements é definido como true, elementos que não produzem tinta são considerados para teste de clique. Nesse caso, desde que o elemento atenda aos requisitos espaciais (o ponto cruza os limites do elemento), ele e seus ancestrais serão incluídos nos resultados.

Confira também

• Point
• FindElementsInHostCoordinates(Point, UIElement)
• FindElementsInHostCoordinates(Rect, UIElement)
• FindElementsInHostCoordinates(Rect, UIElement, Boolean)
• Interações por 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)

Parâmetros

Retornos

Um conjunto enumerável de objetos UIElement que são determinados como localizados na composição de árvore visual no quadro Rect especificado.

Atributos

OverloadAttribute

Exemplos

Considerando essa interface do usuário 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>

Aqui estão alguns exemplos de usos e resultados de FindElementsInHostCoordinates, usando diferentes valores de subárvore :

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
}

Comentários

Um elemento será considerado testável por clique se ocupar espaço no layout e "produzir tinta". Para elementos que têm um Brush, qualquer Pincel não nulo é considerado algo que produz tinta, mesmo que o Pincel não produza pixels visíveis. Por exemplo, um SolidColorBrush com sua cor definida como Transparente ainda produz tinta. Somente um pincel nulo não produz tinta. A propriedade Opacity não é considerada. O elemento ainda produz tinta, mesmo que a opacidade seja 0.

Quando o parâmetro includeAllElements é definido como true, elementos que não produzem tinta são considerados para teste de clique. Nesse caso, desde que o elemento atenda aos requisitos espaciais (o rect cruza os limites do elemento), ele e seus ancestrais são incluídos nos resultados.

Confira também

• FindElementsInHostCoordinates(Point, UIElement)
• FindElementsInHostCoordinates(Rect, UIElement)
• FindElementsInHostCoordinates(Point, UIElement, Boolean)
• Interações por mouse