Image.Source property

Applies to Windows and Windows Phone

Gets or sets the source for the image.

Syntax


public:
property ImageSource^ Source { 
   ImageSource^ get();
   void set (ImageSource^ value);
}


<Image Source="uri"/>

XAML Values

uri

The URI location of the image source file. In XAML syntax, you can specify what appears to be a relative URI that is relative to a base URI. The base URI is interpreted based on the location of the XAML file that loads it, and uses the ms-appx: scheme implicitly. For more info see Remarks.

Property value

Type: ImageSource

An object that represents the image source file for the drawn image. Typically you set this with a BitmapImage object, constructed with the URI that describes the path to a valid image source file. Or, you can initialize a BitmapSource with a stream, perhaps a stream from a storage file.

Remarks

Setting the Source property is inherently an asynchronous action. Because it's a property, there isn't an awaitable syntax, but for most scenarios you don't need to interact with the asynchronous aspects of image source file loading. The framework will wait for the image source to be returned, and will rerun layout when the image source file becomes available.

Setting the source to a URI value that can't be resolved to a valid image source file does not throw an exception. Instead, it fires an ImageFailed event. Decoding failures also fire ImageFailed. You can write an ImageFailed handler and attach it to the Image object to detect this, and possibly use the ErrorMessage in event data to determine the nature of the failure. Also, if you want to verify that an image source file was loaded correctly, you can handle the ImageOpened event on the Image element.

Setting Source in XAML

If you set the Source property as an attribute in XAML, you are setting the Source property using a URI. This behavior relies on underlying type conversion that processes the string as a URI, and calls the equivalent of the BitmapImage(Uri) constructor. The XAML parser interprets any strings that represent a relative URI, using the base URI of the XAML page that is being parsed. For example, if you specify a value "Images/myimage.png" in XAML, that string is interpreted as a relative path suffix that is appended to the base URI location within the app package where the XAML page itself exists.


<Image Width="200" Source="Images/myimage.png" />

A property element syntax in XAML is also possible, specifying a BitmapImage object element with valid source as the property value.

Setting Source in code

If you create an Image object using code, Image.Source requires a BitmapImage or BitmapSource (not a URI) in code. If your source is content in your app, use the BitmapImage constructor that takes a URI. The Windows Runtime enforces that a URI must be absolute, you can't use relative URIs in Windows Runtime code.

How you construct the URI will vary, depending on how and where you package the image source file within your app. You can construct a Uri using one of the signatures that creates a URI from an absolute base and then a relative part/path. In C# or Microsoft Visual Basic, the URI type is projected as System.Uri, so use the System.Uri constructors that take a string as the second parameter. In Visual C++ component extensions (C++/CX) use Uri(String,String). For the first parameter, call BaseUri on the Image instance where you are setting the source. This creates a URI with the ms-appx: scheme and adds the path that is part of the XAML page's location. For example: CapturedPhoto.Source = new BitmapImage(new Uri(this.BaseUri, "Assets/placeholder-sdk.png"));

If you're using the http: or https: schemes, use a Uri constructor that takes a string, specifying the whole string of the URI including the scheme. If you are using a .NET Framework System.Uri value, and you use a signature that requires a UriKind value, make sure to specify Absolute.

Here's an example of setting Image.Source in C#. In this example, the Image object was created in XAML but doesn't have a source or any other property values; instead these values are provided at run-time when the Image is loaded from XAML.


void Image_Loaded(object sender, RoutedEventArgs e)
{
    Image img = sender as Image; 
    BitmapImage bitmapImage = new BitmapImage();
    img.Width = bitmapImage.DecodePixelWidth = 80; //natural px width of image source
    // don't need to set Height, system maintains aspect ratio, and calculates the other
    // dimension, so long as one dimension measurement is provided
    bitmapImage.UriSource = new Uri(img.BaseUri,"Images/myimage.png");
}

Still another option is to use image source files that are placed in your app's local storage, using the ms-appdata: scheme.

Use SetSourceAsync if you're using image sources that are only available at run-time to set an Image, for example image files you've enabled the user to choose by displaying a FileOpenPicker in your UI.


FileOpenPicker open = new FileOpenPicker(); 
// Open a stream for the selected file 
StorageFile file = await open.PickSingleFileAsync(); 
// Ensure a file was selected 
if (file != null) 
{ 
    using (IRandomAccessStream fileStream = await file.OpenAsync(Windows.Storage.FileAccessMode.Read)) 
    { 
        // Set the image source to the selected bitmap 
         BitmapImage bitmapImage = new BitmapImage(); 
         bitmapImage.DecodePixelWidth = 600; //match the target Image.Width, not shown
         await bitmapImage.SetSourceAsync(fileStream); 
         Scenario2Image.Source = bitmapImage; 
    } 
}

You can handle 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.

Image sources and scaling

If you are referencing images that are packaged in your app, you should create your image sources at several recommended sizes, to ensure that your app looks great when the Windows Runtime scales it. When specifying a Source for an Image as a URI, you can use a naming convention that will automatically reference the correct image resource for the current scaling as detected by the system at run-time. 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 or Remarks in Image.

Image sources and resource qualifiers

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 or Remarks in Image. For more info on app resources and how to package image sources in an app, see Defining app resources.

Displaying images from the Pictures library

Some apps might define UI that shows users some or all of the contents of their Pictures library. You can use the Image element in order to display the actual images in the UI. The contents of the Pictures library are available as either a StorageFolderQueryResult or the returned value of a StorageFolder.GetFilesAsync call. To display an individual image, use the StorageFile objects from enumerating the library and call OpenAsync to obtain a stream. Use this stream to set the image source, by creating a new BitmapSource, calling SetSourceAsync using the stream. Remember that you need to specify a capability to access the Pictures library programmatically.

Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.UI.Xaml.Controls
Windows::UI::Xaml::Controls [C++]

Metadata

Windows.winmd

See also

Image
ImageFailed
Quickstart: Image and ImageBrush

 

 

Show:
© 2014 Microsoft