Utilisation de pinceaux pour peindre des arrière-plans, des premier plan et des contours

Utilisez les objets de pinceau pour peindre les intérieurs et les contours des formes, du texte et des contrôles XAML, afin de les rendre visibles dans l’interface utilisateur de votre application.

L’application WinUI 3 Gallery inclut des exemples interactifs de la plupart des contrôles, des caractéristiques et des fonctionnalités de WinUI 3. Obtenir l’application à partir du Microsoft Store ou obtenir le code source sur GitHub

Présentation des pinceaux

Pour peindre une Forme, du texte ou des parties d’un contrôle qui s’affiche sur le canevas de l’application, définissez la propriété de remplissage de la Forme ou les propriétés d'arrière-plan et de premier plan d’un contrôle sur une valeur de pinceau .

Les différents types de pinceaux sont les suivants :

• BrosseAcrylique
• PinceauCouleurSolide
• LinearGradientBrush
• RadialGradientBrush
• ImageBrush
• XamlCompositionBrushBase

Pinceaux de couleur unie

Un SolidColorBrush peint une zone avec une seule couleur, comme le rouge ou le bleu. Il s’agit du pinceau le plus simple. En XAML, il existe trois façons de définir un SolidColorBrush et la couleur spécifiée : noms de couleurs prédéfinis, valeurs de couleur hexadécimales ou syntaxe de l’élément de propriété.

Noms de couleurs prédéfinis

Vous pouvez utiliser un nom de couleur prédéfini, tel que Jaune ou Magenta. Il existe 256 couleurs nommées disponibles. L’analyseur XAML convertit le nom de couleur en structure couleur avec les canaux de couleur appropriés. Les 256 couleurs nommées sont basées sur les noms de couleurs X11 de la spécification Feuilles de style en cascade, Niveau 3 (CSS3), vous pouvez donc déjà être familiarisé avec cette liste de couleurs nommées si vous avez déjà une expérience antérieure avec le développement web ou la conception.

Voici un exemple qui définit la propriété Fill d’un Rectangle sur la couleur rouge prédéfinie.

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

SolidColorBrush appliqué à un rectangle

Si vous définissez un SolidColorBrush à l’aide de code plutôt que XAML, chaque couleur nommée est disponible en tant que valeur de propriété statique de la classe Colors . Par exemple, pour déclarer une valeur de couleur d’un SolidColorBrush pour représenter la couleur nommée « Orchid », définissez la valeur Color sur la valeur statique Colors.Orchid.

Valeurs de couleur hexadécimales

Vous pouvez utiliser une chaîne de format hexadécimale pour déclarer des valeurs de couleur 24 bits précises avec un canal alpha 8 bits pour un SolidColorBrush. Deux caractères de la plage 0 à F définissent chaque valeur de composant, et l’ordre de valeur du composant de la chaîne hexadécimale est : canal alpha (opacité), canal rouge, canal vert et canal bleu (ARGB). Par exemple, la valeur hexadécimale « #FFFF0000 » définit un rouge entièrement opaque (alpha="FF », red="FF », green="00 », et blue="00 »).

Cet exemple XAML définit la propriété Fill d’un rectangle sur la valeur hexadécimale « #FFFF0000 », et donne un résultat identique à l’utilisation de la couleur nommée Colors.Red.

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

Syntaxe de l’élément Property

Vous pouvez utiliser la syntaxe d’élément de propriété pour définir une SolidColorBrush. Cette syntaxe est plus détaillée que les méthodes précédentes, mais vous pouvez spécifier des valeurs de propriété supplémentaires sur un élément, telles que l’opacité. Pour plus d'informations sur la syntaxe XAML, y compris la syntaxe de l'élément de propriété, consultez la vue d'ensemble XAML et le guide de syntaxe XAML.

