ImageBrush class

Applies to Windows and Windows Phone

Paints an area with an image. The image source is typically obtained from file formats such as JPEG.

Inheritance

Object
  DependencyObject
    Brush
      TileBrush
        ImageBrush

Syntax


public sealed class ImageBrush : TileBrush


<ImageBrush .../>

Attributes

[MarshalingBehavior(Agile)]
[Threading(Both)]
[Version(0x06020000)]
[WebHostHidden()]

Members

The ImageBrush class has these types of members:

Constructors

The ImageBrush class has these constructors.

ConstructorDescription
ImageBrush Initializes a new instance of the ImageBrush class.

 

Events

The ImageBrush class has these events.

EventDescription
ImageFailed Occurs when there is an error associated with image retrieval or format.
ImageOpened Occurs when the image source is downloaded and decoded with no failure. You can use this event to determine the size of an image before rendering it.

 

Methods

The ImageBrush 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 ImageBrush class has these properties.

PropertyAccess typeDescription

AlignmentX

Read/writeGets or sets the horizontal alignment of content in the TileBrush base tile. (Inherited from TileBrush)

AlignmentY

Read/writeGets or sets the vertical alignment of content in the TileBrush base tile. (Inherited from TileBrush)

Dispatcher

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

ImageSource

Read/writeGets or sets the image source displayed by this ImageBrush. In code you set this with an ImageSource subclass instance, in XAML you set this with a URI to an image source file.

ImageSourceProperty

Read-onlyIdentifies the ImageSource dependency property.

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)

Stretch

Read/writeGets or sets a value that specifies how the content of this TileBrush stretches to fit its tiles. (Inherited from TileBrush)

Transform

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

 

Remarks

An ImageBrush is a type of TileBrush that defines its content as an image. You can control how the image is stretched, aligned, and tiled, enabling you to produce patterns and other effects. Use for an ImageBrush include decorative effects for text, or tiled backgrounds for controls or layout containers.

If you define an ImageBrush using code, use the default constructor, then set ImageBrush.ImageSource. This requires a BitmapImage (not a URI) in code. If your source is a stream, use the SetSourceAsync method to initialize the value. If your source is a Uniform Resource Identifier (URI), which includes content in your app that uses the ms-appx or ms-resource schemes, use the BitmapImage constructor that takes a URI. You might also consider handling the ImageOpened event if there are any timing issues with retrieving or decoding the image source, where you might need alternate content to display until the image source is available. See XAML images sample for example code.

Note  You can use automatic handling for accessing unqualified resources with current scale and culture qualifiers, or you can use ResourceManager and ResourceMap with qualifiers for culture and scale to obtain the resources directly. For more info see Resource management system.

The Stretch property is important for how the image is applied when used as a brush. Some images look good when stretched as applied to a particular Brush property with the Fill behavior whereas other images do not stretch or scale well and might require a value of None or Uniform for Stretch. Also some images are designed to tile whereas some are not. Experiment with different values for Stretch to see which behavior looks best when applied to the UI.

Image sources and scaling

You should create your image sources at several recommended sizes, to ensure that your app looks great when Windows 8 scales it. When specifying an ImageSource for an ImageBrush, you can use a naming convention that will automatically reference the correct resource for the current scaling. For specifics of the naming convention and more info, see Quickstart: Using file or image resources.

For more info on how to design for scaling, see Guidelines for scaling to pixel density.

Windows 8 behavior

Windows 8 had an issue with ImageSource resolution from a XAML attribute URI value, if the ImageBrush is part of a XAML style or template that's applied to a control. The control usage would sometimes use a component-specific base URI rather than the appropriate base URI for the style or template, which usually comes from the app. The issue is fixed starting with Windows 8.1; the base URI is correctly determined for app resources or component resources depending on the scope that needs the base URI. Apps that were compiled for Windows 8 might have used workarounds for this behavior, by putting their image source files in the "wrong" place, where the XAML URI would resolve and the app would show the images. If you are migrating XAML from Windows 8 to Windows 8.1 you should test any ImageBrush usages in a style or template from your XAML and verify that the image resolution in your app is working with Windows 8.1. If you have a problem, you should move your image source files within the package so that they're in the correct resource scope for the new behavior.

Apps that were compiled for Windows 8 but running on Windows 8.1 continue to use the Windows 8 behavior.

Examples

This XAML example shows how to set the Foreground property of a TextBlock to an ImageBrush, whose image is used as the fill for the TextBlock-rendered text.


<!-- TextBlock with an image brush applied to the text. -->
<TextBlock FontFamily="Verdana" FontSize="72"
 FontStyle="Italic" FontWeight="Bold">
    SHRUBBERY
  <TextBlock.Foreground>
    <ImageBrush ImageSource="forest.jpeg"/>
  </TextBlock.Foreground>
</TextBlock>


This illustration shows the results of this XAML example.

An ImageBrush applied to text

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

TileBrush
Image
Quickstart: Image and ImageBrush
XAML vector-based drawing sample (see Scenario 2)

 

 

Show:
© 2014 Microsoft