Görsel Katmanında İsabet Testi

Bu konu, görsel katmanı tarafından sağlanan isabet testi işlevlerine genel bir bakış sağlar. İsabet testi desteği, bir geometri veya nokta değerinin bir Visual'in işlenmiş içeriği içinde olup olmadığını belirlemenize olanak tanır, böylece örneğin birden çok nesne seçmek için bir seçim dikdörtgeni gibi kullanıcı arayüzü davranışlarını uygulamanıza olanak tanır.

İsabetLi Test Senaryoları

UIElement sınıfı, verilen koordinat değerini kullanarak bir öğeye karşı teste ulaşmanızı sağlayan InputHitTest yöntemini sağlar. Çoğu durumda, InputHitTest yöntemi öğelerin isabet testini uygulamak için istenen işlevselliği sağlar. Ancak, görsel katmanında isabet testi uygulamanız gerekebilecek çeşitli senaryolar vardır.

  • UIElement olmayan nesnelere karşı isabet testi: bu, UIElement veya grafik nesneleri gibiDrawingVisual olmayan nesneleri test ediyorsanız geçerlidir.

  • Geometri kullanarak isabet testi: Bu, bir noktanın koordinat değerini kullanmak yerine bir geometri nesnesi aracılığıyla isabet testi yapmanız gerektiğinde geçerlidir.

  • Birden çok nesneye karşı isabet testi: Bu, çakışan nesneler gibi birden çok nesneye karşı teste basmanız gerektiğinde geçerlidir. Yalnızca ilki değil, geometri veya nokta kesişen tüm görseller için sonuçlar alabilirsiniz.

  • UIElement isabet testi ilkesini yoksaymanız gerektiğinde: Bu, bir öğenin devre dışı mı yoksa görünmez mi olduğu gibi faktörleri dikkate alan UIElement isabet testi ilkesini yoksaymanız gerektiğinde geçerlidir.

Uyarı

Görsel katmanında isabet testini gösteren eksiksiz bir kod örneği için bkz. ÇizimVisuals Kullanarak İsabet Testi Örneği ve Win32 Birlikte Çalışma ile İsabet Testi Örneği .

İsabet Testi Desteği

HitTest sınıfındaki VisualTreeHelper yöntemlerinin amacı, geometri veya nokta koordinat değerinin denetim veya grafik öğesi gibi belirli bir nesnenin işlenmiş içeriği içinde olup olmadığını belirlemektir. Örneğin, bir nesnenin sınırlayıcı dikdörtgeninde fare tıklamasının dairenin geometrisi içinde olup olmadığını belirlemek için isabet testi kullanabilirsiniz. Ayrıca, kendi özel isabet testi hesaplamalarınızı gerçekleştirmek için varsayılan isabet testi uygulamasını geçersiz kılmayı da seçebilirsiniz.

Aşağıdaki çizimde dikdörtgen olmayan bir nesnenin bölgesi ile sınırlayıcı dikdörtgeni arasındaki ilişki gösterilmektedir.

Geçerli isabet testi bölgesinin diyagramı
Geçerli isabet testi bölgesinin diyagramı

İsabet Testi ve Z Sırası

Windows Presentation Foundation (WPF) görsel katmanı, yalnızca en üstteki nesneye değil, nokta veya geometri altındaki tüm nesnelere yönelik isabet testini destekler. Sonuçlar z sırasına göre döndürülür. Ancak, HitTest yöntemine parametre olarak geçirdiğiniz görsel nesne, görsel ağacının hangi bölümünün isabet testi olacağını belirler. Görsel ağacının tamamına veya herhangi bir bölümüne karşı teste basabilirsiniz.

Aşağıdaki çizimde, daire nesnesi hem kare hem de üçgen nesnelerin üstündedir. Yalnızca z sırası değeri en üstte olan görsel nesneyle çarpışma testiyle ilgileniyorsanız, çarpışma testi geçişini ilk öğe üzerinde durdurmak için görsel çarpışma testi sabit listesini Stop'u HitTestResultCallback'de döndürecek şekilde ayarlayabilirsiniz.

Görsel ağaç z sırasının diyagramı
Görsel ağacın z sırasının diyagramı

