Usar pinceles para pintar fondos, primer plano y contornos

Usa los objetos Brush para pintar los interiores y los contornos del texto, los controles y las formas XAML, de modo que estén visibles en la interfaz de usuario de la aplicación.

La aplicación Galería de WinUI 3 incluye ejemplos interactivos de características y controles winUI. Obtenga la aplicación del Microsoft Store o examine el código fuente en GitHub.

Introducción a los pinceles

Para pintar un objeto Shape, texto o partes de un objeto Control que se muestra en el lienzo de la aplicación, establece la propiedad Fill del objeto Shape o Background y las propiedades Foreground de un objeto Control en el valor Brush.

Los diferentes tipos de pinceles son:

• PincelAcrílico
• SolidColorBrush
• LinearGradientBrush
• RadialGradientBrush
• ImageBrush
• XamlCompositionBrushBase

Pinceles de color sólido

Un objeto SolidColorBrush pinta un área con un único Color, como rojo o azul. Este es el pincel más básico. En XAML, hay tres maneras de definir un SolidColorBrush y el color que especifica: nombres de color predefinidos, valores de color hexadecimales o la sintaxis del elemento de propiedad.

Nombres de color predefinidos

Puede usar un nombre de color predefinido, como Amarillo o Magenta. Hay 256 colores con nombre disponibles. El analizador XAML convierte el nombre de color en una estructura Color con los canales de color correctos. Los 256 colores con nombre se basan en los nombres de color de X11 de la especificación de Hojas de estilo en cascada, nivel 3 (CSS3), por lo que es posible que ya esté familiarizado con esta lista de colores con nombre si tiene experiencia previa en desarrollo web o diseño.

El ejemplo siguiente establece la propiedad Fill de un objeto Rectangle en el color predefinido Red.

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

objeto SolidColorBrush

SolidColorBrush aplicado a un rectángulo

Si defines un objeto SolidColorBrush mediante programación en lugar de usar XAML, cada color con nombre está disponible como un valor de propiedad estático de la clase Colors. Por ejemplo, para declarar un valor de Color de un SolidColorBrush que represente el color llamado "Orchid", establezca el valor Color en el valor estático Colors.Orchid.

Valores de color hexadecimales

Puede usar una cadena de formato hexadecimal para declarar valores de color precisos de 24 bits con un canal alfa de 8 bits para un SolidColorBrush. Dos caracteres del intervalo 0 a F definen cada valor de componente y el orden de valor del componente de la cadena hexadecimal es: canal alfa (opacidad), canal rojo, canal verde y canal azul (ARGB). Por ejemplo, el valor hexadecimal "#FFFF0000" define rojo totalmente opaco (alpha="FF", red="FF", green="00" y blue="00").

En este ejemplo de XAML se establece la propiedad Fill de un Rectangle en el valor hexadecimal "n.º FFFF0000", cuyo resultado es idéntico al uso del color con nombre Colors.Red.

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

Sintaxis del elemento Property

Puede usar la sintaxis del elemento de propiedad para definir un SolidColorBrush. Esta sintaxis es más detallada que los métodos anteriores, pero puede especificar valores de propiedad adicionales en un elemento, como la opacidad. Para obtener más información sobre la sintaxis XAML, incluida la sintaxis de elementos de propiedad, consulta la información general de XAML y la guía de sintaxis XAML .

En los ejemplos anteriores, el pincel que se crea se crea de forma implícita y automática, como parte de una abreviatura deliberada del lenguaje XAML que ayuda a simplificar las definiciones de interfaz de usuario para los casos más comunes. El ejemplo siguiente crea un objeto Rectangle y crea explícitamente el objeto SolidColorBrush como un valor de elemento para una propiedad Rectangle.Fill. El Color del SolidColorBrush se establece en Azul y la Opacidad se establece en 0,5.

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

Pinceles de degradado lineal

Un objeto LinearGradientBrush pinta un área con un degradado que se define a lo largo de una línea. Esta línea se denomina eje de degradado. Puede especificar los colores del degradado y sus ubicaciones a lo largo del eje de degradado mediante GradientStop objetos. De forma predeterminada, el eje de degradado se extiende desde la esquina superior izquierda hasta la esquina inferior derecha del área que pinta el pincel, resultando en un sombreado diagonal.

El objeto GradientStop es el bloque de creación básico de un pincel de degradado. Un delimitador de degradado especifica que el objeto Color del pincel se encuentra en un objeto Offset a lo largo del eje de degradado, cuando el pincel se aplica a la superficie que se está pintando.

