ImageBrush Class

Reference

Definition

Namespace:: Microsoft.UI.Xaml.Media

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

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

public ref class ImageBrush sealed : TileBrush

/// [Windows.Foundation.Metadata.Activatable(65536, "Microsoft.UI.Xaml.WinUIContract")]
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class ImageBrush final : TileBrush

[Windows.Foundation.Metadata.Activatable(65536, "Microsoft.UI.Xaml.WinUIContract")]
[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class ImageBrush : TileBrush

Public NotInheritable Class ImageBrush
Inherits TileBrush

<ImageBrush .../>

Inheritance: Object Platform::Object IInspectable DependencyObject Brush TileBrush ImageBrush

Attributes: ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

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>

Remarks

An ImageBrush is a type of brush that defines its content as an image which can be optionally stretched and aligned. Uses for an ImageBrush include decorative effects for text, or image backgrounds for controls or layout containers.

It's useful to use an ImageBrush instead of an Image control in two main scenarios:

You want to paint a non-rectangular area such as an ellipse or border with an image
You want to use a single ImageBrush to paint multiple areas or UIElements with the same image, which is more efficient than using multiple Image controls

If you define an ImageBrush using code, use the default constructor, then set ImageBrush.ImageSource. This requires a BitmapImage (not a Uniform Resource Identifier (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 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. 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.

Constructors

ImageBrush()

Initializes a new instance of the ImageBrush class.

Properties

AlignmentX	Gets or sets the horizontal alignment of content in the TileBrush base tile. (Inherited from TileBrush)
AlignmentY	Gets or sets the vertical alignment of content in the TileBrush base tile. (Inherited from TileBrush)
Dispatcher	Always returns `null` in a Windows App SDK app. Use DispatcherQueue instead. (Inherited from DependencyObject)
DispatcherQueue	Gets the `DispatcherQueue` that this object is associated with. The `DispatcherQueue` 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)
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.
ImageSourceProperty	Identifies the ImageSource dependency property.
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)
Stretch	Gets or sets a value that specifies how the content of this TileBrush stretches to fit its tiles. (Inherited from TileBrush)
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)

Events

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.

Applies to

Share via