Belirli bir nokta veya geometri altındaki tüm görsel nesneleri numaralandırmak istiyorsanız, Continueüzerinden HitTestResultCallback döndürmelisiniz. Diğer nesnelerin altındaki, tamamen gizlenmiş olsalar bile, görsel nesneleri test edebileceğiniz anlamına gelir. Daha fazla bilgi için "Hit Test Results Callback'ı Kullanma" bölümündeki örnek kodu inceleyin.

Uyarı

Saydam bir görsel nesneye de çarpışma testi yapılabilir.

Varsayılan İsabet Testlerini Kullanma

HitTest yöntemini kullanarak bir görsel nesnenin geometrisinde bir noktanın olup olmadığını belirleyebilir ve test etmek için nokta koordinat değeri belirtebilirsiniz. Görsel nesne parametresi, isabet testi araması için görsel ağacındaki başlangıç noktasını tanımlar. Görsel ağda, geometrisi koordinatı içeren bir görsel nesne bulunursa, bu nesne VisualHit nesnesinin HitTestResult özelliğine ayarlanır. HitTestResult daha sonra HitTest yönteminden döndürülür. Eğer nokta, isabet sınaması yaptığınız görsel alt ağacında yer almıyorsa, HitTestnulldöndürür.

Uyarı

Varsayılan isabet testi her zaman z düzeninde en üstteki nesneyi döndürür. Tüm görsel nesneleri, kısmen veya tamamen gizlenmiş olanlar dahil, tanımlamak için bir vuruş testi sonucu geri çağırma kullanın.

HitTest yöntemi için nokta parametresi olarak geçirdiğiniz koordinat değeri, test ettiğiniz görsel nesnenin koordinat alanına göre olmalıdır. Örneğin, üst öğesinin koordinat alanında (100, 100) tanımlı iç içe görsel nesneleriniz varsa, (0, 0) konumundaki bir alt görseli test etme isabeti, üst öğesinin koordinat alanında (100, 100) isabet testine eşdeğerdir.

Aşağıdaki kodda, isabet testi için kullanılan olayları yakalamak için kullanılan bir UIElement nesnesi için fare olay işleyicilerinin nasıl ayarlanacağı gösterilmektedir.

// Respond to the left mouse button down event by initiating the hit test.
private void OnMouseLeftButtonDown(object sender, MouseButtonEventArgs e)
{
    // Retrieve the coordinate of the mouse position.
    Point pt = e.GetPosition((UIElement)sender);

    // Perform the hit test against a given portion of the visual object tree.
    HitTestResult result = VisualTreeHelper.HitTest(myCanvas, pt);

    if (result != null)
    {
        // Perform action on hit visual object.
    }
}

' Respond to the left mouse button down event by initiating the hit test.
Private Overloads Sub OnMouseLeftButtonDown(ByVal sender As Object, ByVal e As MouseButtonEventArgs)
    ' Retrieve the coordinate of the mouse position.
    Dim pt As Point = e.GetPosition(CType(sender, UIElement))

    ' Perform the hit test against a given portion of the visual object tree.
    Dim result As HitTestResult = VisualTreeHelper.HitTest(myCanvas, pt)

    If result IsNot Nothing Then
        ' Perform action on hit visual object.
    End If
End Sub

Görsel Ağaç İsabet Testini Nasıl Etkiler?

Görsel ağaçtaki başlangıç noktası, nesnelerin isabet testi numaralandırması sırasında hangi nesnelerin döndürüleceğini belirler. Sınamaya isabet etmek istediğiniz birden çok nesneniz varsa, görsel ağaçta başlangıç noktası olarak kullanılan görsel nesne, ilgilendiğiniz tüm nesnelerin ortak atası olmalıdır. Örneğin, aşağıdaki diyagramda hem düğme öğesini hem de çizim görselini isabet testi yapmak istiyorsanız, görsel ağaçta başlangıç noktasını her ikisinin ortak atası olarak ayarlamanız gerekir. Bu durumda, tuval öğesi hem düğme öğesinin hem de çizim görselinin ortak atasıdır.

Görsel ağaç hiyerarşisi diyagramı
Görsel ağaç hiyerarşisinin diyagramı

Uyarı

IsHitTestVisible özelliği, UIElementtüretilmiş bir nesnenin işlenmiş içeriğinin bir bölümünden isabet testi sonucu olarak döndürülüp döndürülemeyeceğini bildiren bir değer alır veya ayarlar. Bu, isabet testinde hangi görsel nesnelerin yer aldığını belirlemek için görsel ağacı seçmeli olarak değiştirmenize olanak tanır.

