Panoramica sugli strumenti decorativi

Gli strumenti decorativi sono un tipo speciale di FrameworkElement, usato per fornire segnali visivi a un utente. Tra l'altro, è possibile usare gli strumenti decorativi per aggiungere handle funzionali agli elementi o fornire informazioni sullo stato relative a un controllo.

Informazioni sugli strumenti decorativi

Un Adorner oggetto è un oggetto personalizzato FrameworkElement associato a un oggetto UIElement. Il rendering degli strumenti decorativi viene eseguito in un AdornerLayeroggetto , ovvero una superficie di rendering sempre in cima all'elemento adornato o a una raccolta di elementi adornati. Il rendering di uno strumento decorativo è indipendente dal rendering dell'oggetto UIElement a cui è associato lo strumento decorativo. Uno strumento decorativo viene in genere posizionato rispetto all'elemento a cui è associato, utilizzando l'origine della coordinata 2D standard situata in alto a sinistra dell'elemento decorato.

Applicazioni comuni per gli strumenti decorativi includono:

• Aggiunta di handle funzionali a un UIElement oggetto che consente a un utente di modificare l'elemento in qualche modo (ridimensionare, ruotare, riposizionare e così via).
• Fornire indicazioni visive per identificare i vari stati, oppure in risposta a vari eventi.
• Sovrapporre le decorazioni visive su un oggetto UIElement.
• Mascherare visivamente o eseguire l'override di una parte o di un oggetto UIElement.

Windows Presentation Foundation (WPF) fornisce un framework di base per adornare gli elementi visivi. La tabella seguente include i principali tipi usati per la decorazione di oggetti e il relativo scopo. Di seguito sono riportati diversi esempi di utilizzo:

Classe	Descrizione
Adorner	Classe di base astratta dalla quale ereditano tutte le implementazioni di strumenti decorativi concreti.
AdornerLayer	Classe che rappresenta un livello di rendering per gli strumenti decorativi di uno o più elementi decorati.
AdornerDecorator	Classe che consente di associare un livello dello strumento decorativo a una raccolta di elementi.

Implementazione di uno strumento decorativo personalizzato

Il framework degli strumenti decorativi fornito da Windows Presentation Foundation (WPF) è destinato principalmente a supportare la creazione di strumenti decorativi personalizzati. Uno strumento decorativo personalizzato viene creato implementando una classe che eredita dalla classe astratta Adorner .

Nota

L'elemento padre di è Adorner l'oggetto AdornerLayer che esegue il rendering di Adorner, non l'elemento decorato.

L'esempio seguente mostra una classe che implementa uno strumento decorativo semplice. Lo strumento decorativo di esempio adorna semplicemente gli angoli di un oggetto UIElement con cerchi.

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

L'immagine seguente mostra l'oggetto SimpleCircleAdorner applicato a un oggetto TextBox:

Comportamento di rendering per gli strumenti decorativi

È importante notare che gli strumenti decorativi non includono alcun comportamento di rendering inerente, pertanto è responsabilità dell'implementatore garantire il rendering di uno strumento decorativo visuale. Un modo comune per implementare il comportamento di rendering consiste nell'eseguire l'override del OnRender metodo e usare uno o più DrawingContext oggetti per eseguire il rendering degli oggetti visivi dello strumento decorativo in base alle esigenze (come illustrato nell'esempio precedente).

Nota

Il rendering di qualsiasi elemento posizionato nel livello degli strumenti decorativi viene eseguito al di sopra degli altri stili impostati. In altre parole, gli strumenti decorativi vengono sempre visualizzati al di sopra degli altri elementi e non possono essere sottoposti a override tramite l'ordine z.

Eventi e hit test

Gli strumenti decorativi ricevono eventi di input come qualsiasi altro FrameworkElementoggetto . Poiché uno strumento decorativo ha sempre un ordine z superiore rispetto all'elemento che adorna, lo strumento decorativo riceve gli eventi di input (ad esempio Drop o MouseMove) che possono essere destinati all'elemento adornato sottostante. Uno strumento decorativo può ascoltare determinati eventi di input e passare tali valori all'elemento decorato sottostante generando nuovamente l'evento.

Per abilitare l'hit test pass-through degli elementi in uno strumento decorativo, impostare la proprietà hit test IsHitTestVisible su false sullo strumento decorativo. Per altre informazioni sull'hit testing, vedere Hit Testing nel livello visivo.

Decorazione di un singolo UIElement

Per associare uno strumento decorativo a un particolare UIElementoggetto , seguire questa procedura:

1. Chiamare il metodo GetAdornerLayer statico per ottenere un AdornerLayer oggetto per l'oggetto UIElement da adornare. GetAdornerLayer scorre la struttura ad albero visuale, a partire dall'oggetto specificato UIElemente restituisce il primo livello decorativo trovato. (se non viene trovato alcun livello dello strumento decorativo, il metodo restituisce null).

2. Chiamare il Add metodo per associare lo strumento decorativo alla destinazione UIElement.

Nell'esempio seguente viene associato un oggetto SimpleCircleAdorner (illustrato sopra) a un TextBox oggetto denominato myTextBox:

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

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

Nota

L'uso del linguaggio XAML (Extensible Application Markup Language) per associare uno strumento decorativo a un altro elemento non è attualmente supportato.

Decorazione degli elementi figlio di un elemento Panel

Per associare uno strumento decorativo agli elementi figlio di un Paneloggetto , seguire questa procedura:

1. Chiamare il static metodo GetAdornerLayer per trovare un livello decorativo per l'elemento i cui elementi figlio devono essere adornati.

2. Enumerare gli elementi figlio dell'elemento padre e chiamare il Add metodo per associare uno strumento decorativo a ogni elemento figlio.

L'esempio seguente associa simpleCircleAdorner (illustrato sopra) agli elementi figlio di un StackPanel myStackPanel denominato:

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

Vedi anche

• AdornerHitTestResult
• Cenni preliminari sugli oggetti Shape e sulle funzionalità di disegno di base di WPF
• Disegnare con oggetti Image, Drawing e Visual
• Cenni preliminari sugli oggetti Drawing
• Procedure relative alle risorse