Usare i pennelli per colorare gli sfondi, i primi piani e i profili

Usa gli oggetti Brush per colorare l'interno e il contorno di forme, testo e controlli XAML, rendendoli visibili nell'interfaccia utente della tua applicazione.

API importanti: Classe Brush

Introduzione ai pennelli

Per colorare un elemento Shape, testo o parti di un elemento Control visualizzato nell'area di disegno dell'app, imposta la proprietà Fill dell'elemento Shape o le proprietà Background e Foreground di un elemento Control su un valore Brush.

I diversi tipi di pennelli disponibili sono:

• AcrylicBrush
• SolidColorBrush
• LinearGradientBrush
• RadialGradientBrush
• ImageBrush
• WebViewBrush
• XamlCompositionBrushBase

Pennelli tinta unita

Un oggetto SolidColorBrush consente di disegnare un'area con un'unica struttura Color, ad esempio rosso o blu. È il pennello più semplice. In XAML esistono tre modi per definire un oggetto SolidColorBrush e il colore che specifica: nomi di colore predefiniti, valori di colore esadecimali o la sintassi degli elementi di proprietà.

Nomi di colore predefiniti

Puoi usare un nome di colore predefinito, ad esempio Yellow o Magenta. Sono disponibili 256 nomi di colore. Il parser XAML converte il nome del colore in una struttura Color con i canali di colore corretti. I 256 nomi di colori si basano sui nomi di colori X11 della specifica CSS3 (Cascading Style Sheets, livello 3) ed è probabile che tu abbia già familiarità con questo elenco di nomi di colori se hai esperienza nello sviluppo o nella progettazione Web.

In questo esempio la proprietà Fill di un oggetto Rectangle verrà impostata sul colore predefinito Red.

<Rectangle Width="100" Height="100" Fill="Red" />

SolidColorBrush applicato a un rettangolo

Se definisci un oggetto SolidColorBrush usando codice anziché XAML, ogni nome di colore sarà disponibile come valore di proprietà statico della classe Colors. Ad esempio, per dichiarare un valore Color di un oggetto SolidColorBrush per rappresentare il nome di colore "Orchid", imposta il valore Color sul valore statico Colors.Orchid.

Valori di colore esadecimali

Puoi usare una stringa in formato esadecimale per dichiarare valori di colori a 24 bit precisi con canale alfa a 8 bit per un oggetto SolidColorBrush. Ogni valore di componente è definito da due caratteri compresi nell'intervallo 0-F e l'ordine dei valori della stringa esadecimale è il seguente: canale alfa (opacità), canale rosso, canale verde e canale blu (ARGB). Ad esempio, il valore esadecimale "#FFFF0000" definisce il rosso completamente opaco (alfa="FF", rosso="FF", verde="00" e blu="00").

Questo esempio XAML imposta la proprietà Fill di un oggetto Rectangle sul valore esadecimale "#FFFF0000" e fornisce un risultato identico a quello che si ottiene usando il nome di colore Colors.Red.

<StackPanel>
  <Rectangle Width="100" Height="100" Fill="#FFFF0000" />
</StackPanel>

Sintassi per gli elementi proprietà

Per definire un oggetto SolidColorBrush, puoi usare la sintassi degli elementi di proprietà. Questa sintassi è più dettagliata rispetto ai metodi precedenti, ma ti permette di specificare valori di proprietà aggiuntivi di un elemento, ad esempio Opacity. Per altre informazioni sulla sintassi XAML, inclusa la sintassi degli elementi di proprietà, vedi Panoramica di XAML e Guida alla sintassi XAML.

Negli esempi precedenti, il pennello viene creato in modo implicito e automatico come parte di una sintassi abbreviata del linguaggio XAML che consente di mantenere semplici le definizioni dell'interfaccia utente per i casi più comuni. Nell'esempio seguente viene creato un elemento Rectangle e viene esplicitamente creato l'oggetto SolidColorBrush come valore dell'elemento per una proprietà Rectangle.Fill. La proprietà Color di SolidColorBrush è impostata su Blue e la proprietà Opacity è impostata su 0.5.

<Rectangle Width="200" Height="150">
    <Rectangle.Fill>
        <SolidColorBrush Color="Blue" Opacity="0.5" />
    </Rectangle.Fill>
</Rectangle>

Pennelli sfumatura lineare