İsabet Testi Sonucu Geri Çağırma kullanma

Geometrisi belirtilen koordinat değerini içeren bir görsel ağaçtaki tüm görsel nesneleri numaralandırabilirsiniz. Bu, diğer görsel nesneler tarafından kısmen veya tamamen gizlenenler bile olmak üzere tüm görsel nesneleri tanımlamanızı sağlar. Görsel ağaçtaki görsel nesneleri numaralandırmak için isabet testi geri çağırma işleviyle HitTest yöntemini kullanın. Belirttiğiniz koordinat değeri bir görsel nesnede bulunduğunda isabet testi geri çağırma işlevi sistem tarafından çağrılır.

İsabet testi sonuçları numaralandırması sırasında görsel ağacı değiştiren herhangi bir işlem gerçekleştirmemelisiniz. Bir nesnenin geçiş yapılırken görsel ağaçtan eklenmesi veya kaldırılması öngörülemeyen davranışlara neden olabilir. HitTest yöntemi döndürdüğünde görsel ağacı güvenle değiştirebilirsiniz. İsabet testi sonuçları numaralandırması sırasında değerleri depolamak için ArrayListgibi bir veri yapısı sağlamak isteyebilirsiniz.

// Respond to the right mouse button down event by setting up a hit test results callback.
private void OnMouseRightButtonDown(object sender, MouseButtonEventArgs e)
{
    // Retrieve the coordinate of the mouse position.
    Point pt = e.GetPosition((UIElement)sender);

    // Clear the contents of the list used for hit test results.
    hitResultsList.Clear();

    // Set up a callback to receive the hit test result enumeration.
    VisualTreeHelper.HitTest(myCanvas, null,
        new HitTestResultCallback(MyHitTestResult),
        new PointHitTestParameters(pt));

    // Perform actions on the hit test results list.
    if (hitResultsList.Count > 0)
    {
        Console.WriteLine("Number of Visuals Hit: " + hitResultsList.Count);
    }
}

' Respond to the right mouse button down event by setting up a hit test results callback.
Private Overloads Sub OnMouseRightButtonDown(ByVal sender As Object, ByVal e As MouseButtonEventArgs)
    ' Retrieve the coordinate of the mouse position.
    Dim pt As Point = e.GetPosition(CType(sender, UIElement))

    ' Clear the contents of the list used for hit test results.
    hitResultsList.Clear()

    ' Set up a callback to receive the hit test result enumeration.
    VisualTreeHelper.HitTest(myCanvas, Nothing, New HitTestResultCallback(AddressOf MyHitTestResult), New PointHitTestParameters(pt))

    ' Perform actions on the hit test results list.
    If hitResultsList.Count > 0 Then
        Console.WriteLine("Number of Visuals Hit: " & hitResultsList.Count)
    End If
End Sub

İsabet testi geri çağırma yöntemi, görsel ağacındaki belirli bir görsel nesnede isabet testi tanımlandığında gerçekleştirdiğiniz eylemleri tanımlar. Eylemleri gerçekleştirdikten sonra, diğer görsel nesnelerin numaralandırmasına devam edilip edilmeyeceğini belirleyen bir HitTestResultBehavior değeri döndürürsiniz.

// Return the result of the hit test to the callback.
public HitTestResultBehavior MyHitTestResult(HitTestResult result)
{
    // Add the hit test result to the list that will be processed after the enumeration.
    hitResultsList.Add(result.VisualHit);

    // Set the behavior to return visuals at all z-order levels.
    return HitTestResultBehavior.Continue;
}

' Return the result of the hit test to the callback.
Public Function MyHitTestResult(ByVal result As HitTestResult) As HitTestResultBehavior
    ' Add the hit test result to the list that will be processed after the enumeration.
    hitResultsList.Add(result.VisualHit)

    ' Set the behavior to return visuals at all z-order levels.
    Return HitTestResultBehavior.Continue
End Function

Uyarı

Hit görsel nesnelerinin numaralandırma sırası, z-index sırasına göredir. En üst z sırası düzeyindeki görsel nesne, numaralandırılmış ilk nesnedir. Numaralandırılan diğer tüm görsel nesneler z sırası düzeyinde azalan düzeydedir. Bu numaralandırma sırası, görsellerin işleme sırasına karşılık gelir.