Dans les exemples précédents, le pinceau créé est créé implicitement et automatiquement, dans le cadre d’un raccourci de langage XAML délibéré qui permet de simplifier les définitions d’interface utilisateur dans les cas les plus courants. L’exemple suivant crée un Rectangle et crée explicitement un SolidColorBrush en tant que valeur d'élément pour la propriété Rectangle.Fill . La Couleur du SolidColorBrush est définie sur Bleu et l'opacité est définie sur 0,5.

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

Pinceaux de dégradé linéaire

Un LinearGradientBrush peint une zone avec un dégradé défini le long d’une ligne. Cette ligne est appelée axe de dégradé. Vous spécifiez les couleurs du dégradé et leurs emplacements le long de l'axe de dégradé en utilisant des objets GradientStop . Par défaut, l'axe du dégradé s'étend du coin supérieur gauche au coin inférieur droit de la zone que le pinceau peint, entraînant un ombrage diagonal.

Le GradientStop est le bloc de construction de base d’une brosse à dégradé. Un arrêt de dégradé spécifie quelle est la couleur du pinceau à un décalage sur l'axe du dégradé, lorsque le pinceau est appliqué à la zone à peindre.

La propriété Couleur de l'étape de dégradé spécifie la couleur de l'étape de dégradé. Vous pouvez définir la couleur à l’aide d’un nom de couleur prédéfini ou en spécifiant les valeurs ARVB hexadécimales.

La propriété Offset d’une GradientStop spécifie la position de chaque GradientStop le long de l’axe de dégradé. Le offset de est un double comprise entre 0 et 1. Un Offset de 0 place le GradientStop au début de l'axe du dégradé, en d'autres termes près de son StartPoint. Un offset de 1 place le GradientStop au EndPoint. Au minimum, un LinearGradientBrush utile doit avoir deux valeurs GradientStop, où chaque GradientStop doit spécifier une couleur différente et avoir un offset différent entre 0 et 1.

Cet exemple crée un dégradé linéaire avec quatre couleurs et l’utilise pour peindre un 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>

La couleur de chaque point entre les arrêts du dégradé est interpolée de manière linéaire comme une combinaison de la couleur spécifiée par les deux arrêts du dégradé délimitant. L’image suivante met en évidence les points d'arrêt de dégradé dans l’exemple précédent. Les cercles marquent la position des points de dégradé et la ligne en pointillés affiche l’axe du dégradé.

Combinaison de couleurs spécifiée par les deux points de dégradé délimitants

Vous pouvez modifier la ligne à laquelle les arrêts de dégradé sont positionnés en définissant les propriétés StartPoint et EndPoint pour qu’elles aient des valeurs différentes des valeurs de départ par défaut (0,0) et (1,1). En modifiant les valeurs de coordonnées StartPoint et EndPoint , vous pouvez créer des dégradés horizontaux ou verticaux, inverser la direction du dégradé ou condenser la propagation du dégradé pour s’appliquer à une plage plus petite que la zone peinte complète. Pour condenser le dégradé, vous définissez les valeurs de StartPoint et/ou EndPoint pour qu’elles soient comprises entre les valeurs 0 et 1. Par exemple, si vous souhaitez un dégradé horizontal où le fondu se produit tous sur la moitié gauche du pinceau et que le côté droit est unie à votre dernière couleur GradientStop, vous spécifiez un StartPoint de (0,0) et un EndPoint de (0.5,0).

Pinceaux de dégradé radial

Un RadialGradientBrush est dessiné dans un ellipse défini par les propriétéscenter , RadiusXet RadiusY. Les couleurs du dégradé commencent au centre de l’ellipse et se terminent au rayon.

Les couleurs du dégradé radial sont définies par des intersections de couleur ajoutées à la propriété de collection GradientStops. Chaque arrêt de dégradé spécifie une couleur et un décalage le long du dégradé.

L’origine du dégradé est par défaut centrée et peut être décalée à l’aide de la propriété GradientOrigin.