Un oggetto LinearGradientBrush disegna un'area con una sfumatura definita lungo una linea, che è definita asse della sfumatura. Devi specificare i colori della sfumatura e le relative posizioni lungo l'asse tramite oggetti GradientStop. Per impostazione predefinita, l'asse della sfumatura va dall'angolo superiore sinistro all'angolo inferiore destro dell'area disegnata dal pennello, creando un'ombreggiatura diagonale.

GradientStop è il blocco predefinito di base di un pennello sfumatura. Un cursore sfumatura specifica il valore Color del pennello in corrispondenza di una proprietà Offset lungo l'asse della sfumatura, quando il pennello viene applicato all'area da disegnare.

La proprietà Color del cursore sfumatura specifica il colore di tale cursore. Puoi impostare il colore usando un nome predefinito oppure specificando i valori ARGB esadecimali.

La proprietà Offset di un oggetto GradientStop specifica la posizione di ogni GradientStop lungo l'asse della sfumatura. Offset è una proprietà double con valore compreso tra 0 e 1. Con un valore di Offset pari a 0, l'oggetto GradientStop si trova all'inizio dell'asse della sfumatura, ossia vicino al relativo StartPoint. Con un valore di Offset pari a 1, l'oggetto GradientStop si trova in corrispondenza di EndPoint. Un oggetto LinearGradientBrush utile deve avere almeno due valori di GradientStop e ogni valore di GradientStop deve specificare una diversa proprietà Color e avere un valore di Offset diverso (0 o 1).

In questo esempio viene creata una sfumatura lineare con quattro colori per disegnare un oggetto Rectangle.

<!-- This rectangle is painted with a diagonal linear gradient. -->
<Rectangle Width="200" Height="100">
    <Rectangle.Fill>
        <LinearGradientBrush StartPoint="0,0" EndPoint="1,1">
            <GradientStop Color="Yellow" Offset="0.0" x:Name="GradientStop1"/>
            <GradientStop Color="Red" Offset="0.25" x:Name="GradientStop2"/>
            <GradientStop Color="Blue" Offset="0.75" x:Name="GradientStop3"/>
            <GradientStop Color="LimeGreen" Offset="1.0" x:Name="GradientStop4"/>
        </LinearGradientBrush>
    </Rectangle.Fill>
</Rectangle>

Il colore di ogni punto tra i cursori sfumatura è linearmente interpolato come combinazione del colore specificato dai due cursori sfumatura di delimitazione. L'immagine seguente evidenzia i cursori sfumatura dell'esempio precedente. I cerchi indicano la posizione dei cursori sfumatura, mentre la linea tratteggiata indica l'asse della sfumatura.

Combinazione dei colori specificati dai due cursori sfumatura di delimitazione

Puoi modificare la linea in cui sono posizionati i cursori sfumatura impostando le proprietà StartPoint ed EndPoint su valori diversi rispetto ai valori predefiniti iniziali (0,0) e (1,1). Modificando i valori delle coordinate StartPoint ed EndPoint, puoi creare sfumature orizzontali o verticali, invertire la direzione della sfumatura o ridurre la distribuzione della sfumatura per applicarla a un intervallo più piccolo rispetto all'intera area colorata. Per ridurre la sfumatura, imposta i valori di StartPoint e/o EndPoint su un numero compreso tra i valori 0 e 1. Ad esempio, per una sfumatura orizzontale in cui la dissolvenza si verifica tutta nella metà sinistra del pennello mentre il lato destro è a tinta unita fino all'ultimo colore di GradientStop, puoi specificare un valore di StartPoint pari a (0,0) e un valore di EndPoint pari a (0.5,0).

Usare gli strumenti per creare sfumature

Ora che sai come funzionano le sfumature lineari, puoi usare Visual Studio o Blend per creare queste sfumature in modo più semplice. Per creare una sfumatura, seleziona l'oggetto a cui vuoi applicare la sfumatura nell'area di progettazione o nella visualizzazione XAML. Espandi Pennello e seleziona la scheda Sfumatura lineare.

Creazione di una sfumatura lineare in Visual Studio

Ora puoi modificare i colori dei cursori sfumatura e far scorrere i cursori usando la barra nella parte inferiore. Puoi anche aggiungere nuovi cursori sfumatura facendo clic sulla barra e rimuoverli trascinando i cursori fuori dalla barra (vedi lo screenshot seguente).

Dispositivo di scorrimento per l'impostazione della sfumatura

Pennelli sfumatura radiale