Stopdöndürerek isabet testi geri çağırma işlevinde görsel nesnelerin numaralandırmasını istediğiniz zaman durdurabilirsiniz.

// Set the behavior to stop enumerating visuals.
return HitTestResultBehavior.Stop;

' Set the behavior to stop enumerating visuals.
Return HitTestResultBehavior.Stop

Hit Test Filtresi Callback Kullanma

İsabet testi sonuçlarına geçirilen nesneleri kısıtlamak için isteğe bağlı bir isabet testi filtresi kullanabilirsiniz. Bu, isabet testlerinizde işlemeyi düşünmediğiniz görsel ağacın bazı kısımlarını yoksaymanıza imkân sağlar. İsabet testi filtresi uygulamak için bir isabet testi filtresi geri çağırma işlevi tanımlar ve HitTest yöntemini çağırdığınızda bunu parametre değeri olarak geçirirsiniz.

// Respond to the mouse wheel event by setting up a hit test filter and results enumeration.
private void OnMouseWheel(object sender, MouseWheelEventArgs e)
{
    // Retrieve the coordinate of the mouse position.
    Point pt = e.GetPosition((UIElement)sender);

    // Clear the contents of the list used for hit test results.
    hitResultsList.Clear();

    // Set up a callback to receive the hit test result enumeration.
    VisualTreeHelper.HitTest(myCanvas,
                      new HitTestFilterCallback(MyHitTestFilter),
                      new HitTestResultCallback(MyHitTestResult),
                      new PointHitTestParameters(pt));

    // Perform actions on the hit test results list.
    if (hitResultsList.Count > 0)
    {
        ProcessHitTestResultsList();
    }
}

' Respond to the mouse wheel event by setting up a hit test filter and results enumeration.
Private Overloads Sub OnMouseWheel(ByVal sender As Object, ByVal e As MouseWheelEventArgs)
    ' Retrieve the coordinate of the mouse position.
    Dim pt As Point = e.GetPosition(CType(sender, UIElement))

    ' Clear the contents of the list used for hit test results.
    hitResultsList.Clear()

    ' Set up a callback to receive the hit test result enumeration.
    VisualTreeHelper.HitTest(myCanvas, New HitTestFilterCallback(AddressOf MyHitTestFilter), New HitTestResultCallback(AddressOf MyHitTestResult), New PointHitTestParameters(pt))

    ' Perform actions on the hit test results list.
    If hitResultsList.Count > 0 Then
        ProcessHitTestResultsList()
    End If
End Sub

İsteğe bağlı isabet testi filtre geri çağırma işlevini sağlamak istemiyorsanız, null yöntemi için parametre olarak HitTest değerini geçirin.

// Set up a callback to receive the hit test result enumeration,
// but no hit test filter enumeration.
VisualTreeHelper.HitTest(myCanvas,
                  null,  // No hit test filtering.
                  new HitTestResultCallback(MyHitTestResult),
                  new PointHitTestParameters(pt));

' Set up a callback to receive the hit test result enumeration,
' but no hit test filter enumeration.
VisualTreeHelper.HitTest(myCanvas, Nothing, New HitTestResultCallback(AddressOf MyHitTestResult), New PointHitTestParameters(pt)) ' No hit test filtering.

Isabet testi filtresi kullanarak görsel ağacı ayıklama
Görsel ağacı ayıklama

İsabet testi filtresi geri çağırma işlevi, belirtilen koordinatları içeren görüntülenen içeriğe sahip tüm görselleri gözden geçirmenize olanak tanır. Ancak, isabet testi sonuçları geri çağırma işlevinizde işlemek istemediğiniz görsel ağacının belirli dallarını yoksaymak isteyebilirsiniz. vuruş testi filtre geri çağırma işlevinin dönüş değeri, görsel nesnelerin sıralanmasının ne tür bir işlem yapması gerektiğini belirler. Örneğin, ContinueSkipSelfAndChildrendeğerini döndürürseniz, geçerli görsel nesnesini ve alt öğelerini isabet testi sonuçları numaralandırmasından kaldırabilirsiniz. Bu, isabet testi sonuçları geri çağırma işlevinin bu nesneleri numaralandırmasında göremeyeceği anlamına gelir. Nesnelerin görsel ağacının budaması, isabet testi sonuçlarını belirleme aşaması sırasında işleme miktarını azaltır. Aşağıdaki kod örneğinde, filtre etiketleri ve alt öğeleri atlar ve diğer her şeyi test eder.