MappingMode définit si Center, RadiusX, RadiusY et GradientOrigin représentent des coordonnées relatives ou absolues.

Lorsque MappingMode est défini sur RelativeToBoundingBox, les valeurs X et Y des trois propriétés sont traitées comme relatives aux limites de l’élément, où (0,0) représente le haut à gauche et (1,1) représente le bas à droite des limites de l’élément pour le centre , les propriétés RadiusXet RadiusY et (0,0) représente le centre de la propriété GradientOrigin.

Lorsque MappingMode est défini sur Absolute, les valeurs X et Y des trois propriétés sont traitées comme des coordonnées absolues dans les limites de l’élément.

Cet exemple crée un dégradé linéaire avec quatre couleurs et l’utilise pour peindre un 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>

La couleur de chaque point entre les points de gradient est interpolée radialement comme une combinaison de la couleur spécifiée par les deux points de gradient limitants. L’image suivante met en évidence les points d'arrêt de dégradé dans l’exemple précédent.

Points de dégradé

Pinceaux d’image

Un ImageBrush peint une zone avec une image, avec l’image à peindre provenant d’une source de fichier image. Vous définissez la propriété ImageSource avec le chemin de l'image à charger. En règle générale, la source d’image provient d’un élément de contenu qui fait partie des ressources de votre application.

Par défaut, un ImageBrush étire son image pour remplir complètement la zone peinte, ce qui peut fausser l’image si la zone peinte a un rapport d’aspect différent de celui de l’image. Vous pouvez modifier ce comportement en changeant la propriété Stretch de sa valeur par défaut Fill et en la définissant sur Aucun, Uniformeou UniformToFill.

L’exemple suivant crée un ImageBrush et définit l’ImageSource sur une image nommée licorice.jpg, que vous devez inclure en tant que ressource dans l’application. Le ImageBrush peint ensuite la zone définie par une formeEllipse.

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

Une ImageBrush rendue

ImageBrush et Image font référence à un fichier source d’image par URI (Uniform Resource Identifier), où ce fichier source d’image utilise plusieurs formats d’image possibles. Ces fichiers sources d’image sont spécifiés en tant qu’URI. Pour plus d’informations sur la spécification de sources d’images, les formats d’image utilisables et leur empaquetage dans une application, consultez Image et ImageBrush.

Pinceaux et texte

Vous pouvez également utiliser des pinceaux pour appliquer des caractéristiques de rendu aux éléments de texte. Par exemple, la propriété Foreground de TextBlock utilise un Brush . Vous pouvez appliquer l’un des pinceaux décrits ici au texte. Toutefois, soyez prudent avec les pinceaux appliqués au texte, car tout fond pourrait rendre le texte illisible si vous utilisez des pinceaux qui se fondent dans l'arrière-plan. Utilisez SolidColorBrush pour la lisibilité des éléments de texte dans la plupart des cas, sauf si vous souhaitez que l’élément de texte soit principalement décoratif.

Même lorsque vous utilisez une couleur unie, assurez-vous que la couleur de texte que vous choisissez a suffisamment de contraste par rapport à la couleur d’arrière-plan du conteneur de disposition du texte. Le niveau de contraste entre le premier plan de texte et l’arrière-plan du conteneur de texte est une considération d’accessibilité.

XamlCompositionBrushBase

XamlCompositionBrushBase est une classe de base utilisée pour créer des pinceaux personnalisés qui utilisent CompositionBrush pour peindre des éléments d’interface utilisateur XAML.

Cela permet l’interopérabilité « déroulante » entre les couches Windows.UI.Xaml et Windows.UI.Composition, comme décrit dans la vue d’ensemble de la couche visuelle.

Pour créer un pinceau personnalisé, créez une classe qui hérite de XamlCompositionBrushBase et implémente les méthodes requises.

