Quickstart: Image and ImageBrush (XAML)
[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]
Roadmap: How does this topic relate to others? See:
- Roadmap for Windows Runtime apps using C# or Visual Basic
- Roadmap for Windows Runtime apps using C++
Image and ImageBrush
To render an image, you can use either the Image object or the ImageBrush object. An Image object renders an image, and an ImageBrush object paints another object with an image. This example shows how to create an image by using the Image object.
<Image Width="200" Source="licorice.jpg" />
Here's the rendered Image object.
In this example, the Source property specifies the location of the image that you want to display. You can set the Source by specifying an absolute URL (for example, http://contoso.com/myPicture.jpg) or by specifying a URL that is relative to your app packaging structure. For our example, we put the "licorice.jpg" image file in the root folder of our project and declare project settings that include the image file as content.
With the ImageBrush object you can use an image to paint an area that takes a Brush object. For example, you can use an ImageBrush for the value of the Fill property of an Ellipse or the Background property of a Canvas.
<Ellipse Height="200" Width="300"> <Ellipse.Fill> <ImageBrush ImageSource="licorice.jpg" /> </Ellipse.Fill> </Ellipse>
Stretching an image
If you don't set the Width or Height values of an Image, it is displayed with the dimensions of the image specified by the Source. Setting the Width and Height creates a containing rectangular area in which the image is displayed. You can specify how the image fills this containing area by using the Stretch property. The Stretch property accepts these values, which the Stretch enumeration defines:
- None: The image doesn't stretch to fill the output dimensions. Be careful with this Stretch setting: if the source image is larger than the containing area, your image will be clipped, and this usually isn't desirable because you don't have any control over the viewport like you do with a deliberate Clip.
- Uniform: The image is scaled to fit the output dimensions. But the aspect ratio of the content is preserved. This is the default value.
- UniformToFill: The image is scaled so that it completely fills the output area but preserves its original aspect ratio.
- Fill: The image is scaled to fit the output dimensions. Because the content's height and width are scaled independently, the original aspect ratio of the image might not be preserved. That is, the image might be distorted to completely fill the output area.
Cropping an image
The next example shows how to use a RectangleGeometry as the clip region for an image. In this example, we define an Image object with a Height of 200. A RectangleGeometry defines a rectangle for the area of the image that will be displayed. The Rect property is set to "25,25,100,150", which defines a rectangle starting at position "25,25" with a width of 100 and a height of 150. Only the part of the image that is within the area of the rectangle is displayed.
<Image Source="licorice.jpg" Height="200"> <Image.Clip> <RectangleGeometry Rect="25,25,100,150" /> </Image.Clip> </Image>
Here's the clipped Image object.
Applying an opacity
You can apply an Opacity to an image so that the image is rendered semi-translucent. The opacity values are from 0.0 to 1.0 where 1.0 is fully opaque and 0.0 is fully transparent. This example shows how to apply an opacity of 0.5 to an Image.
<Image Height="200" Source="licorice.jpg" Opacity="0.5" />
Here's the rendered Image object with an opacity of 0.5 and a black background showing through the partial opacity.
Image file formats
- Joint Photographic Experts Group (JPEG)
- Portable Network Graphics (PNG)
- bitmap (BMP)
- Graphics Interchange Format (GIF)
- Tagged Image File Format (TIFF)
- JPEG XR
- icons (ICO)
For more info on app resources and how to package image sources in an app, see Defining app resources.
A WriteableBitmap provides a BitmapSource that can be modified and that doesn't use the basic file-based decoding from the WIC. You can alter images dynamically and re-render the updated image. To define the buffer content of a WriteableBitmap, use the PixelBuffer property to access the buffer and use a stream or language-specific buffer type to fill it. For example code, see WriteableBitmap.
The RenderTargetBitmap class is available starting with Windows 8.1. This class can capture the XAML UI tree from a running app, and then represents a bitmap image source. After capture, that image source can be applied to other parts of the app, saved as a resource or app data by the user, or used for other scenarios. One particularly useful scenario is creating a runtime thumbnail of a XAML page for a navigation scheme, such as providing an image link from a Hub control. RenderTargetBitmap does have some limitations on the content that will appear in the captured image. For more info, see the reference topic for RenderTargetBitmap.
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 a Source for an Image, 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.
Image and ImageBrush in code
If you define an Image or ImageBrush using code, use the default constructors then set the relevant properties (Image.Source and ImageBrush.ImageSource). These require a BitmapImage (not a URI) when you define them using 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 If you establish images using code, 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.