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 Galeria da WinUI 3 inclui exemplos interativos da maioria dos controles, recursos e funcionalidades da WinUI 3. Obtenha o aplicativo na Microsoft Store ou obtenha o código-fonte no GitHub

Introdução aos pincéis

Para pintar um Shape, texto ou partes de um Control que é exibido no canvas do aplicativo, defina a propriedade Fill do Shape ou as propriedades Background e Foreground de um Control para um valor Brush.

Os diferentes tipos de pincéis são:

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

Pincéis de cores sólidas

Um SolidColorBrush pinta uma área com um único Color, como vermelho ou azul. Este é o pincel mais básico. No XAML, há três maneiras de definir um SolidColorBrush e a cor especificada: nomes de cores predefinidos, valores de cor hexadecimal ou a sintaxe do elemento de 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 a cor nomeada "Orchid", defina o valor cor para o valor estático Colors.Orchid.

Valores de cor 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 XAML define a propriedade Fill de um Rectangle para o valor hexadecimal "#FFFF0000" e fornece um resultado idêntico ao uso da cor nomeada Colors.Red.

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

Sintaxe do elemento property

Você pode usar a sintaxe do elemento de 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 Retângulo e cria explicitamente o SolidColorBrush como o valor do elemento para uma propriedade Rectangle.Fill . O de do SolidColorBrush está definido como Azul e ode Opacidade está definido 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.

O GradientStop é o elemento fundamental de um pincel de gradiente. Uma parada de gradiente especifica qual é a Cor do pincel em um Deslocamento ao longo do eixo do gradiente, quando aplicado à área a ser pintada.

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

A propriedade Offset de um GradientStop especifica a posição de cada GradientStop ao longo do eixo do gradiente. O Offset é um duplo que varia de 0 a 1. Um de deslocamento de de 0 coloca o GradientStop no início do eixo gradiente, ou seja, perto de seu do StartPoint. Um de Deslocamento de 1 coloca o GradientStop nodo Ponto de Extremidade . No mínimo, um linearGradientBrush útil deve ter dois valores de GradientStop , em que cada GradientStop deve especificar um de Cor de diferente e ter um deslocamento de 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 paradas de gradiente é interpolada como uma combinação linear da cor especificada pelas duas paradas de gradiente delimitantes. 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 especificada pelas duas paradas delimitadoras do gradiente

Você pode alterar a linha na qual as paradas de gradiente são posicionadas definindo as propriedades StartPoint e EndPoint como 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, se você quiser um gradiente horizontal em que o esmaecimento ocorre na metade esquerda do pincel e o lado direito é sólido para a cor de GradientStop da última , especifique um do StartPoint de e um do Ponto de Extremidade de .

Pincéis de gradiente radial

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

As cores do gradiente radial são definidas por pontos de cor adicionados à propriedade de coleção GradientStops. Cada ponto 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 paradas de gradiente é interpolada radialmente como uma combinação da cor especificada pelas duas paradas de gradiente delimitantes. A imagem a seguir realça os pontos do gradiente no exemplo anterior.

Paradas de gradiente

Pincéis de imagem

Um ImageBrush pinta uma área com uma imagem cuja fonte é um arquivo de imagem. Você define a propriedade ImageSource com o caminho da imagem a ser carregada. Normalmente, a origem da imagem vem de um item de Content que faz parte dos recursos do seu aplicativo.

Por padrão, um ImageBrush estica 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 usa 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.

Isso permite a interoperação "drop down" 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, é possível usar isso para aplicar efeitos aos UIElements-XAML usando um CompositionEffectBrush, como um GaussianBlurEffect ou um SceneLightingEffect que controla as propriedades reflexivas de um UIElement-XAML quando iluminado por um XamlLight.

Para obter exemplos de código, consulte XamlCompositionBrushBase.

Pincéis como recursos do 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 então compartilhados e aplicados a qualquer caso em que você referencie o recurso de pincel como um {StaticResource} uso em 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 no código

É muito mais comum especificar pincéis usando XAML do que usar código para definir pincéis. Isso ocorre porque os pincéis geralmente são definidos como recursos XAML e porque os valores de pincel geralmente são a saída de ferramentas de design ou como parte de uma definição de interface do usuário 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 no código, use o construtor que usa 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 chame outras APIs antes de tentar usar esse brush para uma propriedade da interface do usuário.

ImageSource requer um BitmapImage (não um URI) quando você define um 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 em seu aplicativo que usa o ms-appx ou esquemas de ms-resource, use o construtor BitmapImage que usa um URI. Você também poderá considerar o tratamento do evento ImageOpened se houver problemas de tempo com a recuperação ou decodificação da fonte da imagem, em que talvez seja necessário exibir conteúdo alternativo até que a fonte da imagem esteja disponível.

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

UWP e WinUI 2

As APIs de pincel existem nos namespaces Windows.UI.Xaml.Controls e Windows.UI.Xaml.Controls .

Recomendamos usar a versão mais recente do WinUI 2 () para obter os estilos, modelos e recursos mais atualizados para todos os controles.

WebViewBrush (somente UWP)

Um WebViewBrush é um tipo especial de pincel que pode acessar o conteúdo normalmente exibido em um controle WebView. Em vez de renderizar o conteúdo na área de controle retangular WebView, WebViewBrush pinta esse conteúdo sobre outro elemento que tem uma propriedade do tipo Brushpara uma superfície de renderização. WebViewBrush não é apropriado para todos os cenários de brush, mas é útil para transições de WebView. Para obter mais informações, consulte WebViewBrush.

Se você criar um WebViewBrush no código, use o construtor padrão e chame outras APIs antes de tentar usar esse pincel para uma propriedade de interface do usuário. Talvez seja necessário chamar Redraw se você redefiniu recentemente a propriedade SourceName ou se o conteúdo do WebView também estiver sendo alterado por código.

Para obter exemplos de código, consulte WebViewBrush.