Cenni preliminari sugli strumenti decorativi visuali

Gli strumenti decorativi visuali sono un tipo speciale di FrameworkElement che fornisce all'utente segnali visivi. Gli strumenti decorativi visuali possono anche essere utilizzati per aggiungere handle funzionali a elementi o fornire informazioni sullo stato di un controllo.

Nel presente argomento sono contenute le seguenti sezioni.

• Informazioni sugli strumenti decorativi visuali
• Implementazione di uno strumento decorativo visuale personalizzato
• Comportamento di rendering degli strumenti decorativi visuali
• Eventi e hit testing
• Decorazione di un singolo UIElement
• Decorazione di elementi figlio di un oggetto Panel
• Argomenti correlati

Informazioni sugli strumenti decorativi visuali

Un oggetto Adorner è un oggetto FrameworkElement personalizzato associato a un oggetto UIElement. Il rendering degli strumenti decorativi visuali viene eseguito in un oggetto AdornerLayer, una superficie di rendering che si trova sempre sopra l'elemento decorato o un insieme di elementi decorati. Il rendering di uno strumento decorativo è indipendente dal rendering dell'oggetto UIElement a cui lo strumento decorativo visuale è associato. La posizione di uno strumento decorativo visuale è in genere relativa all'elemento a cui è associato, utilizzando l'origine delle coordinate standard bidimensionali poste in alto a sinistra rispetto all'elemento decorato.

Le applicazioni comuni degli strumenti decorativi visuali includono:

• Aggiunta di handle funzionali a un oggetto UIElement che consentono a un utente di modificare (ridimensionare, ruotare, riposizionare e così via) l'elemento.

• Fornire feedback visuale per indicare vari stati o in risposta a vari eventi.

• Sovrapporre decorazioni visuali su un oggetto UIElement.

• Mascherare visivamente o eseguire l'override di una parte o dell'intero oggetto UIElement.

Windows Presentation Foundation (WPF) fornisce un framework di base per la decorazione di elementi visivi. Nella tabella riportata di seguito vengono elencati i tipi primari utilizzati per la decorazione di oggetti e ne viene descritto lo scopo. Seguiranno alcuni esempi di utilizzo.

Adorner	Una classe base astratta da cui ereditano tutte le implementazioni concrete di elementi decorativi visuali.
AdornerLayer	Una classe che rappresenta un livello di rendering per lo strumento o gli strumenti decorativi visuali di uno o più elementi decorati.
AdornerDecorator	Una classe che consente l'associazione di un livello dello strumento decorativo visuale a un insieme di elementi.

Implementazione di uno strumento decorativo visuale personalizzato

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

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

Nell'esempio di codice riportato di seguito viene illustrata una classe che implementa un semplice strumento decorativo visuale. Lo strumento decorativo dell'esempio decora semplicemente gli angoli di un oggetto UIElement con dei cerchi.

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

Nell'immagine riportata di seguito viene illustrato lo strumento decorativo SimpleCircleAdorner a un oggetto TextBox.

Comportamento di rendering degli strumenti decorativi visuali

È importante notare che gli strumenti decorativi non comprendono comportamenti di rendering intrinseci; garantire che uno strumento decorativo esegua il rendering è responsabilità dell'implementatore. Un modo comune di implementare un comportamento di rendering consiste nell'eseguire l'override del metodo OnRender e nell'utilizzare uno o più oggetti DrawingContext per eseguire il rendering degli elementi visivi dello strumento decorativo in base alle esigenze (come illustrato in questo esempio).

Nota
Qualsiasi elemento posizionato sul livello dello strumento decorativo viene sottoposto a rendering sopra tutti gli altri stili eventualmente impostati.In altre parole, gli strumenti decorativi sono sempre "in primo piano" e il loro override non può essere eseguito tramite l'ordine Z.

Eventi e hit testing

Gli strumenti decorativi visuali ricevono eventi di input come qualsiasi altro FrameworkElement. Poiché uno strumento decorativo visuale presenta un ordine Z più elevato rispetto all'elemento da decorare, lo strumento decorativo visuale riceve eventi di input, ad esempio Drop o MouseMove, che potrebbero essere destinati all'elemento decorato sottostante. Uno strumento decorativo visuale può rimanere in ascolto di determinati eventi di input e passare gli eventi ricevuti all'elemento decorato sottostante generando nuovamente l'evento.

Per abilitare l'hit testing pass-through di elementi sotto uno strumento decorativo visuale, impostare la proprietà IsHitTestVisible di hit testing su false sullo strumento decorativo visuale. Per ulteriori informazioni sull'hit testing, vedere

Hit testing a livello visivo.

Decorazione di un singolo UIElement

Per associare uno strumento decorativo visuale a un particolare oggetto UIElement, seguire questi passaggi:

1. Chiamare il metodo statico GetAdornerLayer per ottenere un oggetto AdornerLayer per l'elemento UIElement da decorare. GetAdornerLayer risale la struttura ad albero visuale, partendo dall'oggetto UIElement specificato e restituisce il primo livello dello strumento decorativo trovato. (Se non viene trovato alcun livello dello strumento decorativo, il metodo restituisce null.)

2. Chiamare il metodo Add per associare lo strumento decorativo visuale all'oggetto UIElement di destinazione.

Nell'esempio riportato di seguito viene associato un SimpleCircleAdorner (illustrato in precedenza) a un controllo TextBox denominato myTextBox.

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

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

Nota
Non è al momento possibile utilizzare Extensible Application Markup Language (XAML) per associare uno strumento decorativo visuale a un altro elemento.

Decorazione di elementi figlio di un oggetto Panel

Per associare uno strumento decorativo visuale agli elementi figlio di un oggetto Panel, seguire questi passaggi:

 

1. Chiamare il metodo staticGetAdornerLayer per trovare un livello dello strumento decorativo visuale per l'elemento di cui decorare gli elementi figlio.

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

Nell'esempio riportato di seguito viene associato un SimpleCircleAdorner (illustrato in precedenza) agli elementi figlio di un oggetto StackPanel denominato myStackPanel.

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

Vedere anche

Riferimenti

AdornerHitTestResult

Concetti

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

Altre risorse

Procedure relative agli elementi grafici