SolidColorBrush class

Applies to Windows and Windows Phone

Paints an area with a solid color. The solid color is defined by a Color value.

Inheritance

Object
  DependencyObject
    Brush
      SolidColorBrush

Syntax


public sealed class SolidColorBrush : Brush


<SolidColorBrush .../>
-or-
<SolidColorBrush>colorString</SolidColorBrush>


<SolidColorBrush Color="predefinedColorName"/>
- or -
<SolidColorBrush Color="#rgb"/>
- or -
<SolidColorBrush Color="#argb"/>
- or -
<SolidColorBrush Color="#rrggbb"/>
- or -
<SolidColorBrush Color="#aarrggbb"/>
- or -
<SolidColorBrush Color="sc#scR,scG,scB"/>
- or -
<SolidColorBrush Color="sc#scA,scR,scG,scB"/>

XAML Values

colorString

A string that supplies the XAML initialization text for a new SolidColorBrush. You can use any of the string formats described below; put this string within the SolidColorBrush element as content and don't use attributes, the equals sign or quotation marks.

predefinedColor

One of the colors predefined by the Colors class. These are static properties, and you specify a color by providing the string name of that Colors property for the Color attribute value. For example, use "Cyan" to specify the color that's defined by Colors.Cyan. Each Colors property lists its exact ARGB value in the reference page.

rgb

A three-character hexadecimal value. The first character specifies the color's R value, the second character specifies the G value, and the third character specifies the B value. For example, 00F.

argb

A four-character hexadecimal value. The first character specifies the color's A value, the second character specifies its R value, the third character specifies the G value, and the fourth character specifies its B value. For example, F00F.

rrggbb

A six-character hexadecimal value. The first two characters specify the color's R value, the next two specify its G value, and the final two specify its B value. For example, 0000FF.

aarrggbb

An eight-character hexadecimal value. The first two characters specify the color's A value, the next two specify its R value, the next two specify its G value, and the final two specify its B value. For example, FF0000FF.

scA

The color's ScA value as a value between 0 and 1. ScA is not exposed as a Color property directly.

scR

The color's ScR value as a value between 0 and 1. ScR is not exposed as a Color property directly.

scG

The color's ScG value as a value between 0 and 1. ScG is not exposed as a Color property directly.

scB

The color's ScB value as a value between 0 and 1. ScB is not exposed as a Color property directly.

Attributes

[ContentProperty("Name=Color")]
[MarshalingBehavior(Agile)]
[Threading(Both)]
[Version(0x06020000)]
[WebHostHidden()]

Members

The SolidColorBrush class has these types of members:

Constructors

The SolidColorBrush class has these constructors.

ConstructorDescription
SolidColorBrush() Initializes a new instance of the SolidColorBrush class with no color.
SolidColorBrush(Color) Initializes a new instance of the SolidColorBrush class with the specified Color.

 

Methods

The SolidColorBrush class has these methods. It also inherits methods from the Object class.

MethodDescription
ClearValue Clears the local value of a dependency property. (Inherited from DependencyObject)
GetAnimationBaseValue Returns any base value established for a dependency property, which would apply in cases where an animation is not active. (Inherited from DependencyObject)
GetValue Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject)
ReadLocalValue Returns the local value of a dependency property, if a local value is set. (Inherited from DependencyObject)
SetValue Sets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject)

 

Properties

The SolidColorBrush class has these properties.

PropertyAccess typeDescription

Color

Read/writeGets or sets the color of this SolidColorBrush.

ColorProperty

Read-onlyIdentifies the Color dependency property.

Dispatcher

Read-onlyGets the CoreDispatcher that this object is associated with. (Inherited from DependencyObject)

Opacity

Read/writeGets or sets the degree of opacity of a Brush. (Inherited from Brush)

RelativeTransform

Read/writeGets or sets the transformation that is applied to the brush using relative coordinates. (Inherited from Brush)

Transform

Read/writeGets or sets the transformation that is applied to the brush. (Inherited from Brush)

 

Remarks

A SolidColorBrush is the most common type of Brush that is used for many possible UI properties that use a Brush to fill some or all of an object's visual area in app UI. Examples of some of the most commonly-used properties that use a Brush value include: Control.Background, Control.Foreground, Shape.Fill, Control.BorderBrush, Panel.Background, TextBlock.Foreground.

For these properties, a null value is often acceptable, and has the result that nothing is rendered there. If the element appears in the same coordinate space as other elements, the null value for a property such as Background causes that element to not register for purposes of hit-testing, and determining where an input event should be sourced from. Any pointer events, gestures or so on that occur on that point in the UI coordinate space are only detectable when there's a value other than null for the Brush property that influences rendering for that point.

A SolidColorBrush can be created that uses the Transparent value, and although this doesn't visually apply any changes to UI (it's transparent), that point is detectable for hit-testing purposes. So this is different than a Brush property with a null value. A Transparent brush can be useful for techniques such as creating overlay regions over UI elements where you want to intercept the hit testing with an element like a Rectangle, Border or panel. You might do this if the elements underneath aren't able to do their own hit-testing, but you still want to detect input events. For more info on hit testing, see "Hit testing" section of Responding to mouse interactions.

