ImageBrush ImageBrush ImageBrush Class

Paints an area with an image. The image source is typically obtained from file formats such as Joint Photographic Experts Group (JPEG).

Syntax

Declaration

public sealed class ImageBrushpublic sealed class ImageBrushPublic NotInheritable Class ImageBrush
<ImageBrush .../>

Inheritance Hierarchy

Inherited Members

, , , , , , , , , , , , , , , , , , ,

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 ImageSource. This requires a BitmapImage (not a Uniform Resource Identifier (URI)) in code. If your source is a stream, use the SetSourceAsync(Windows.Storage.Streams.IRandomAccessStream) 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 @Windows.UI.Xaml.Media.Imaging.BitmapImage.#ctor(Windows.Foundation.Uri) constructor that takes a Uniform Resource Identifier (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 UX guidelines for layout and scaling.

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>

An ImageBrush applied to text

Constructors summary

Initializes a new instance of the ImageBrush class.

Properties summary

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

Identifies the ImageSource dependency property.

Events summary

Occurs when there is an error associated with image retrieval or format.

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.

Constructors

  • ImageBrush()
    ImageBrush()
    ImageBrush()
    ImageBrush()

    Initializes a new instance of the ImageBrush class.

    public ImageBrush()public ImageBrush()Public Function ImageBrush() As

Properties

  • ImageSource
    ImageSource
    ImageSource
    ImageSource

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

    public ImageSource ImageSource { get; set; }public ImageSource ImageSource { get; set; }Public ReadWrite Property ImageSource As ImageSource
    <ImageBrush ImageSource="imageUri"/>
    

    Property Value

    Remarks

    Setting an image source from an image source file or stream is inherently an asynchronous action. Setting the source to a Uniform Resource Identifier (URI) value that cannot be resolved to a valid image source file does not throw an error. Instead, it fires an ImageFailed event on the ImageBrush. If you want to verify that an image source file did load correctly, you can handle ImageOpened for verification, plus ImageFailed as a way to provide a fallback image source or recompose your UI.

    Setting ImageSource in XAML

    You can set this property in XAML, but in this case you are setting the ImageSource attribute value as a string representing a Uniform Resource Identifier (URI). This behavior relies on underlying type conversion that processes the string as a Uniform Resource Identifier (URI), and calls the internal equivalent of the @Windows.UI.Xaml.Media.Imaging.BitmapImage.#ctor(Windows.Foundation.Uri) constructor.

    The ImageFailed event can occur if the initial ImageSource attribute value in XAML does not specify a valid source. You can use a relative path to reference an image that you package with the app, or an absolute Uniform Resource Identifier (URI) to reference an image from a server. If you are using an image source that's packaged as part of your app, it's common to use either the ms-appx or ms-resource schemes.

    Setting ImageSource in code

    If you define an ImageBrush using code, ImageSource requires a BitmapImage (not a Uniform Resource Identifier (URI)) in code. If your source is a stream, use the SetSourceAsync(Windows.Storage.Streams.IRandomAccessStream) method to initialize the value. If your source is a Uniform Resource Identifier (URI) referencing a file, which includes content in your app that uses the ms-appx or ms-resource schemes, use the @Windows.UI.Xaml.Media.Imaging.BitmapImage.#ctor(Windows.Foundation.Uri) constructor that takes a Uniform Resource Identifier (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.

    If you need to compose a URI in relation to another object in the UI to help scope the resource request, you can sometimes use the BaseUri property as called on another object in the UI. This provides a base URI that is where the XAML page comes from within the app's project structure.

    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.

    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 UX guidelines for layout and scaling.

    For more info on app resources and how to package image sources in an app, see Defining app resources.

    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.

  • ImageSourceProperty
    ImageSourceProperty
    ImageSourceProperty
    ImageSourceProperty

    Identifies the ImageSource dependency property.

    public static DependencyProperty ImageSourceProperty { get; }public static DependencyProperty ImageSourceProperty { get; }Public Static ReadOnly Property ImageSourceProperty As DependencyProperty

    Property Value

Events

  • ImageFailed
    ImageFailed
    ImageFailed
    ImageFailed

    Occurs when there is an error associated with image retrieval or format.

    public event ExceptionRoutedEventHandler ImageFailedpublic event ExceptionRoutedEventHandler ImageFailedPublic Event ImageFailed
    <ImageBrush ImageFailed="eventhandler"/>
    

    Remarks

    If this event fires, that means that the ImageSource value has been asynchronously determined to not be available, or is not suitable for use. Conditions in which this event can occur include:

    • File not found
    • Invalid (unrecognized or unsupported) file format
    • Unknown file format decoding error after upload An ImageBrush in this situation won't display anything. There is no default "missing image" placeholder image for app images as there might be when a browser can't resolve an image URI. If you want behavior like that you'll have to implement it.

    ImageFailed and ImageOpened are mutually exclusive. One event or the other will always file whenever an ImageBrush has the ImageSource value set or reset.

  • ImageOpened
    ImageOpened
    ImageOpened
    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.

    public event RoutedEventHandler ImageOpenedpublic event RoutedEventHandler ImageOpenedPublic Event ImageOpened
    <ImageBrush ImageOpened="eventhandler"/>
    

    Remarks

    For the scenario of checking the size of an image before rendering, that info isn't part of the ImageOpened event data. Instead, the fact that the event fired is the notification that the PixelHeight and PixelWidth values of the image source (ImageSource value) are available.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.ActivatableAttribute

Details

Assembly

Windows.UI.Xaml.Media.dll