Displaying Images with the Image Element
The Image is a FrameworkElement that makes it easy to display both local or remote images on the phone.
The Image element supports two image formats: PNG and JPEG, and displays indexed images with 1, 4, or 8 bit color-depth, or true color images with 24 or 32 bit color-depth.
The Image.Source property is used to set the URI of the image file location. This value can be either an absolute or relative URI. A URI can be used to specify a source file from a variety of locations, including the following:
The current assembly
A referenced assembly
The XAP file
An external network, such as an image on the Web
Relative URIs are the most common way to identify local images in Windows Phone apps. The following example demonstrates how to display an image called Book.jpg, which is located in the root directory of a project, and which has its Build Action set to Content:
<Image Source="/Book.jpg" />
Note
When the Build Action of an image file is set to Content, its path is relative to the root of the project. Conversely, when the Build Action is set to Resource, its path is relative to the directory in which it is located.
If the image were located in a subdirectory of the project—for example, a directory called Images, then the Image element would be as follows:
<Image Source="/Images/Book.jpg" />
The trailing slash is required when referring to images with a Build Action set to Content. If using a Build Action of Resource, a trailing slash cannot be used:
<Image Source="Images/BookAsResource.png" />
Tip
Avoid setting the Build Action of images to Resource. Instead use the Content Build Action because this will reduce the size of your project’s assembly, thus reducing the time the CLR takes to load it.
One caveat, however, is that it takes longer for the CLR to fetch a file that is content than it does to fetch a file that is a resource. This is because the image file data becomes present in memory as soon as the assembly is loaded. So, the Content build action, while reducing the startup time of your app, may lead to some images being displayed after the rest of the UI has been displayed. This is especially important for background images, whose momentary absence will be glaringly evident. The general rule: If you need an image to be loaded immediately because it is the background for a page, for example, use the Resource Build Action; otherwise, use the Content Build Action.
An absolute URI, which targets an image in the same or another assembly, can be specified using the Relative Component URI scheme, as the following example demonstrates:
<Image Source="/AssemblyNameWithoutTheDllExtension;component/Images/Book.png" />
The URL of an image located on the Web can also be specified as shown:
<Image Source="http://www.example.com/Images/Book.jpg" />
Tip
Try to limit the number of images in your app. Even if your image happens to be a 30KB compressed JPEG image, at runtime that image becomes an uncompressed surface that may take several MBs of memory. In most cases an application must never consume more than 90MB of RAM, unless it has more than 256MB of total memory; otherwise, it will fail Windows Phone Marketplace certification.
For more information on measuring the memory available to your app, see the section “Device Status,” in Chapter 2, “Fundamental Concepts in Windows Phone Development.”
Working examples for each of these cases are located in the MediaExamplesView.xaml page in the downloadable sample code.
There are numerous examples of using the Image control throughout this book; you see how to implement image localizability, image caching, and in Chapter 14, “Leveraging Built-In Apps via Launchers and Choosers,” you see how to data bind the Image.Source property to a viewmodel property.