Par exemple, cela peut être utilisé pour appliquer des effets à des UIElements XAML à l’aide d’un CompositionEffectBrush, tel qu’un GaussianBlurEffect ou un SceneLightingEffect qui contrôle les propriétés réfléchissantes d’un UIElement XAML lorsqu’il est éclairé par un XamlLight.

Pour obtenir des exemples de code, consultez XamlCompositionBrushBase.

Pinceaux en tant que ressources XAML

Vous pouvez déclarer n’importe quel pinceau comme ressource XAML clé dans un dictionnaire de ressources XAML. Cela facilite la réplication des mêmes valeurs de pinceau que celles appliquées à plusieurs éléments d’une interface utilisateur. Les valeurs de pinceau sont ensuite partagées et appliquées à tout cas où vous référencez la ressource de pinceau en tant que {StaticResource} utilisation dans votre code XAML. Cela inclut les cas où vous disposez d’un modèle de contrôle XAML qui fait référence au pinceau partagé et que le modèle de contrôle est lui-même une ressource XAML clé.

Pinceaux dans le code

Il est beaucoup plus courant de spécifier des pinceaux à l’aide de XAML que d’utiliser du code pour définir des pinceaux. Cela est dû au fait que les pinceaux sont généralement définis en tant que ressources XAML et que les valeurs de pinceau sont souvent la sortie d’outils de conception ou dans le cadre d’une définition d’interface utilisateur XAML. Cependant, pour le cas occasionnel où vous pourriez souhaiter définir un pinceau par du code, tous les types de pinceau sont disponibles pour l'instanciation via le code.

Pour créer un SolidColorBrush dans le code, utilisez le constructeur qui accepte un paramètre Color . Transmettez une valeur qui est une propriété statique de la classe Colors , comme suit :

SolidColorBrush blueBrush = new SolidColorBrush(Colors.Blue);

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

Pour ImageBrush, utilisez le constructeur par défaut, puis appelez d’autres API avant de tenter d’utiliser ce pinceau pour une propriété d’interface utilisateur.

ImageSource nécessite un BitmapImage (et non un URI) lorsque vous définissez un ImageBrush à l’aide du code. Si votre source est un flux, utilisez la méthode SetSourceAsync pour initialiser la valeur. Si votre source est un URI, qui inclut du contenu dans votre application qui utilise le ms-appx ou schémas de ms-resource, utilisez le constructeur BitmapImage qui accepte un URI. Vous pouvez également envisager de gérer l’événement ImageOpened s’il existe des problèmes de minutage lors de la récupération ou du décodage de la source d’image, où vous devrez peut-être afficher un autre contenu jusqu’à ce que la source de l’image soit disponible.

Pour obtenir des exemples de code, consultez ImageBrush et XamlCompositionBrushBase.

UWP et WinUI 2

Les APIs Brush se trouvent dans les espaces de noms Windows.UI.Xaml.Controls et Windows.UI.Xaml.Controls.

Nous vous recommandons d’utiliser la dernière version de WinUI 2 pour obtenir les styles, modèles et fonctionnalités les plus récents pour tous les contrôles.

WebViewBrush (UWP uniquement)

Un WebViewBrush est un type spécial de pinceau qui peut accéder au contenu normalement consulté dans le contrôle WebView. Au lieu de rendre le contenu dans la zone de contrôle rectangulaire WebView, WebViewBrush peint ce contenu sur un autre élément qui possède une propriété de type Brushpour une surface de rendu. WebViewBrush n'est pas approprié pour chaque scénario de brosse, mais il est utile pour les transitions d'un WebView. Pour plus d’informations, consultez WebViewBrush.

Si vous créez un WebViewBrush dans le code, utilisez le constructeur par défaut, puis appelez d’autres API avant de tenter d’utiliser ce pinceau pour une propriété d’interface utilisateur. Vous devrez peut-être appeler Redraw si vous avez récemment réinitialisé la propriété SourceName ou si le contenu du WebView est également modifié avec du code.

Pour obtenir des exemples de code, consultez WebViewBrush.