Adorners Übersicht

Verzierungen sind eine besondere Art von FrameworkElement, die verwendet werden, um einem Benutzer visuelle Hinweise zu bieten. Unter anderem können Adorners verwendet werden, um funktionale Griffe zu Elementen hinzuzufügen oder Zustandsinformationen über ein Steuerelement bereitzustellen.

Über Verzierer

Ein Adorner ist eine benutzerdefinierte FrameworkElement, die an eine UIElementgebunden ist. Verzierungen werden in einer AdornerLayergerendert, eine Renderingoberfläche, die immer über dem verzierten Element oder einer Sammlung von verzierten Elementen liegt. Das Rendern eines Schmuckelements ist unabhängig vom Rendern des UIElement, an das das Schmuckelement gebunden ist. Ein Zierer wird in der Regel relativ zu dem Element positioniert, an das es gebunden ist, wobei der standardmäßige 2D-Koordinatenursprung oben links des verzierten Elements verwendet wird.

Zu den gängigen Anwendungen für die Gestaltungselemente gehören:

• Hinzufügen funktionaler Griffe zu einer UIElement, die es einem Benutzer ermöglichen, das Element interaktiv zu manipulieren (Größe ändern, drehen, umpositionieren usw.).
• Stellen Sie visuelles Feedback bereit, um verschiedene Zustände oder als Reaktion auf verschiedene Ereignisse anzugeben.
• Überlagern Sie visuelle Dekorationen auf einer UIElement.
• Visuell maskieren oder überschreiben Sie einen Teil oder das Ganze von einem UIElement.

Windows Presentation Foundation (WPF) bietet ein grundlegendes Framework zum Schmücken visueller Elemente. In der folgenden Tabelle sind die primären Typen aufgeführt, die beim Verzieren von Objekten verwendet werden, sowie deren Zweck. Es folgen mehrere Verwendungsbeispiele:

Implementieren eines benutzerdefinierten Zierers

Das von der Windows Presentation Foundation (WPF) bereitgestellte Adorner-Framework soll in erster Linie die Erstellung von benutzerdefinierten Adornern unterstützen. Ein benutzerdefinierter Adorner wird erstellt, indem eine Klasse implementiert wird, die von der abstrakten Klasse Adorner erbt.

Das folgende Beispiel zeigt eine Klasse, die einen einfachen Adorner implementiert. Der Beispielschmücker schmückt einfach die Ecken eines UIElement mit Kreisen.

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

Die folgende Abbildung zeigt den SimpleCircleAdorner, der auf eine TextBoxangewendet wurde:

Renderingverhalten für Adorner

Es ist wichtig zu beachten, dass Adorner kein inhärentes Renderverhalten enthalten; es liegt in der Verantwortung des Adorner-Implementierers sicherzustellen, dass ein Adorner gerendert wird. Eine gängige Methode zum Implementieren des Renderingverhaltens besteht darin, die OnRender-Methode außer Kraft zu setzen und ein oder mehrere DrawingContext-Objekte zu verwenden, um die visuellen Elemente des Adorners nach Bedarf zu rendern (wie im obigen Beispiel gezeigt).

Ereignisse und Treffertests

Adorners erhalten Eingabeereignisse wie jede andere FrameworkElement. Da ein Zierer immer eine höhere Z-Reihenfolge aufweist als das Element, das es schmückt, empfängt der Zierer Eingabeereignisse (z. B. Drop oder MouseMove), die für das zugrunde liegende verzierte Element vorgesehen sein können. Ein Adorner kann auf bestimmte Eingabeereignisse lauschen und diese durch erneutes Auslösen an das zugrunde liegende geschmückte Element weitergeben.

Um Pass-Through-Treffertests von Elementen unter einem Zierer zu ermöglichen, legen Sie den Treffertest IsHitTestVisible Eigenschaft auf false auf dem Zierer fest. Weitere Informationen zu Treffertests finden Sie unter Treffertests in der Visual Layer-.

Schmücken eines einzelnen UIElements

Führen Sie die folgenden Schritte aus, um einen Zierer an eine bestimmte UIElementzu binden:

1. Rufen Sie die statische Methode GetAdornerLayer auf, um ein AdornerLayer-Objekt für die zu schmückende UIElement zu erhalten. GetAdornerLayer durchläuft den visuellen Baum, beginnend bei der angegebenen UIElement, und gibt den ersten gefundenen Adorner-Layer zurück. (Wenn keine Adorner-Ebenen gefunden werden, gibt die Methode null zurück.)

2. Rufen Sie die Add-Methode auf, um den Zierer an das Ziel UIElementzu binden.

Im folgenden Beispiel wird ein SimpleCircleAdorner (siehe oben) an eine TextBox namens myTextBoxgebunden:

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

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

Schmücken der Kinder eines Panels

Führen Sie die folgenden Schritte aus, um einen Zierer an die Untergeordneten eines Panelzu binden:

1. Rufen Sie die static-Methode GetAdornerLayer auf, um eine Verzierungsschicht für das Element zu finden, für dessen untergeordnete Elemente eine Verzierung vorgesehen ist.

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

Im folgenden Beispiel wird ein SimpleCircleAdorner (siehe oben) an die untergeordneten Elemente eines StackPanel namens myStackPanelgebunden:

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

• AdornerHitTestResult
• Formen und Grundlagen des Zeichnens in WPF Übersicht
• Malerei mit Bildern, Zeichnungen und visuellen Elementen
• übersicht über Zeichnungsobjekte
• Anleitungsthemen