SolidColorBrush Class

Definition

Namespace:

Windows.UI.Xaml.Media

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

public ref class SolidColorBrush sealed : Brush

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.UI.Xaml.Markup.ContentProperty(Name="Color")]
/// [Windows.Foundation.Metadata.Activatable(Windows.UI.Xaml.Media.ISolidColorBrushFactory, 65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
class SolidColorBrush final : Brush

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.UI.Xaml.Markup.ContentProperty(Name="Color")]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.UI.Xaml.Media.ISolidColorBrushFactory), 65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
public sealed class SolidColorBrush : Brush

Public NotInheritable Class SolidColorBrush
Inherits Brush

<SolidColorBrush .../>
-or-
<SolidColorBrush>colorString</SolidColorBrush>
- or -
<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"/>

Inheritance

Object Platform::Object IInspectable DependencyObject Brush SolidColorBrush

Attributes

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute ContentPropertyAttribute

Windows requirements

Device family	Windows 10 (introduced in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduced in v1.0)

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} markup extension or {ThemeResource} markup extension s.

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

• Select a custom color from a 24-bit color range consisting of chosen amounts of red, green, and blue by using a hexadecimal RGB color code:

<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 an RGB-style hex color code. -->
  <Rectangle Width="100" Height="100" Fill="#FF0000" />
</Canvas>

• You can also specify a custom color with a specified opacity by setting the desired property to an ARGB color code in hexadecimal format:

<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 fully opaque red SolidColorBrush,
       described using an ARGB style hex code. -->
  <Rectangle Width="100" Height="100" Fill="#FFFF0000" />
</Canvas>

Solid color brushes can be created in code-behind by instantiating a SolidColorBrush object with a predefined color from the Colors struct.

SolidColorBrush greenBrush = new SolidColorBrush(Colors.Green);

Windows::UI::Xaml::Media::SolidColorBrush greenBrush{ Windows::UI::Colors::Green() };

auto greenBrush = ref 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));

Windows::UI::Xaml::Media::SolidColorBrush myBrush{ Windows::UI::ColorHelper::FromArgb(255, 90, 200, 90) };

auto myBrush = ref new SolidColorBrush(ColorHelper::FromArgb(255, 90, 200, 90));

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 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 attribute, 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} markup extension. For more info on how to use system resource brushes in your own control template XAML, see XAML theme resources.

Constructors

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.

Properties

Color	Gets or sets the color of this SolidColorBrush.
ColorProperty	Identifies the Color dependency property.
Dispatcher	Gets the CoreDispatcher that this object is associated with. The CoreDispatcher represents a facility that can access the DependencyObject on the UI thread even if the code is initiated by a non-UI thread. (Inherited from DependencyObject)
Opacity	Gets or sets the degree of opacity of a Brush. (Inherited from Brush)
RelativeTransform	Gets or sets the transformation that is applied to the brush using relative coordinates. (Inherited from Brush)
Transform	Gets or sets the transformation that is applied to the brush. (Inherited from Brush)

Methods

ClearValue(DependencyProperty)	Clears the local value of a dependency property. (Inherited from DependencyObject)
GetAnimationBaseValue(DependencyProperty)	Returns any base value established for a dependency property, which would apply in cases where an animation is not active. (Inherited from DependencyObject)
GetValue(DependencyProperty)	Returns the current effective value of a dependency property from a DependencyObject. (Inherited from DependencyObject)
PopulatePropertyInfo(String, AnimationPropertyInfo)	Defines a property that can be animated. (Inherited from Brush)
PopulatePropertyInfoOverride(String, AnimationPropertyInfo)	When overridden in a derived class, defines a property that can be animated. (Inherited from Brush)
ReadLocalValue(DependencyProperty)	Returns the local value of a dependency property, if a local value is set. (Inherited from DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registers a notification function for listening to changes to a specific DependencyProperty on this DependencyObject instance. (Inherited from DependencyObject)
SetValue(DependencyProperty, Object)	Sets the local value of a dependency property on a DependencyObject. (Inherited from DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Cancels a change notification that was previously registered by calling RegisterPropertyChangedCallback. (Inherited from DependencyObject)

See also

• Color
• Colors
• Brush
• Color.FromArgb
• Use brushes
• ResourceDictionary and XAML resource references