// Filter the hit test values for each object in the enumeration.
public HitTestFilterBehavior MyHitTestFilter(DependencyObject o)
{
    // Test for the object value you want to filter.
    if (o.GetType() == typeof(Label))
    {
        // Visual object and descendants are NOT part of hit test results enumeration.
        return HitTestFilterBehavior.ContinueSkipSelfAndChildren;
    }
    else
    {
        // Visual object is part of hit test results enumeration.
        return HitTestFilterBehavior.Continue;
    }
}

' Filter the hit test values for each object in the enumeration.
Public Function MyHitTestFilter(ByVal o As DependencyObject) As HitTestFilterBehavior
    ' Test for the object value you want to filter.
    If o.GetType() Is GetType(Label) Then
        ' Visual object and descendants are NOT part of hit test results enumeration.
        Return HitTestFilterBehavior.ContinueSkipSelfAndChildren
    Else
        ' Visual object is part of hit test results enumeration.
        Return HitTestFilterBehavior.Continue
    End If
End Function

Uyarı

Bazen isabet testi sonuçları geri çağırma çağrılmadığında, isabet testi filtresi geri çağırması çağrılır.

Varsayılan İsabet Testlerini Geçersiz Kılma

HitTestCore yöntemini geçersiz kılarak görsel nesnesinin varsayılan isabet testi desteğini geçersiz kılabilirsiniz. Başka bir deyişle, HitTest yöntemini çağırdığınızda geçersiz kılınan HitTestCore uygulamanız çağrılır. Geçersiz kılınan yönteminiz, koordinat görsel nesnesinin işlenmiş içeriğinin dışında olsa bile isabet testi görsel nesnesinin sınırlayıcı dikdörtgeninin içinde olduğunda çağrılır.

// Override default hit test support in visual object.
protected override HitTestResult HitTestCore(PointHitTestParameters hitTestParameters)
{
    Point pt = hitTestParameters.HitPoint;

    // Perform custom actions during the hit test processing,
    // which may include verifying that the point actually
    // falls within the rendered content of the visual.

    // Return hit on bounding rectangle of visual object.
    return new PointHitTestResult(this, pt);
}

' Override default hit test support in visual object.
Protected Overrides Overloads Function HitTestCore(ByVal hitTestParameters As PointHitTestParameters) As HitTestResult
    Dim pt As Point = hitTestParameters.HitPoint

    ' Perform custom actions during the hit test processing,
    ' which may include verifying that the point actually
    ' falls within the rendered content of the visual.

    ' Return hit on bounding rectangle of visual object.
    Return New PointHitTestResult(Me, pt)
End Function

Bazen hem sınırlayıcı dikdörtgende hem de görsel nesnenin işlenmiş içeriğinde teste isabet etmek isteyebilirsiniz. PointHitTestParameterstemel yönteminin parametresi olarak geçersiz kılınan HitTestCore yönteminizdeki HitTestCore parametre değerini kullanarak, görsel nesnesinin sınırlayıcı dikdörtgenine yapılan isabete göre eylemler gerçekleştirebilir ve ardından görsel nesnesinin işlenmiş içeriğine karşı ikinci bir isabet testi yapabilirsiniz.

// Override default hit test support in visual object.
protected override HitTestResult HitTestCore(PointHitTestParameters hitTestParameters)
{
    // Perform actions based on hit test of bounding rectangle.
    // ...

    // Return results of base class hit testing,
    // which only returns hit on the geometry of visual objects.
    return base.HitTestCore(hitTestParameters);
}

' Override default hit test support in visual object.
Protected Overrides Overloads Function HitTestCore(ByVal hitTestParameters As PointHitTestParameters) As HitTestResult
    ' Perform actions based on hit test of bounding rectangle.
    ' ...

    ' Return results of base class hit testing,
    ' which only returns hit on the geometry of visual objects.
    Return MyBase.HitTestCore(hitTestParameters)
End Function

Ayrıca bakınız

  • Last updated on