Partilhar via

Usando pincéis para pintar planos de fundo, primeiro plano e contornos

Use Pincel objetos para pintar os interiores e contornos de formas, texto e controles XAML, tornando-os visíveis na interface do usuário do aplicativo.

Abra o aplicativo WinUI 3 Gallery e veja o RadialGradientBrush em ação

O aplicativo WinUI 3 Gallery inclui exemplos interativos da maioria dos controles, recursos e funcionalidades do WinUI 3. Obtenha o aplicativo no da Microsoft Store ou obtenha o código-fonte em do GitHub

Introdução aos pincéis

Para pintar umade Forma , texto ou partes de uma de Controle de exibida na tela do aplicativo, defina a propriedade Preenchimento da Forma ou Plano de Fundo e propriedades de Primeiro Plano de um de Controle de como um valor de Pincel .

Os diferentes tipos de escovas são:

Pincéis de cor sólida

Um SolidColorBrush pinta uma área com uma única cor , como vermelho ou azul. Esta é a escova mais básica. Em XAML, há três maneiras de definir um SolidColorBrush e a cor que ele especifica: nomes de cores predefinidos, valores de cores hexadecimais ou a sintaxe do elemento de propriedade.

Nomes de cores predefinidos

Você pode usar um nome de cor predefinido, como Yellow ou Magenta. Existem 256 cores nomeadas disponíveis. O analisador XAML converte o nome da cor em uma estrutura de cor com os canais de cores corretos. As 256 cores nomeadas são baseadas nos nomes de cores X11 da especificação CSS3 (Cascading Style Sheets, Level 3), portanto, você já pode estar familiarizado com esta lista de cores nomeadas se tiver experiência anterior com desenvolvimento ou design web.

Este é um exemplo que define a propriedade Fill de um Rectangle para a cor predefinida Red.

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

Um PincelDeCorSólida renderizado

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ática da classe Colors. Por exemplo, para declarar um valor Color de um SolidColorBrush para representar a cor nomeada "Orchid", defina o valor Color como o valor estático Colors.Orchid.

Valores de cor hexadecimais

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 valores do componente da cadeia 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 dá um resultado idêntico ao uso da cor nomeada Colors.Red.

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

Sintaxe do elemento de propriedade

Você pode usar a sintaxe do elemento de propriedade para definir um SolidColorBrush. Esta sintaxe é mais detalhada do que os métodos anteriores, mas pode-se especificar valores de propriedade adicionais num elemento, como o Opacity. Para saber mais sobre a sintaxe XAML, incluindo a sintaxe do elemento de propriedade, veja a visão geral do XAML e o guia de sintaxe XAML .

Nos exemplos anteriores, o pincel que está sendo criado é criado implícita e automaticamente, como parte de uma abreviação deliberada da linguagem XAML que ajuda a manter as definições da interface do usuário simples para os casos mais comuns. O próximo exemplo cria um Rectangle e cria explicitamente o SolidColorBrush como um valor de elemento para uma propriedade Rectangle.Fill. A Cor do SolidColorBrush está definida como Azul e a Opacidade está definida como 0,5.

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

Pincéis de gradiente linear

Um LinearGradientBrush pinta uma área com um gradiente definido ao longo de uma linha. Essa linha é chamada de eixo de gradiente . Você especifica as cores do gradiente e seus locais ao longo do eixo do gradiente usando objetos GradientStop. Por padrão, o eixo do gradiente vai do canto superior esquerdo ao canto inferior direito da área pintada pelo pincel, resultando em um sombreamento diagonal.

O GradientStop é o bloco de construção básico de um pincel de gradiente. Uma parada de gradiente especifica qual é a de Cor do pincel em um de Deslocamento de ao longo do eixo do gradiente, quando o pincel é aplicado à área que está sendo pintada.

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

A propriedade Offset de um GradientStop especifica a posição de cada GradientStop ao longo do eixo do gradiente. O Offset é um double que varia de 0 a 1. Uma de deslocamento de de 0 coloca o GradientStop no início do eixo do gradiente, em outras palavras, perto de seu StartPoint. Um Offset de 1 coloca o GradientStop no EndPoint. No mínimo, um útil LinearGradientBrush deve ter dois valores de GradientStop, onde cada GradientStop deve especificar um Color diferente e ter um Offset 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 paradas de gradiente é interpolada linearmente como uma combinação da cor especificada pelas duas paradas de gradiente delimitadoras. A imagem a seguir destaca as paradas de gradiente no exemplo anterior. Os círculos marcam a posição das paradas de gradiente e a linha tracejada mostra o eixo do gradiente.

Diagrama que representa Gradient Stops 1 a 4 começando no canto superior esquerdo do diagrama e inclinando-se para baixo e para a direita até chegar ao canto inferior direito do diagrama.

