Übersicht über Adorner

Adorner sind ein besonderer Typ von FrameworkElement, mit denen visuelle Hinweise für einen Benutzer angezeigt werden. Unter anderem können Adorner verwendet werden, um Elementen funktionale Handles hinzuzufügen oder Zustandsinformationen über ein Steuerelement zur Verfügung zu stellen.

Dieses Thema enthält folgende Abschnitte.

• Informationen über Adorner
• Implementieren eines benutzerdefinierten Adorners
• Renderingverhalten für Adorner
• Ereignisse und Treffertests
• Verzieren eines einzelnen UIElements
• Verzieren der untergeordneten Elemente eines Bereichs
• Verwandte Abschnitte

Informationen über Adorner

Ein Adorner ist ein benutzerdefiniertes FrameworkElement, das an ein UIElement gebunden wird. Adorner werden in einer AdornerLayer gerendert, einer Renderingoberfläche, die sich immer über dem verzierten Element oder einer Auflistung verzierter Elemente befindet. Das Rendern eines Adorners ist unabhängig vom Rendern des UIElement, an das der Adorner gebunden wird. Ein Adorner wird typischerweise relativ zu dem Element positioniert, an das dieser gebunden ist. Dazu wird ein 2D-Standardkoordinatenursprung verwendet, der sich in der linken oberen Ecke des verzierten Elements befindet.

Zu den häufigen Anwendungen für Adorner zählen:

• Hinzufügen funktionaler Handles für ein UIElement, mit denen ein Benutzer das Element bearbeiten kann (Größenanpassung, Drehung, Neuanordnung usw.).

• Bereitstellen von visuellem Feedback, um verschiedene Zustände anzugeben oder als Reaktion auf verschiedene Ereignisse.

• Überlagern von UIElement mit visuellen Ergänzungen.

• Visuelles Maskieren oder Überschreiben eines Teils von UIElement oder des gesamten Elements.

Windows Presentation Foundation (WPF) stellt ein grundlegendes Framework zum Verzieren visueller Elemente bereit. In der folgenden Tabelle werden die zum Verzieren von Objekten verwendeten primären Typen und ihre Funktion aufgelistet. Es folgen mehrere Verwendungsbeispiele.

Adorner	Eine abstrakte Basisklasse, von der alle konkreten Adornerimplementierungen erben.
AdornerLayer	Eine Klasse, die eine Renderingebene für den (die) Adorner von einem oder mehreren verzierten Elementen darstellt.
AdornerDecorator	Eine Klasse, die ermöglicht, dass eine Adornerebene einer Auflistung von Elementen zugeordnet werden kann.

Implementieren eines benutzerdefinierten Adorners

Das von Windows Presentation Foundation (WPF) bereitgestellte Adornerframework dient in erster Linie der Unterstützung beim Erstellen benutzerdefinierter Adorner. Ein benutzerdefinierter Adorner wird erstellt, indem eine Klasse implementiert wird, die von der abstrakten Adorner-Klasse erbt.

Hinweis
Das übergeordnete Element eines Adorner ist die AdornerLayer, die den Adorner rendert, nicht das zu verzierende Element.

Im folgenden Beispiel wird eine Klasse dargestellt, die einen einfachen Adorner implementiert. Der Beispieladorner versieht einfach die Ecken eines UIElement mit Kreisen.

Public Class SimpleCircleAdorner
    Inherits Adorner
    Sub New(ByVal adornedElement As UIElement)
        MyBase.New(adornedElement)
    End Sub

    Protected Overrides Sub OnRender(ByVal drawingContext As System.Windows.Media.DrawingContext)
        MyBase.OnRender(drawingContext)
        Dim adornedElementRect As New Rect(AdornedElement.DesiredSize)
        Dim renderBrush As New SolidColorBrush(Colors.Green)
        renderBrush.Opacity = 0.2
        Dim renderPen As New Pen(New SolidColorBrush(Colors.Navy), 1.5)
        Dim renderRadius As Double
        renderRadius = 5.0

        'Draw a circle at each corner.
        drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.TopLeft, renderRadius, renderRadius)
        drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.TopRight, renderRadius, renderRadius)
        drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.BottomLeft, renderRadius, renderRadius)
        drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.BottomRight, renderRadius, renderRadius)
    End Sub
End Class

// Adorners must subclass the abstract base class Adorner.
public class SimpleCircleAdorner : Adorner
{
  // Be sure to call the base class constructor.
  public SimpleCircleAdorner(UIElement adornedElement)
    : base(adornedElement) 
  { 
  }