El color del delimitador de degradado se especifica por medio de su propiedad Color. Puede establecer el color mediante un nombre de color predefinido o especificando los valores ARGB hexadecimales.

La propiedad Offset de un objeto GradientStop especifica la posición de cada objeto GradientStop en el eje de degradado. Un objeto Offset es de tipo double con valores entre 0 y 1. Un objeto Offset con un valor de 0 sitúa el objeto GradientStop al principio del eje de degradado; es decir, junto a su StartPoint. Un objeto Offset con un valor de 1 sitúa el objeto GradientStop en su EndPoint. Como mínimo, un objeto LinearGradientBrush debe tener dos valores de GradientStop, en los que cada objeto GradientStop debe especificar un valor de Color distinto y tener un valor de Offset entre 0 y 1.

En este ejemplo se crea un degradado lineal con cuatro colores y se usa para pintar un rectángulo.

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

El color de cada punto entre los delimitadores de degradado se interpola linealmente como una combinación del color especificado por los dos delimitadores de degradado limítrofes. En la imagen siguiente, se resaltan los delimitadores de degradado del ejemplo anterior. Los círculos marcan la posición de los delimitadores de degradado y la línea punteada muestra el eje de degradado.

Combinación de colores especificada por los dos delimitadores de degradado

Puede cambiar la línea en la que se sitúan los delimitadores de degradado estableciendo las propiedades StartPoint y EndPoint con valores distinto de los valores predeterminados iniciales (0,0) y (1,1). Al cambiar los valores de coordenadas StartPoint y EndPoint , puede crear degradados horizontales o verticales, invertir la dirección del degradado o condensar la propagación de degradado para aplicarse a un rango menor que el área pintada completa. Para condensar el degradado, establezca los valores de StartPoint y/o EndPoint para que se encuentren entre los valores 0 y 1. Por ejemplo, si deseas un degradado horizontal en el que toda la atenuación se produzca en la mitad izquierda del pincel y el lado derecho sea sólido con el último color de GradientStop, debes especificar un valor de StartPoint de (0,0) y un valor de EndPoint de (0.5,0).

Pinceles del degradado radial

Un RadialGradientBrush se dibuja dentro de una elipse que está definida por las propiedades Center, RadiusXy RadiusY. Los colores para el gradiente comienzan en el centro de la elipse y terminan en el radio.

Los colores del degradado radial se definen según los delimitadores de color agregados a la propiedad de colección GradientStops. Cada delimitador de degradado especifica un color y un desplazamiento a lo largo del degradado.

El origen del degradado se establece de manera predeterminada en el centro y se puede desplazar con la propiedad GradientOrigin.

MappingMode define si Center, RadiusX, RadiusY y GradientOrigin representan coordenadas relativas o absolutas.

Cuando MappingMode se establece en RelativeToBoundingBox, los valores X e Y de las tres propiedades se tratan como relativos en los límites del elemento, en que (0,0) representa la parte superior izquierda, (1,1) representa la parte inferior derecha de los límites del elemento para las propiedades Center, RadiusX y RadiusY, y (0,0) representa el centro de la propiedad GradientOrigin.

Cuando MappingMode se establece en Absolute, los valores de X y Y de las tres propiedades se consideran coordenadas absolutas dentro de los límites del elemento.

En este ejemplo se crea un degradado lineal con cuatro colores y se usa para pintar un rectángulo.

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

El color de cada punto entre los delimitadores de degradado se interpola de forma radial como una combinación del color especificado por los dos delimitadores de degradado. En la imagen siguiente, se resaltan los delimitadores de degradado del ejemplo anterior.

Delimitadores de degradado

Pinceles de imagen

Un objeto ImageBrush pinta una superficie con una imagen que proviene de un origen de archivo de imagen. La propiedad ImageSource se establece con la ruta de acceso de la imagen que se va a cargar. Normalmente, el origen de la imagen procede de un elemento del Contenido que es parte de los recursos de tu aplicación.

De forma predeterminada, un ImageBrush amplía su imagen para rellenar completamente el área pintada, posiblemente distorsionando la imagen si el área pintada tiene una relación de aspecto diferente a la imagen. Para cambiar este comportamiento, modifique la propiedad Stretch de su valor predeterminado Fill y configúrela como None, Uniformo UniformToFill.

