Übersicht über Adorner

  • Artikel

Als Adorner wird ein spezieller FrameworkElement-Typ bezeichnet, der zum Bereitstellen von visuellen Hinweisen für Benutzer*innen verwendet wird. Adorner können unter anderem verwendet werden, um Elementen funktionale Ziehpunkte hinzuzufügen oder Zustandsinformationen über Steuerelemente bereitzustellen.

Informationen über Adorner

Ein Adorner ist ein benutzerdefiniertes FrameworkElement, das an ein UIElement gebunden ist. Adorner werden in einer AdornerLayer-Ebene gerendert, die sich immer über dem Element mit dem Adorner oder über einer Auflistung von Elementen mit Adornern befindet. Das Rendern eines Adorners erfolgt unabhängig vom Rendern des UIElement, an das der Adorner gebunden ist. Ein Adorner wird in der Regel relativ zum Element positioniert, an das er gebunden ist. Dazu wird ein 2D-Standardkoordinatenursprung verwendet, der sich in der linken oberen Ecke des Elements mit dem Adorner befindet.

Adorner finden eine breite Anwendung in folgenden Fällen:

  • Hinzufügen funktionaler Ziehpunkte zu einem UIElement, damit Benutzer*innen das Element auf irgendeine Art und Weise bearbeiten können (Größe ändern, drehen, Position ändern usw.).
  • Bereitstellen von visuellem Feedback, um verschiedene Zustände anzugeben oder auf verschiedene Ereignisse zu reagieren.
  • Überlagern von visuellen Dekorationen auf einem UIElement
  • Visuelles Maskieren oder Überschreiben eines gesamten UIElement oder eines Teils davon

Windows Presentation Foundation (WPF) bietet ein grundlegendes Framework zum Anfügen von Adornern an visuelle Elemente. In der folgenden Tabelle sind die zum Verzieren von Objekten verwendeten primären Typen samt deren Zweck aufgelistet. Im Folgenden finden Sie mehrere Verwendungsbeispiele:

Klasse Beschreibung
Adorner Eine abstrakte Basisklasse, von der alle einzelnen Adornerimplementierungen geerbt werden.
AdornerLayer Eine Klasse, die eine Rendering-Ebene für den (die) Adorner eines oder mehrerer verzierten Elementen darstellt.
AdornerDecorator Eine Klasse, mit der eine Adorner-Ebene einer Auflistung von Elementen zugeordnet werden kann.

Implementierung eines benutzerdefinierten Adorners

Das von Windows Presentation Foundation (WPF) bereitgestellte Adorner-Framework dient in erster Linie zur Unterstützung beim Erstellen benutzerdefinierter Adorner. Ein benutzerdefinierter Adorner wird durch das Implementieren einer Klasse erstellt, die von der abstrakten Adorner-Klasse erbt.

Hinweis

Das übergeordnete Element eines Adorner ist die AdornerLayer, die den Adorner statt des Elements rendert, an das er angefügt ist.

Im folgenden Beispiel wird eine Klasse dargestellt, in der ein einfacher Adorner implementiert wird. In diesem Beispiel fügt der Adorner an den Ecken eines UIElement lediglich Kreise hinzu.

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

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

In der folgenden Abbildung wurde ein SimpleCircleAdorner auf ein TextBox-Element angewandt:

Screenshot that shows an adorned text box.

Renderingverhalten der Adorner

Beachten Sie, dass für Adorner kein Renderingverhalten festgelegt ist. Damit wird sichergestellt, dass für das Rendering die Adorner-Implementierung verantwortlich ist. Zur Implementierung des Renderingverhaltens wird häufig die OnRender-Methode überschrieben, und es werden ein oder mehrere DrawingContext-Objekte verwendet, um die Darstellung des Adorners nach Bedarf zu rendern (wie im oben aufgeführten Beispiel).

Hinweis

Sämtliche Elemente auf der Adorner-Ebene werden vor allen anderen Stilen gerendert, die Sie festgelegt haben. Anders gesagt, befinden sich Adorner visuell stets im Vordergrund und können in der Z-Reihenfolge nicht überschrieben werden.

Ereignisse und Treffertests

Adorner empfangen Eingabeereignisse wie jedes andere FrameworkElement. Da ein Adorner sich in der Z-Reihenfolge immer über dem Element befindet, an das er angefügt wurde, empfängt der Adorner Eingabeereignisse (z. B. Drop oder MouseMove), die möglicherweise an das zugrunde liegende Element gerichtet sind. Ein Adorner kann bestimmte Eingabeereignisse überwachen und diese durch erneutes Auslösen des Ereignisses an das zugrunde liegende verzierte Element weiterleiten.

Um Passthrough-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 auf der visuellen Ebene.

Verzieren eines einzelnen UIElement-Elements

Gehen Sie folgendermaßen vor, um einen Adorner an ein bestimmtes UIElement zu binden:

  1. Rufen Sie die statische GetAdornerLayer-Methode auf, um ein AdornerLayer-Objekt für das UIElement abzurufen, an das der Adorner gebunden werden soll. GetAdornerLayer durchläuft die visuelle Struktur beginnend am angegebenen UIElement und gibt die erste gefundene Adorner-Ebene zurück. (Falls keine Adorner-Ebenen 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 oben) an ein TextBox-Element mit dem Namen myTextBox gebunden:

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

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

Hinweis

Das Binden von Adornern an andere Elemente mit XAML (Extensible Application Markup Language) wird derzeit nicht unterstützt.

Verzieren der untergeordneten Elemente eines Panels

Gehen Sie folgendermaßen vor, um einen Adorner an ein untergeordnetes Element eines Panel zu binden:

  1. Rufen Sie die static Methode GetAdornerLayer auf, um eine Adorner-Ebene für das Element zu finden, an dessen untergeordnete Elemente ein Adorner gebunden werden soll.

  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 oben) an die untergeordneten Elemente eines StackPanel-Elements mit dem Namen myStackPanel gebunden.

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

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

Siehe auch