  // A common way to implement an adorner's rendering behavior is to override the OnRender
  // method, which is called by the layout system as part of a rendering pass.
  protected override void OnRender(DrawingContext drawingContext)
  {
    Rect adornedElementRect = new Rect(this.AdornedElement.DesiredSize);

    // Some arbitrary drawing implements.
    SolidColorBrush renderBrush = new SolidColorBrush(Colors.Green);
    renderBrush.Opacity = 0.2;
    Pen renderPen = new Pen(new SolidColorBrush(Colors.Navy), 1.5);
    double renderRadius = 5.0;

    // Draw a circle at each corner.
    drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.TopLeft, renderRadius, renderRadius);
    drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.TopRight, renderRadius, renderRadius);
    drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.BottomLeft, renderRadius, renderRadius);
    drawingContext.DrawEllipse(renderBrush, renderPen, adornedElementRect.BottomRight, renderRadius, renderRadius);
  }
}

Im folgenden Bild wird der auf ein TextBox angewendete SimpleCircleAdorner dargestellt.

Renderingverhalten für Adorner

Beachten Sie, dass für Adorner kein Renderingverhalten festgelegt ist. Sicherzustellen, dass ein Adorner rendert, ist Aufgabe des Implementierers. Zur Implementierung von Renderingverhalten wird meistens die OnRender-Methode überschrieben, und es werden ein oder mehrere DrawingContext-Objekte verwendet, um die Darstellung des Adorners wie gewünscht zu rendern (wie im oben stehenden Beispiel gezeigt).

Hinweis
Sämtliche Elemente auf der Adornerebene werden über allen anderen möglicherweise festgelegten Stilen gerendert.Anders gesagt, befinden sich Adorner stets visuell im Vordergrund und können nicht mit der Z-Reihenfolge überschrieben werden.

Ereignisse und Treffertests

Adorner empfangen Eingabeereignisse wie jedes andere FrameworkElement. Da sich ein Adorner immer höher in der Z-Reihenfolge befindet als das Element, das verziert wird, empfängt der Adorner Eingabeereignisse (z. B. Drop oder MouseMove), die möglicherweise für das zugrunde liegende verzierte Element bestimmt sind. Ein Adorner kann bestimmte Eingabeereignisse überwachen und sie durch erneutes Auslösen des Ereignisses an das zugrunde liegende verzierte Element weiterleiten.

Um die Pass-Through-Treffertests von Elementen unter einem Adorner zu aktivieren, legen Sie die IsHitTestVisible-Eigenschaft des Treffertests für den Adorner auf false fest. Weitere Informationen zu Treffertests finden Sie unter

Treffertests in der visuellen Ebene.

Verzieren eines einzelnen UIElements

Um einen Adorner an ein bestimmtes UIElement zu binden, führen Sie die folgenden Schritte aus:

1. Rufen Sie die statische Methode GetAdornerLayer auf, um ein AdornerLayer-Objekt für das zu verzierende UIElement-Element abzurufen. GetAdornerLayer durchläuft, beginnend am angegebenen UIElement-Element , die visuelle Struktur und gibt die erste gefundene Adornerebene zurück. (Wenn keine Adornerebenen gefunden werden, gibt die Methode NULL zurück.)

2. Rufen Sie die Add-Methode auf, um den Adorner an das Ziel-UIElement zu binden.

Im folgenden Beispiel wird ein SimpleCircleAdorner (siehe weiter oben) an ein TextBox mit dem Namen myTextBox gebunden.

myAdornerLayer = AdornerLayer.GetAdornerLayer(myTextBox)
myAdornerLayer.Add(New SimpleCircleAdorner(myTextBox))

myAdornerLayer = AdornerLayer.GetAdornerLayer(myTextBox);
myAdornerLayer.Add(new SimpleCircleAdorner(myTextBox));

Hinweis
Die Verwendung von Extensible Application Markup Language (XAML) zum Binden eines Adorners an ein anderes Element wird derzeit nicht unterstützt.

Verzieren der untergeordneten Elemente eines Bereichs

Um einen Adorner an die untergeordneten Elemente eines Panel zu binden, führen Sie diese Schritte aus:

 

1. Rufen Sie die static Methode GetAdornerLayer auf, um eine Adornerebene für das Element zu finden, dessen untergeordnete Elemente verziert werden sollen.

2. Durchlaufen Sie die untergeordneten Elemente des übergeordneten Elements, und rufen Sie die Add-Methode auf, um einen Adorner an jedes untergeordnete Element zu binden.

Im folgenden Beispiel wird ein SimpleCircleAdorner (siehe weiter oben) an die untergeordneten Elemente eines StackPanel mit dem Namen myStackPanel gebunden.

            For Each toAdorn As UIElement In myStackPanel.Children
                myAdornerLayer.Add(New SimpleCircleAdorner(toAdorn))
            Next

foreach (UIElement toAdorn in myStackPanel.Children)
  myAdornerLayer.Add(new SimpleCircleAdorner(toAdorn));

Siehe auch

Referenz

AdornerHitTestResult

Konzepte

Übersicht über Formen und die grundlegenden Funktionen zum Zeichnen in WPF

Zeichnen mit Bildern, Zeichnungen und visuellen Elementen

Übersicht über Zeichnungsobjekte

Weitere Ressourcen

Gewusst-wie-Themen zu Adorner