Översikt över dekoreringar

Artikel
12/18/2024

Utsmyckningar är en särskild typ av FrameworkElement, som används för att ge visuella ledtrådar till en användare. Bland andra användningsområden kan Adorners användas för att lägga till funktionella handtag till element eller för att ge tillståndsinformation om en kontroll.

Om utsmyckningar

En Adorner är en anpassad FrameworkElement som är bunden till en UIElement. Utsmyckningar visas i en AdornerLayer, vilket utgör en återgivningsyta som alltid befinner sig ovanpå det utsmyckade elementet eller en samling utsmyckade element. Återgivning av en prydnad är oberoende av återgivning av UIElement som prydnaden är kopplad till. En prydnad är vanligtvis placerad i förhållande till det element som den är bunden till, med hjälp av standard 2D-koordinatsystemets ursprung som finns längst upp till vänster i det dekorerade elementet.

Vanliga användningsområden för utsmyckningar är:

Lägga till funktionella handtag till en UIElement som gör det möjligt för en användare att manipulera elementet på något sätt (ändra storlek, rotera, flytta osv.).
Ge visuell feedback för att ange olika tillstånd eller som svar på olika händelser.
Överlägg visuella dekorationer på en UIElement.
Maskera eller åsidosätt en del av eller hela ett UIElement.

Windows Presentation Foundation (WPF) tillhandahåller ett grundläggande ramverk för att pryda visuella element. I följande tabell visas de primära typer som används vid utsmyckning av objekt och deras syfte. Flera användningsexempel följer:

Klass	Beskrivning
Adorner	En abstrakt basklass från vilken alla konkreta implementeringar av prydnader ärver.
AdornerLayer	En klass som representerar ett återgivningslager för utsmyckningarna för ett eller flera utsmyckningselement.
AdornerDecorator	En klass som gör att ett utsmyckningslager kan associeras med en samling element.

Implementera en anpassad utsmyckning

Utsmyckningsramverket som tillhandahålls av Windows Presentation Foundation (WPF) är främst avsett att stödja skapandet av anpassade utsmyckningar. En anpassad adorner skapas genom att implementera en klass som ärver från den abstrakta Adorner-klassen.

Obs

Förälder till en Adorner är den AdornerLayer som renderar Adorner, inte det element som pryds.

I följande exempel visas en klass som implementerar en enkel prydnad. Exempeldekorationen utsmyckar bara hörnen av en UIElement med cirklar.

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

Följande bild visar SimpleCircleAdorner som tillämpas på en TextBox:

Skärmbild som visar en utsmyckad textruta.

Återgivningsbeteende för utsmyckningar

Det är viktigt att notera att förskönare inte har något inbyggt återgivningsbeteende; det är förskönarens implementerares ansvar att säkerställa att en förskönare återges. Ett vanligt sätt att implementera återgivningsbeteende är att åsidosätta metoden OnRender och använda ett eller flera DrawingContext objekt för att återge utsmyckningens visuella objekt efter behov (som du ser i exemplet ovan).

Not

Allt som placeras i utsmyckningsskiktet återges ovanpå resten av de format du har angett. Med andra ord är utsmyckningar alltid visuellt överst och kan inte åsidosättas med z-ordning.

Händelser och träfftestning

Adorners får indatahändelser precis som vilken annan FrameworkElementsom helst. Eftersom en utsmyckning alltid har en högre z-ordning än elementet den pryder, får utsmyckningen indatahändelser (till exempel Drop eller MouseMove) som kan vara avsedda för det underliggande prydnadselementet. En dekoration kan lyssna efter vissa indatahändelser och skicka dessa vidare till det underliggande dekorerade elementet genom att utlösa händelsen igen.

Om du vill aktivera pass-through träfftestning av element under en adorner ställer du in träfftestegenskapen IsHitTestVisible till falskt på adornern. Mer information om träfftestning finns i Träfftestning i Visual Layer.

Dekorera ett enda UIElement

Följ dessa steg om du vill binda en utsmyckning till en viss UIElement:

Anropa den statiska metoden GetAdornerLayer för att hämta ett AdornerLayer objekt för UIElement som ska prydas. GetAdornerLayer går upp i det visuella trädet med början vid angiven UIElementoch returnerar det första utsmyckningsskiktet som hittas. (Om inga utsmyckningslager hittas returnerar metoden null.)
Anropa metoden Add för att binda utsmyckningen till målet UIElement.

I följande exempel binds en SimpleCircleAdorner (visas ovan) till en TextBox med namnet myTextBox:

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

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

Anmärkning

Användning av XAML (Extensible Application Markup Language) för att binda en utsmyckning till ett annat element stöds för närvarande inte.

Pröjsa barnen i en panel

Följ dessa steg för att binda en utsmyckning till barnen av en Panel-enhet:

Anropa static-metoden GetAdornerLayer för att hitta ett utsmyckningslager för det element vars barn ska dekoreras.
Iterera igenom barnen till förälderlementet och anropa metoden Add för att binda en utsmyckning till varje barnelement.

I följande exempel binds en SimpleCircleAdorner (visas ovan) till barnen i en StackPanel som heter myStackPanel:

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

Dela via