Usando pincéis para pintar fundos, elementos do primeiro plano e contornos

Use objetos Brush para pintar os interiores e contornos de formas XAML, textos e controles, tornando-os visíveis na UI do seu aplicativo.

O aplicativo Da Galeria do WinUI 3 inclui exemplos interativos de controles e recursos do WinUI. Obtenha o aplicativo na Microsoft Store ou navegue pelo código-fonte em GitHub.

Introdução aos pincéis

Para pintar uma Shape, um texto ou partes de um Control que é exibido na tela do aplicativo, defina a propriedade Fill da Shape ou as propriedades de Background e Foreground de um Control com um valor de Brush.

Os diferentes tipos de pincéis são:

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

Pincéis de cor sólida

Um SolidColorBrush pinta uma área com uma única Color, como vermelho ou azul. Este é o pincel mais básico. No XAML, há três maneiras de definir um SolidColorBrush e a cor que ele especifica: nomes de cores predefinidas, valores de cores hexadecimais ou a sintaxe do elemento da propriedade.

Nomes de cores predefinidos

Você pode usar um nome de cor predefinido, como Amarelo ou magenta. Há 256 cores nomeadas disponíveis. O analisador XAML converte o nome da cor em uma estrutura Color com os canais de cores corretos. As 256 cores nomeadas se baseiam nos nomes de cores X11 da especificação CSS3 (Folhas de Estilos em Cascata, Nível 3), portanto, talvez você já esteja familiarizado com essa lista de cores nomeadas se tiver experiência anterior com desenvolvimento ou design da Web.

Aqui está um exemplo que define a propriedade Fill do retângulo para a cor predefinida Vermelho.

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

SolidColorBrush aplicado a um retângulo

Se você estiver definindo um SolidColorBrush usando código em vez de XAML, cada cor nomeada estará disponível como um valor de propriedade estático da classe Colors. Por exemplo, para declarar um valor Color de um SolidColorBrush para representar o nome de cor "Orquídea", defina o valor Color como o valor estático Colors.Orchid.

Valores de cores em hexadecimal

Você pode usar uma cadeia de caracteres de formato hexadecimal para declarar valores de cor precisos de 24 bits com canal alfa de 8 bits para um SolidColorBrush . Dois caracteres no intervalo de 0 a F definem cada valor de componente e a ordem de valor do componente da cadeia de caracteres hexadecimal é: canal alfa (opacidade), canal vermelho, canal verde e canal azul (ARGB). Por exemplo, o valor hexadecimal "#FFFF0000" define vermelho totalmente opaco (alfa="FF", vermelho="FF", verde="00" e azul="00").

Este exemplo de XAML define a propriedade Fill de um Rectangle como o valor hexadecimal "#FFFF0000" e produz um resultado idêntico ao usar o nome de cor Colors.Red.

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

Sintaxe do elemento property

Você pode usar a sintaxe do elemento da propriedade para definir um SolidColorBrush. Essa sintaxe é mais detalhada do que os métodos anteriores, mas você pode especificar valores de propriedade adicionais em um elemento, como a opacidade . Para obter mais informações sobre a sintaxe XAML, incluindo a sintaxe do elemento de propriedade, consulte a visão geral do XAML e o guia de sintaxe do XAML .

Nos exemplos anteriores, o pincel que está sendo criado é criado implicitamente e automaticamente, como parte de uma abreviação de linguagem XAML deliberada que ajuda a manter as definições de interface do usuário simples para os casos mais comuns. O exemplo a seguir cria um Rectangle e cria explicitamente o SolidColorBrush como um valor de elemento para uma propriedade Rectangle.Fill. A Color do SolidColorBrush é definida como Blue e a Opacity é definida como 0,5.

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

Pincéis de degradê linear

Um LinearGradientBrush pinta uma área com um gradiente definido ao longo de uma linha. Essa linha é chamada de linha do eixo de gradiente . Você especifica as cores do gradiente e suas localizações ao longo do eixo do gradiente usando objetos de GradientStop . Por padrão, o eixo do gradiente se estende do canto superior esquerdo até o canto inferior direito da área que o pincel pinta, criando um sombreamento diagonal.

A GradientStop é um bloco de construção básico de um pincel de gradiente. Uma marca de gradiente especifica a Color do pincel que está em um Offset ao longo do eixo do gradiente, quando o pincel é aplicado na área sendo pintada.

