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

例

これは、特定の Name の要素が、アプリの UI の Point にある 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;
}

注釈

戻り値は 1 つの要素ではなく、コレクションです。 複数の UI 要素を z オーダーで積み重ねることができるため、コレクションには複数の要素を含めることができます。 PointerPressed イベントの送信者値など、入力イベント ハンドラーによって公開される従来のヒット テスト手法は、z オーダーが最も高い最上位の要素のみを考慮しています。 FindElementsInHostCoordinates メソッドは、アプリ UI でそのポイントまたは領域を共有する要素のスタック全体を返します。これは、z オーダーの逆数で示されます。 そのため、FindElementsInHostCoordinates を使用すると、要素を意図的または意図せずに積み重ねたケースを調べるのに役立ちます。 レンダリングとヒット テストの順序を修正するか、その順序を他の理由で調べたい場合があります。

FindElementsInHostCoordinates は、基本的なヒット テスト、特定の要素のフィルター処理を行うヒット テスト、同じポイントでオーバードローされているビジュアル ツリー内の要素があるかどうかを判断する 3 つのシナリオに役立ちます。

基本的なヒット テスト

基本的なヒット テストの目的は、x-y 座標の特定のポイントでアプリ UI の z オーダーで最も高い要素を検出することです。 この要素は、レンダリングされた UI で最上位に描画される要素であることに加えて、ポインター イベントなどのユーザー操作がある場合に報告されるイベント ソースであるため、重要です。 ヒット テストのシナリオでは、入力イベントが発生する前に上位の z オーダーに存在する要素を把握し、それを予測し、z オーダー配置の間違いを修正できる場合があります。

このシナリオでは、ヒット テストに関心のあるポイントを intersectingPoint パラメーターの値として渡す必要があります。 サブツリー パラメーターの場合は、null として渡すことができます。 または、 サブツリー をページのルート ビジュアルであることがわかっている要素に指定することも、ヒット テストの最後の停止にする要素を指定することもできます。

z オーダーの最上位にある要素は、常に UIElement 項目の返された IEnumerable の最初の要素です。 そのため、基本的なヒット テストでは、通常、その非常に最初の項目にのみ関心があります。 IEnumerable 内のその他の項目は、その時点でも Z オーダーに戻り、その最初の項目の下に描画されるその他の要素です。 さらに後ろの要素は、その時点での入力イベントのソースとして自分自身を報告しません。最上位の要素のみが報告されます。

要素フィルターによるヒット テスト

UI の特定のポイントに特定の要素が存在するかどうかを知りたい場合があります。 その場合は、 intersectingPoint のポイントを指定し、探している要素を サブツリー パラメーターとして指定できます。 戻り値が空でない場合は、UI のその時点に 要素が存在しないことを意味します。 要素が戻り値の最初の項目である場合は、要素が intersectingPoint の z オーダーの一番上にあることを意味します。 戻り値に他の項目があり、 サブツリー が最初でない場合、他の項目は、z オーダーで高い intersectingPoint でレンダリングされる要素を表します (視覚的には、これらの項目は サブツリー 要素の上にレンダリングされます)。 その場合、 サブツリー は、最初の要素ではなく、返された IEnumerable 内の最後の要素です。

戻り値が空の場合は、 サブツリー 要素が存在しなかったことを意味します(z オーダー値)。

オーバードローを探すか、完全なビジュアル ツリーを見る

UI は動的な場合があります。特に、UI の作成にデータ バインディングからのコレクションを使用している場合は 。 そのため、現在どの要素が上にあるかを知る必要がある場合があります。 ユーザーが対話する可能性があるアプリ内のポイントを予測し、意図した操作が現在可能であることを確認している可能性があります。 このシナリオでは、通常、現在アプリ ウィンドウ内にある有効な座標である (0,0) などの既知のポイントを表す Point 値を指定します。 サブツリー パラメーターの場合は、null として渡すことができます。 または、 サブツリー をページのルート ビジュアルであることがわかっている要素に指定することも、ヒット テストの最後の停止にする要素を指定することもできます。

戻り値では、内の各項目に関心がある場合があります。 そのため、 foreach または同様の言語固有の手法を使用してコレクションを反復処理し、これらの各要素に対して独自のロジックを実行できます。 そのコレクションの最初の要素は、z オーダーで一番上にある要素であることを思い出してください。

C# または Microsoft Visual Basic を使用してプログラミングする場合、このメソッドの戻り値の型は、UIElement 項目を含む IEnumerable ジェネリック コレクションとして投影されます。 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)

パラメーター

戻り値

指定した Rect フレーム内のビジュアル ツリーコンポジション内にある UIElement オブジェクトの列挙可能なセット。

属性

OverloadAttribute

例

次の XAML UI を指定します。

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

注釈