Un oggetto RadialGradientBrush viene disegnato con un'ellisse definita dalle proprietà Center, RadiusX e RadiusY. I colori della sfumatura iniziano al centro dell'ellisse e terminano in corrispondenza del raggio.

I colori della sfumatura radiale sono definiti da cursori sfumatura aggiunti alla proprietà della raccolta GradientStops. Ogni cursore sfumatura specifica un colore e un offset lungo la sfumatura.

Per impostazione predefinita, l'origine della sfumatura è al centro e può essere scostata usando la proprietà GradientOrigin.

MappingMode definisce se Center, RadiusX, RadiusY e GradientOrigin rappresentano coordinate relative o assolute.

Quando MappingMode è impostato su RelativeToBoundingBox, i valori X e Y delle tre proprietà vengono considerati come relativi rispetto ai limiti dell'elemento, dove (0,0) rappresenta la parte superiore sinistra e (1,1) rappresenta la parte inferiore destra dei limiti dell'elemento per le proprietà Center, RadiusX e RadiusY e (0,0) rappresenta il centro per la proprietà GradientOrigin.

Quando MappingMode è impostato su Absolute, i valori X e Y delle tre proprietà vengono considerati come coordinate assolute all'interno dei limiti dell'elemento.

In questo esempio viene creata una sfumatura lineare con quattro colori per disegnare un oggetto Rectangle.

<!-- This rectangle is painted with a radial gradient. -->
<Rectangle Width="200" Height="200">
    <Rectangle.Fill>
        <media:RadialGradientBrush>
            <GradientStop Color="Blue" Offset="0.0" />
            <GradientStop Color="Yellow" Offset="0.2" />
            <GradientStop Color="LimeGreen" Offset="0.4" />
            <GradientStop Color="LightBlue" Offset="0.6" />
            <GradientStop Color="Blue" Offset="0.8" />
            <GradientStop Color="LightGray" Offset="1" />
        </media:RadialGradientBrush>
    </Rectangle.Fill>
</Rectangle>

Il colore di ogni punto tra i cursori sfumatura è radialmente interpolato come combinazione del colore specificato dai due cursori sfumatura di delimitazione. L'immagine seguente evidenzia i cursori sfumatura dell'esempio precedente.

Cursori sfumatura

Pennelli immagine

Un oggetto ImageBrush disegna un'area con un'immagine la cui origine è un file di immagine. Puoi impostare la proprietà ImageSource con il percorso dell'immagine da caricare. In genere, l'origine dell'immagine viene ricavata da un elemento Content che fa parte delle risorse dell'app.

Per impostazione predefinita, un oggetto ImageBrush estende l'immagine in modo da riempire completamente l'area disegnata, eventualmente distorcendo l'immagine se le proporzioni dell'area sono diverse rispetto all'immagine. Puoi modificare questo comportamento sostituendo il valore predefinito della proprietà Stretch, Fill, con None, Uniform o UniformToFill.

Nell'esempio seguente viene creato un oggetto ImageBrush e la proprietà ImageSource viene impostata su un'immagine denominata licorice.jpg, che deve essere inclusa come risorsa nell'app. L'oggetto ImageBrush disegna quindi l'area definita da una forma Ellipse.

<Ellipse Height="200" Width="300">
   <Ellipse.Fill>
     <ImageBrush ImageSource="licorice.jpg" />
   </Ellipse.Fill>
</Ellipse>

Rendering di un oggetto ImageBrush

ImageBrush e Image fanno entrambi riferimento al file di origine dell'immagine tramite URI (Uniform Resource Identifier), dove tale file di origine dell'immagine usa diversi formati di immagine. Questi file di origine dell'immagine sono specificati come URI. Per altre informazioni su come specificare le origini di immagini e i formati immagine utilizzabili e sulla creazione dei relativi pacchetti in un'app, vedi Image e ImageBrush.

Pennelli e testo

Puoi usare i pennelli anche per applicare caratteristiche di rendering a elementi di testo. Ad esempio, la proprietà Foreground di un oggetto TextBlock accetta un oggetto Brush. Puoi applicare al testo qualsiasi pennello descritto in questo argomento. Tuttavia, presta attenzione ai pennelli applicati al testo, in quanto qualsiasi sfondo potrebbe rendere illeggibile il testo se si usano pennelli che penetrano nello sfondo. Nella maggior parte dei casi, per migliorare la leggibilità di elementi di testo che non siano puramente decorativi, è consigliabile usare l'oggetto SolidColorBrush.