A propriedade Color da marca do gradiente especifica a cor da marca do gradiente. Você pode definir a cor usando um nome de cor predefinido ou especificando os valores hexadecimais ou ARGB.

A propriedade Offset de uma GradientStop especifica a posição de cada GradientStop ao longo do eixo do gradiente. O Offset é um double que vai de 0 a 1. Um Offset igual a 0 coloca a GradientStop no início do eixo do gradiente, em outras palavras, próximo ao seu StartPoint. Um Offset igual a 1 coloca a GradientStop no EndPoint. No mínimo, um LinearGradientBrush útil deve ter dois GradientStop valores, onde cada GradientStop deve especificar uma Cor diferente e ter um Offset diferente entre 0 e 1.

Este exemplo cria um gradiente linear com quatro cores e o usa para pintar um retâ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>

A cor de cada ponto entre as marcas do gradiente são linearmente interpoladas como uma combinação da cor especificada pelas duas marcas de gradiente associadas. A imagem a seguir realça os pontos do gradiente no exemplo anterior. Os círculos marcam a posição das paradas de gradiente e a linha tracejada mostra o eixo do gradiente.

Combinação de cores especificadas pelas duas marcas de gradiente delimitadoras

Marcas de gradiente Você pode alterar a linha na qual as marcas de gradiente são posicionadas definindo as propriedades StartPoint e EndPoint com valores diferentes dos padrões iniciais (0,0) e (1,1). Ao alterar os valores de coordenada StartPoint e EndPoint, você pode criar gradientes horizontais ou verticais, inverter a direção do gradiente ou condensar a propagação do gradiente para aplicar a um intervalo menor do que a área pintada completa. Para condensar o gradiente, defina os valores de StartPoint e/ou EndPoint para que sejam algo que se situem entre os valores 0 e 1. Por exemplo, para um gradiente horizontal em que o esmaecimento acontece totalmente na metade esquerda do pincel e o lado direito é sólido como sua última cor GradientStop, especifique um StartPoint de (0,0) e um EndPoint de (0.5,0).

Pincéis de gradiente radial

Um RadialGradientBrush é desenhado em uma elipse que é definida pelas propriedades Center, RadiusX e RadiusY. As cores do gradiente começam no centro da elipse e terminam no raio.

As cores do gradiente radial são definidas por marcas de cor adicionadas à propriedade da coleção de GradientStops. Cada marca de gradiente especifica uma cor e um deslocamento ao longo do gradiente.

A origem do gradiente tem como padrão o centro e pode ser deslocada usando a propriedade GradientOrigin.

MappingMode define se Center, RadiusX, RadiusYe GradientOrigin representam coordenadas relativas ou absolutas.

Quando MappingMode é definido como RelativeToBoundingBox, os valores X e Y das três propriedades são tratados como relativos aos limites do elemento, onde (0,0) representa o ponto superior esquerdo e (1,1) representa o ponto inferior direito dos limites do elemento para as propriedades Center, RadiusXe RadiusY, e (0,0) representa o centro da propriedade GradientOrigin.

Quando MappingMode é definido como Absolute, os valores X e Y das três propriedades são tratados como coordenadas absolutas dentro dos limites do elemento.

Este exemplo cria um gradiente linear com quatro cores e o usa para pintar um retâ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>

A cor de cada ponto entre as marcas de gradiente é radialmente interpolada como uma combinação da cor especificada pelas duas marcas de gradiente associadas. A imagem a seguir realça os pontos do gradiente no exemplo anterior.

Marcas de gradiente

Pincéis de imagem

Um ImageBrush pinta uma imagem em uma área e a imagem a ser pintada se origina de uma origem de arquivo de imagem. Você define a propriedade ImageSource com o caminho da imagem a ser carregada. Geralmente, a origem da imagem vem de um item Content que faz parte dos recursos do seu aplicativo.

Por padrão, um ImageBrush estica a sua imagem para preencher completamente a área pintada, possivelmente distorcendo a imagem se a área pintada tiver uma proporção diferente da imagem. Você pode alterar esse comportamento mudando a propriedade Stretch de seu valor padrão Fill e definindo-a como None, Uniformou UniformToFill.