戻り値は 1 つの要素ではなく、コレクションです。 コレクションには複数の要素を含めることができます。複数の UI 要素が z オーダーで積み重ねられ、 また、交差するRect フレーム内の複数の要素が完全または部分的に積み重ねられる可能性があるためです。 PointerPressed イベントの送信者値など、入力イベント ハンドラーによって公開される従来のヒット テスト手法は、z オーダーが最も高い最上位の要素のみを考慮しています。 FindElementsInHostCoordinates メソッドは、アプリ UI でそのポイントまたは領域を共有する要素のスタック全体を返します。これは、ビジュアル ツリーの順序 (通常は XAML 宣言順序の逆と同じです) で示されます。 そのため、FindElementsInHostCoordinates を使用すると、要素を意図的または意図せずに積み重ねたケースを調べるのに役立ちます。 レンダリングとヒット テストの順序を修正するか、その順序を他の理由で調べたい場合があります。

領域に対する FindElementsInHostCoordinates は、特定の要素に対してフィルター処理する基本的なヒット テストとヒット テストの 2 つのシナリオに役立ちます。

基本的なヒット テスト

基本的なヒット テストの目的は、アプリ UI の z オーダーで最も高い要素を検出することです。 マウス操作のヒット テストを行う場合は、ポイントを使用できますが、タッチ指向のヒット テストでは、四角形の領域を使用することが適切なことがよくあります。 タッチ イベントが発生する前に、最上位の z オーダーに存在する要素を把握する必要があるヒット テスト シナリオが発生する可能性があります。 または、中心点の近くに何があるか、どの要素が目的のターゲットであるかを確認するために、四角形として展開する点がある場合もあります。

このシナリオでは、ヒット テストに関心のある四角形を intersectingRect パラメーターの値として渡す必要があります。 サブツリー パラメーターの場合は、null として渡すことができます。 または、 サブツリー をページのルート ビジュアルであることがわかっている要素に指定することも、ヒット テストの最後の停止にする要素を指定することもできます。

UIElement 項目の返された IEnumerable 内の要素の順序は、領域内の座標空間と z オーダーの両方を占めます。 そのため、z オーダーが最も高くないため、入力イベントのソースにできなかった項目のヒットを取得できます。 確実に行うには、同じ intersectingRect を使用し、目的の要素を サブツリーとして渡して、関心のある返されたリストから任意の項目に対して要素フィルターによるヒット テストを実行できます。

要素フィルターによるヒット テスト

UI の領域内に特定の要素が存在するかどうかを知りたい場合があります。 その場合は、 intersectingRect の領域を指定し、探している要素を サブツリー パラメーターとして指定できます。 戻り値が空でない場合は、その領域のどこかに要素が存在することを意味します。 領域をヒット テストする場合、セットには複数の x-y 座標の要素が含まれているため、戻り値セットの順序は z オーダーを決定する場合ほど役に立ちません。 セットには、さまざまな x-y 座標で描画される要素と、完全または部分的に描画される可能性がある要素が混在しています。 実際にオーバードローの状況を調べるには、Point を使用する FindElementsInHostCoordinates のオーバーロードを使用して、x-y 座標とビジュアル ツリーの順序が要因にならないようにします。 FindElementsInHostCoordinates(Point,UIElement)を参照してください。

戻り値が空の場合は、 サブツリー 要素が領域に存在しなかったことを意味します。

C# または Microsoft Visual Basic を使用してプログラミングする場合、このメソッドの戻り値の型は、UIElement 項目を含む IEnumerable ジェネリック コレクションとして投影されます。 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 UI を指定します。

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

注釈

要素がレイアウト内のスペースを占有し、"インクを生成する" 場合、要素はヒット テスト可能と見なされます。 Brush を持つ要素の場合、Null 以外の Brush は、ブラシが可視ピクセルを生成しない場合でも、インクを生成するものと見なされます。 たとえば、色が Transparent に設定された SolidColorBrush は、インクを生成します。 null ブラシのみがインクを生成しません。 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)

パラメーター

戻り値

指定した Rect フレーム内のビジュアル ツリーコンポジションに配置されると判断される、列挙可能な UIElement オブジェクトのセット。

属性

OverloadAttribute

例

次の XAML UI を指定します。

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

注釈

要素がレイアウト内のスペースを占有し、"インクを生成する" 場合、要素はヒット テスト可能と見なされます。 Brush を持つ要素の場合、Null 以外の Brush は、ブラシが可視ピクセルを生成しない場合でも、インクを生成するものと見なされます。 たとえば、色が Transparent に設定された SolidColorBrush は、インクを生成します。 null ブラシのみがインクを生成しません。 Opacity プロパティは考慮されません。 不透明度が 0 の場合でも、要素はインクを生成します。

includeAllElements パラメーターが true に設定されている場合、インクを生成しない要素はヒット テストと見なされます。 この場合、要素が空間要件を満たしている限り (rect は要素の境界と交差します)、その要素とその先祖が結果に含まれます。

こちらもご覧ください

• FindElementsInHostCoordinates(Point, UIElement)
• FindElementsInHostCoordinates(Rect, UIElement)
• FindElementsInHostCoordinates(Point, UIElement, Boolean)
• マウス操作