Properties using brushes can be animated as part of transitions or decorative animations. You don't typically animate an entire SolidColorBrush object, you'd have to use a discrete Object animation and that's neither efficient nor aesthetic. Instead, you use property targeting to animate just the Color value, using one of the dedicated animation types that can animate a Color value. This usually involves having .(SolidColorBrush.Color) be a part of the Storyboard.TargetProperty value. For more info on property targeting and how to animate properties that use SolidColorBrush or other Brush values, see Storyboarded animations.

A SolidColorBrush is a shareable object, as are the other derived types of Brush such as LinearGradientBrush and ImageBrush. Because it's shareable a SolidColorBrush is sometimes defined in XAML as a resource in a XAML ResourceDictionary. The advantage of using shareable resources from XAML is that you're only creating the value once and applying it to multiple properties.

Applying a UIElement.Opacity value can change the color appearance of a SolidColorBrush property applied to an object. The UIElement.Opacity value can be cumulative depending on the layout of objects that overlap. The colors appear as expected only when the net Opacity value is 1. There's also a Brush.Opacity property that can affect the apparent color similarly. Brush.Opacity is usually left at its default value of 1, unless it's being deliberately animated for a fade-in or fade-out effect.

Brushes as XAML resources

Each of the Brush types that can be declared in XAML (SolidColorBrush, LinearGradientBrush, ImageBrush) is intended to be defined as a resource, so that you can reuse that brush as a resource throughout your app. The XAML syntax shown for Brush types is appropriate for defining the brush as a resource. When you declare a brush as a resource, you also need an x:Key attribute that you'll later use to refer to that resource from other UI definitions. For more info on XAML resources and how to use x:Key, see ResourceDictionary and XAML resource references.

The advantage of declaring brushes as resources is that it reduces the number of runtime objects that are needed to construct a UI: the brush is now shared as a common resource that's providing values for multiple parts of the object graph.

If you look at the existing control template definitions for Windows Runtime XAML controls, you'll see that the templates use brush resources extensively. Many of these resources are system resources, and they use the ThemeResource markup extension for the resource reference rather than StaticResource. For more info on how to use system resource brushes in your own control template XAML, see XAML theme resources reference.

Examples

The most common way to use SolidColorBrush is to define a XAML element as a resource in a ResourceDictionary, and then reference that resource later from other parts of UI definitions, styles or templates using either StaticResource or ThemeResource markup extensions.


<ResourceDictionary>
...
    <SolidColorBrush x:Key="BlockBackgroundBrush" Color="#FF557EB9"/>
...
</ResourceDictionary>


<Border Background="{StaticResource BlockBackgroundBrush}" 
    Width="80" Height="80" />


There are several different ways to define a SolidColorBrush as an inline UI value rather than as a resource:

  • Select a predefined color by name, and rely on the XAML "shortcut" that this color will create a SolidColorBrush when it's parsed. For example, you can set the Fill of a Rectangle to "Red" like this:


<Canvas
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

  <!-- This rectangle's fill is painted with a red SolidColorBrush,
       described using a named color. -->
  <Rectangle Width="100" Height="100" Fill="Red" />
</Canvas>


  • Create a color within a 32-bit color palette by specifying the amounts of red, green, and blue to combine into a single solid color.


<Canvas
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

  <!-- This rectangle's fill is painted with a red SolidColorBrush,
       described using a named color. -->
  <Rectangle Width="100" Height="100" Fill="Red" />
</Canvas>


The format for specifying a color from the 32-bit palette is #rrggbb, where rr is a two character hexadecimal number specifying the relative amount of red, gg specifies the amount of green, and bb specifies the amount of blue. Additionally, the color can be specified as #aarrggbb, where aa specifies the alpha value, or transparency, of the color. This approach enables you to create colors that are partially transparent. In this next example, the Fill of a Rectangle is set to fully opaque red using hexadecimal notation.

To use a SolidColorBrush object in code you typically construct it using the constructor that takes a Color value. The static properties of the Colors class are useful for that. A SolidColorBrush is a runtime class so in C++/CX make sure you include the ref keyword prior to new.


SolidColorBrush greenBrush = new SolidColorBrush(Colors.Green);

Another way to define a new SolidColorBrush object is to use the FromArgb static utility method. This is useful if there is no named Colors value for the color you want.


SolidColorBrush myBrush = new SolidColorBrush(Color.FromArgb(255, 20, 20, 90));


Requirements

Minimum supported client

Windows 8 [Windows Store apps only]

Minimum supported server

Windows Server 2012 [Windows Store apps only]

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.UI.Xaml.Media
Windows::UI::Xaml::Media [C++]

Metadata

Windows.winmd

See also

Color
Colors
Brush
Color.FromArgb
Quickstart: Using brushes
ResourceDictionary and XAML resource references

 

 

Show:
© 2014 Microsoft