Wahlin on .NET

Silverlight XAML Primer 3: Working with Image Brushes

Dan shows you how to use Silverlight's brushes to create custom images.

• By Dan Wahlin
• 12/11/2007

Silverlight makes it easy to define different types of shapes within a XAML canvas and apply various colors and borders. In my last article, I showed how ellipses, rectangles and text could be defined using XAML and how background colors could be applied. But while applying standard colors to shapes is certainly useful in many situations, there will be times when you'll need more control over the look and feel of a particular shape. In this article, I'll explore one way this can be accomplished using Silverlight image brushes. Future articles will discuss other types of brushes, such as gradient and video brushes.

Working with Image Brushes
Silverlight exposes an element named ImageBrush that can be used to show images within XAML objects. The ImageBrush element is useful any time you'd like to "paint" a PNG or JPEG image into a Silverlight object. Use it whenever you'd like to show a custom image as the foreground of a TextBlock element or want to assign an image as the background of a particular object.

The code below shows an example of using the ImageBrush element with a TextBlock to add an image as the foreground of the text. Notice that the ImageBrush is defined as a child of the TextBlock.Foreground property element and that the path to the image is defined using the ImageSource attribute.

<TextBlock Name="tbImageBrush"
 Canvas.Left="36" Canvas.Top="80"
 FontFamily="Verdana" FontSize="60" FontWeight="Bold"
 Text="Text with Brush">

 <TextBlock.Foreground>
  <ImageBrush ImageSource="Images/GreenPlant.jpg" />   
 </TextBlock.Foreground>

</TextBlock>

The image added to the TextBlock in the code above automatically fills the text's foreground based upon the TextBlock's size. The ImageBrush element can also be used to define a background for a canvas (or any other XAML element that supports a background). Listing 1 shows how to provide a background image for a canvas using the ImageBrush element.

The ImageBrush element defines a Stretch attribute that can be used to control how an image is displayed (as shown in Listing 1). The Silverlight 1.0 documentation provides the following insight into the values that can be supplied to the Stretch attribute:

• None: The content does not stretch to fill the output dimensions, and the applied brush area will come from the matching sized area of the image.
• Uniform: The content is scaled to fit the output dimensions. However, the aspect ratio of the content is preserved. (This means that if the dimensions of the image don't match the dimensions of the target control -- the target control is wider, for example -- then extra space will show in the dimension that doesn't match. In other words, the image won't try to stretch to fit into the non-matching dimension.)
• UniformToFill: The content is scaled so that it completely fills the output area but preserves its original aspect ratio.
• Fill: The content is scaled to fit the output dimensions. Because the content's height and width are scaled independently, the original aspect ratio of the content might not be preserved. That is, the content might be distorted in order to completely fill the output area.

In cases where an ImageBrush uses an image that's smaller than the target element, the Stretch attribute's Fill or UniformToFill values can be used to ensure that the image takes up the entire area of the target element. Keep in mind that, in some cases, this may result in undesirable stretching of the image as its aspect ratio changes.

The placement of the image within its container can also be influenced using the AlignmentX and AlignmentY attributes. The AlignmentX attribute can be assigned values of Left, Center or Right, while the AlignmentY attribute can be assigned values of Top, Center or Bottom.

Figure 1 shows an example of the output generated by using the ImageBrush to apply a TextBlock with a foreground image and a canvas with a background image. The background image brush has its Stretch attribute assigned to a value of Fill.

In the next article, I'll explore another type of brush called the GradientBrush and explain how it can be used to apply gradients to XAML elements.