Anche se usi una tinta unita, verifica che il colore del testo scelto abbia un contrasto sufficiente rispetto al colore di sfondo del contenitore del layout del testo. Il livello di contrasto tra il testo in primo piano e lo sfondo del contenitore del testo è un elemento da tenere presente per l'accessibilità.

WebViewBrush

Un oggetto WebViewBrush è un tipo speciale di pennello che può accedere al contenuto normalmente visualizzato in un controllo WebView. Anziché eseguire il rendering del contenuto nell'area di controllo WebView rettangolare, WebViewBrush disegna il contenuto in un altro elemento che ha una proprietà di tipo Brush per una superficie di rendering. WebViewBrush non è appropriato per ogni scenario, ma è utile per le transizioni di un oggetto WebView. Per altre info, vedi WebViewBrush.

XamlCompositionBrushBase

XamlCompositionBrushBase è una classe di base usata per creare pennelli personalizzati che usano CompositionBrush per disegnare elementi dell'interfaccia utente XAML.

In questo modo viene abilitata l'interoperabilità "a discesa" tra i livelli Windows.UI.Xaml e Windows.UI "come descritto nella panoramica sul livello visivo.

Per creare un pennello personalizzato, crea una nuova classe che eredita da XamlCompositionBrushBase e implementa i metodi necessari.

Ad esempio, può essere usata per applicare effetti agli oggetti UIElements XAML tramite un oggetto CompositionEffectBrush, ad esempio GaussianBlurEffect o SceneLightingEffect che controlla le proprietà riflettenti di un oggetto UIElement XAML quando illuminato da un oggetto XamlLight.

Per alcuni esempi di codice, vedi XamlCompositionBrushBase.

Pennelli come risorse XAML

Puoi dichiarare qualsiasi pennello come risorsa XAML con chiave in un dizionario di risorse XAML. In questo modo, è facile replicare gli stessi valori di pennello applicati a più elementi in un'interfaccia utente. I valori di pennello vengono quindi condivisi e applicati a ogni caso in cui fai riferimento alla risorsa pennello come utilizzo di {StaticResource} in XAML. Sono inclusi i casi in cui è disponibile un modello di controllo XAML che fa riferimento al pennello condiviso e il modello di controllo è anch'esso una risorsa XAML con chiave.

Pennelli nel codice

In genere, i pennelli vengono specificati tramite XAML anziché usando codice per definirli. Il motivo è che i pennelli vengono solitamente definiti come risorse XAML e i valori dei pennelli costituiscono spesso l'output di strumenti di progettazione o fanno comunque parte di una definizione di interfaccia utente XAML. Per i rari casi in cui potresti decidere di definire un pennello mediante codice, sono comunque disponibili tutti i tipi di Brush per la creazione di istanze di codice.

Per creare un oggetto SolidColorBrush nel codice, usa il costruttore che accetta un parametro Color. Passa un valore che corrisponde a una proprietà statica della classe Colors, come illustrato di seguito:

SolidColorBrush blueBrush = new SolidColorBrush(Windows.UI.Colors.Blue);

Dim blueBrush as SolidColorBrush = New SolidColorBrush(Windows.UI.Colors.Blue)

Windows::UI::Xaml::Media::SolidColorBrush blueBrush{ Windows::UI::Colors::Blue() };

blueBrush = ref new SolidColorBrush(Windows::UI::Colors::Blue);

Per WebViewBrush e ImageBrush, usa il costruttore predefinito e quindi chiama altre API prima di provare a usare il pennello per una proprietà dell'interfaccia utente.

• ImageSource richiede BitmapImage (non un URI) quando definisci ImageBrush mediante codice. Se l'origine è un flusso, usa il metodo SetSourceAsync per inizializzare il valore. Se l'origine è un URI, che include il contenuto dell'app che usa gli schemi ms-appx o ms-resource, usa il costruttore BitmapImage che accetta un URI. Puoi anche valutare se gestire l'evento ImageOpened in caso di problemi di tempo con il recupero o la decodifica dell'origine dell'immagine, per cui potresti avere la necessità di visualizzare contenuto alternativo finché l'origine dell'immagine non diventa disponibile.
• Per WebViewBrush potresti dover chiamare Redraw se hai di recente reimpostato la proprietà SourceName oppure se viene modificato anche il contenuto di WebView con il codice.

Per alcuni esempi di codice, vedi WebViewBrush, ImageBrush e XamlCompositionBrushBase.