O próximo exemplo cria um ImageBrush e define o ImageSource para uma imagem chamada licorice.jpg, que deve ser incluída como um recurso no aplicativo. O ImageBrush , em seguida, pinta a área definida por uma forma Elipse.

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

Um ImageBrush renderizado

ImageBrush e Image referenciam um arquivo de origem de imagem pelo URI (Uniform Resource Identifier), em que esse arquivo de origem de imagem usa vários formatos de imagem possíveis. Esses arquivos de origem de imagem são especificados como URIs. Para obter mais informações sobre como especificar fontes de imagem, os formatos de imagem utilizáveis e empacotar em um aplicativo, consulte Image e ImageBrush.

Pincéis e texto

Você também pode usar pincéis para aplicar características de renderização a elementos de texto. Por exemplo, a propriedade Foreground de TextBlock tem um Brush. Você pode aplicar qualquer um dos pincéis descritos aqui ao texto. No entanto, tenha cuidado com pincéis aplicados ao texto, pois qualquer fundo pode tornar o texto ilegível se você usar pincéis que se misturam ao fundo. Use SolidColorBrush para facilitar a leitura de elementos de texto na maioria dos casos, a menos que você queira que o elemento de texto seja principalmente decorativo.

Mesmo quando você usa uma cor sólida, certifique-se de que a cor de texto escolhida tenha contraste suficiente com a cor da tela de fundo do contêiner de layout do texto. O nível de contraste entre o primeiro plano de texto e o plano de fundo do contêiner de texto é uma consideração de acessibilidade.

XamlCompositionBrushBase

XamlCompositionBrushBase é uma classe base usada para criar pincéis personalizados que usam CompositionBrush para pintar elementos da interface do usuário XAML.

Ele permite a interoperação "suspensa" entre as camadas Windows.UI.Xaml e Windows.UI.Composition conforme descrito na Visão geral da Camada Visual.

Para criar um pincel personalizado, crie uma nova classe que herda do XamlCompositionBrushBase e implemente os métodos necessários.

Por exemplo, ele poderá ser usado para aplicar efeitos a UIElements do XAML usando um CompositionEffectBrush, como um GaussianBlurEffect ou SceneLightingEffect que controla as propriedades reflexivas de um UIElement do XAML quando estiver sendo aceso por um XamlLight.

Para obter exemplos de código, consulte XamlCompositionBrushBase.

Pincéis como recursos XAML

Você pode declarar qualquer pincel como um recurso XAML com chave em um dicionário de recursos XAML. Isso facilita a replicação dos mesmos valores de pincel aplicados a vários elementos em uma interface do usuário. Os valores de pincel são compartilhados e aplicativos a qualquer caso no qual você faz referência do recurso de pincel como uma utilização de {StaticResource} no seu XAML. Isso inclui casos em que você tem um modelo de controle XAML que faz referência ao pincel compartilhado e o modelo de controle é um recurso XAML com chave.

Pincéis em código

É muito mais comum especificar pincéis usando XAML do que usar código para definir pincéis. Isso acontece porque os pincéis costumam ser definidos como recursos XAML e porque os valores de pincel geralmente são a saída das ferramentas de design ou fazem parte de uma definição da IU XAML. Ainda assim, para o caso ocasional em que você deseje definir um pincel usando código, todos os tipos de pincel estão disponíveis para instanciação por código.

Para criar um SolidColorBrush em código, use o construtor que leva um parâmetro Color. Passe um valor que seja uma propriedade estática da classe Colors, desta forma:

SolidColorBrush blueBrush = new SolidColorBrush(Colors.Blue);

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

Para ImageBrush, use o construtor padrão e, depois, chame outras APIs antes de tentar usar esse pincel para uma propriedade da IU.

ImageSource requer uma BitmapImage (não um URI) ao definir ImageBrush usando código. Se sua origem for um fluxo, use o método SetSourceAsync para inicializar o valor. Se sua origem for um URI que inclui conteúdo no seu aplicativo que usa o esquema ms-appx ou ms-resource, use o construtor BitmapImage que usa um URI. Você também poderá considerar a manipulação do evento ImageOpened se houver algum problema de temporização com a recuperação ou decodificação da origem da imagem, em que você pode precisar de conteúdo alternativo para exibir até que a origem da imagem esteja disponível.

Para obter exemplos de código, consulte ImageBrush e XamlCompositionBrushBase.