Combinação de cores especificada pelos dois intervalos de gradiente delimitador

Você pode alterar a posição dos pontos de paragem do gradiente definindo as propriedades StartPoint e EndPoint para valores diferentes dos valores padrão iniciais (0,0) e (1,1). Ao alterar os valores de coordenadas StartPoint e EndPoint, é possível criar gradientes horizontais ou verticais, inverter a direção do gradiente ou condensar a propagação do gradiente para aplicá-lo a um intervalo menor do que a área pintada completa. Para condensar o gradiente, defina valores de PontoInicial e/ou PontoFinal para um valor entre 0 e 1. Por exemplo, se você quiser um gradiente horizontal em que o desvanecimento aconteça na metade esquerda do pincel e o lado direito seja sólido até o último cor do GradientStop, especifique uma StartPoint de e uma de EndPoint de .

Pincéis de gradiente radial

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

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

A origem do gradiente assume 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 canto superior esquerdo e (1,1) representa o canto inferior direito dos limites do elemento para o Center, RadiusXe RadiusY propriedades 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 delimitadoras. A imagem a seguir destaca as paradas de gradiente no exemplo anterior.

Captura de ecrã de um gradiente radial.

Paragens de gradiente

Pincéis de imagem

Um ImageBrush pinta uma área com uma imagem, com a imagem a ser pintada proveniente de uma fonte de arquivo de imagem. Você define a propriedade ImageSource com o caminho da imagem para carregar. Normalmente, a fonte da imagem vem de um item de Conteúdo que faz parte dos recursos da sua aplicação.

Por padrão, um ImageBrush estende 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 este comportamento alterando a propriedade Stretch do seu valor padrão de Fill e defini-la como None, Uniformou UniformToFill.

O próximo exemplo cria um ImageBrush e define o ImageSource como uma imagem chamada licorice.jpg, que você deve incluir como um recurso no aplicativo. O ImageBrush 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.

Um ImageBrush renderizado

ImageBrush e Image fazem referência a um arquivo de origem de imagem pelo URI (Uniform Resource Identifier), onde 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 saber mais sobre como especificar fontes de imagem, formatos de imagem utilizáveis e empacotá-los em um aplicativo, veja 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 plano de fundo pode tornar o texto ilegível se você usar pincéis que sangram para o plano de fundo. Use SolidColorBrush para legibilidade 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, verifique se a cor do texto escolhida tem contraste suficiente com a cor do plano 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 "descendente" entre as camadas Windows.UI.Xaml e Windows.UI.Composition, conforme descrito na visão geral do Visual Layer.

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

Por exemplo, isso pode ser usado para aplicar efeitos a 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 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 se faça referência ao recurso de pincel como uma utilização {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 é ele próprio um recurso XAML com chave.

Pincéis em programação

É 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 dos pincéis normalmente resultam de ferramentas de design ou de qualquer outra forma como parte de uma interface XAML. Ainda assim, para o caso ocasional em que possa querer definir um pincel usando código, todos os tipos de Pincel estão disponíveis para instanciação através de código.

Para criar um SolidColorBrush no código, utilize o construtor que recebe um parâmetro de Color. Passe um valor que seja uma propriedade estática da classe Cores , assim:

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 pincel 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 a sua origem for um URI, que inclui conteúdo na sua aplicação que utiliza os esquemas ms-appx ou ms-resource, use o construtor BitmapImage que recebe um URI. Você também pode considerar lidar com o evento ImageOpened se houver algum problema de temporização com a recuperação ou decodificação da fonte da imagem, caso precise de conteúdo alternativo para exibir até que a fonte da imagem esteja disponível.

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

UWP e WinUI 2

Importante

As informações e exemplos neste artigo são otimizados para aplicativos que usam o SDK de Aplicativos Windows e WinUI 3, mas geralmente são aplicáveis a aplicativos UWP que usam WinUI 2. Consulte a referência da API UWP para obter informações e exemplos específicos da plataforma.

Esta seção contém informações que você precisa para usar o controle em um aplicativo UWP ou WinUI 2.

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

Recomendamos usar a WinUI 2 mais recente para obter os estilos, modelos e recursos mais atuais para todos os controles.

WebViewBrush (somente UWP)

Um WebViewBrush é um tipo especial de pincel que pode aceder ao conteúdo normalmente visualizado num controlo WebView. Em vez de renderizar o conteúdo na área retangular de controlo WebView, WebViewBrush aplica esse conteúdo noutro elemento que tem uma propriedade do tipo Brushpara uma superfície de renderização. WebViewBrush não é apropriado para todos os cenários de pincel, mas é útil para transições de um WebView. Para obter mais informações, consulte WebViewBrush.

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

Para obter exemplos de código, consulte WebViewBrush.

  • Last updated on