El ejemplo siguiente crea un objeto ImageBrush y establece el objeto ImageSource en una imagen llamada licorice.jpg que debes incluir como un recurso en la aplicación. Luego, el ImageBrush pinta el área definida por una elipse de forma .

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

Objeto ImageBrush representado

ImageBrush e Image hacen referencia a un archivo de origen de imagen por identificador uniforme de recursos (URI), donde ese archivo de origen de imagen usa varios formatos de imagen posibles. Estos archivos de origen de imagen se especifican como URI. Para obtener más información sobre cómo especificar orígenes de imágenes, los formatos de imagen utilizables y empaquetarlos en una aplicación, consulta Image e ImageBrush.

Pinceles y texto

También puede usar pinceles para aplicar características de representación a elementos de texto. Por ejemplo, la propiedad Foreground de TextBlock utiliza un objeto Brush. Puede aplicar cualquiera de los pinceles descritos aquí al texto. Sin embargo, tenga cuidado con los pinceles aplicados al texto, ya que cualquier fondo podría hacer que el texto sea ilegible si utiliza pinceles que se mezclan con el fondo. Use SolidColorBrush para mejorar la legibilidad de los elementos de texto en la mayoría de los casos, a menos que desee que el elemento de texto sea principalmente decorativo.

Incluso cuando se usa un color sólido, asegúrese de que el color de texto que elija tiene suficiente contraste con el color de fondo del contenedor de diseño del texto. El nivel de contraste entre el fondo del contenedor de texto y el primer plano del texto es una consideración de accesibilidad.

XamlCompositionBrushBase

XamlCompositionBrushBase es una clase base que se usa para crear pinceles personalizados que usan CompositionBrush para pintar elementos de la interfaz de usuario XAML.

Esto permite la interoperación de "lista desplegable" entre las capas Windows.UI.Xaml y Windows.UI.Composition, tal y como se describe en la información general de la capa Visual.

Para crear un pincel personalizado, cree una nueva clase que herede de XamlCompositionBrushBase e implemente los métodos necesarios.

Por ejemplo, esto se puede usar para aplicar efectos a XAML UIElements mediante un CompositionEffectBrush, como un GaussianBlurEffect o un SceneLightingEffect que controla las propiedades reflectantes de un XAML UIElement cuando es iluminado por un XamlLight.

Para obtener ejemplos de código, consulte XamlCompositionBrushBase.

Pinceles como recursos XAML

Puedes declarar cualquier pincel para que sea un recurso XAML con clave en un diccionario de recursos XAML. Esto facilita la replicación de los mismos valores de pincel que se aplican a varios elementos de una interfaz de usuario. A continuación, los valores de pincel se comparten y aplican a cualquier caso en el que se haga referencia al recurso de pincel como un uso {StaticResource} en el código XAML. Esto incluye casos en los que tienes una plantilla de control XAML que hace referencia al pincel compartido y la plantilla de control es un recurso XAML con clave.

Pinceles en código

Es mucho más habitual especificar pinceles mediante XAML que usar código para definir pinceles. Esto se debe a que los pinceles normalmente se definen como recursos XAML y, dado que los valores de los pinceles suelen ser el resultado de las herramientas de diseño o forman parte de una definición de interfaz de usuario XAML. Sin embargo, para el caso ocasional en el que es posible que quiera definir un pincel mediante código, todos los tipos de Brush están disponibles para la instanciación mediante código.

Para crear un objeto SolidColorBrush en código, usa el constructor que utiliza un parámetro Color. Pase un valor que sea una propiedad estática de la clase Colors , de la siguiente manera:

SolidColorBrush blueBrush = new SolidColorBrush(Colors.Blue);

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

Para ImageBrush, use el constructor predeterminado y, a continuación, llame a otras API antes de intentar usar ese pincel para una propiedad de interfaz de usuario.

ImageSource requiere un BitmapImage (no un URI) al definir un ImageBrush mediante código. Si el origen es una secuencia , use el método SetSourceAsync para inicializar el valor. Si el origen es un identificador URI, que incluye contenido en la aplicación que usa los esquemas ms-appx o ms-resource, utiliza el constructor BitmapImage que toma un URI. También puede considerar la posibilidad de controlar el evento ImageOpened si hay algún problema de tiempo con la recuperación o descodificación del origen de la imagen, donde es posible que necesite contenido alternativo para mostrar hasta que el origen de la imagen esté disponible.

Para obtener ejemplos de código, consulta ImageBrush y XamlCompositionBrushBase.