BitmapImage BitmapImage BitmapImage Class

Provides the practical object source type for the Source and ImageSource properties. You can define a BitmapImage by using a Uniform Resource Identifier (URI) that references an image source file, or by calling SetSourceAsync(Windows.Storage.Streams.IRandomAccessStream) and supplying a stream.

Syntax

Declaration

public sealed class BitmapImagepublic sealed class BitmapImagePublic NotInheritable Class BitmapImage
<BitmapImage .../>

Inheritance Hierarchy

Inherited Members

, , , , , , , , , , , , ,

Remarks

A BitmapImage can be sourced from these 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)

If the image source is a stream, that stream is expected to contain an image file in one of these formats.

The BitmapImage class represents an abstraction so that an image source can be set asynchronously but still be referenced in XAML markup as a property value, or in code as an object that doesn't use awaitable syntax. When you create a BitmapImage object in code, it initially has no valid source. You should then set its source using one of these techniques:

  • Use the @Windows.UI.Xaml.Media.Imaging.BitmapImage.#ctor(Windows.Foundation.Uri) constructor rather than the default constructor. Although it's a constructor you can think of this as having an implicit asynchronous behavior: the BitmapImage won't be ready for use until it raises an ImageOpened event that indicates a successful async source set operation.
  • Set the UriSource property. As with using the Uri constructor, this action is implicitly asynchronous, and the BitmapImage won't be ready for use until it raises an ImageOpened event.
  • Use SetSourceAsync(Windows.Storage.Streams.IRandomAccessStream). This method is explicitly asynchronous. The properties where you might use a BitmapImage, such as Source, are designed for this asynchronous behavior, and won't throw exceptions if they are set using a BitmapImage that doesn't have a complete source yet. Rather than handling exceptions, you should handle ImageOpened or ImageFailed events either on the BitmapImage directly or on the control that uses the source (if those events are available on the control class).

ImageFailed and ImageOpened are mutually exclusive. One event or the other will always be raised whenever a BitmapImage object has its source value set or reset.

BitmapImage and encoding

The underlying codec support for image files is supplied by Windows Imaging Component (WIC) API in Windows. For more info on specific image formats as documented for the codecs, see Native WIC Codecs. For more info on formats and how to use Uniform Resource Identifier (URI) to access image source files that come from app resources, see Image and ImageBrush.

The API for Image, BitmapImage and BitmapSource doesn't include any dedicated methods for encoding and decoding of media formats. All of the encode and decode operations are built-in, and at most will surface aspects of encode or decode as part of event data for load events. If you want to do any special work with image encode or decode, which you might use if your app is doing image conversions or manipulation, you should use the API that are available in the Windows.Graphics.Imaging namespace. These imaging API can be used by either Windows Store app using C++, C#, or Visual Basic or Windows app using JavaScript. These APIs are also supported by the Windows Imaging Component (WIC) component of Windows 8.

Animated images

Starting in Windows 10, version 1607, the XAML Image element supports animated GIF images. When you use a BitmapImage as the image Source, you can access BitmapImage API to control playback of the animated GIF image.

  • Use the AutoPlay property, which defaults to true, to specify whether or not an animated bitmap plays as soon as it loads.
  • Use the IsAnimatedBitmap property to check whether a bitmap is animated.
  • Use the IsPlaying property along with the Play() and Stop() methods to control the playback of an animated bitmap.
Note

For most apps, we recommend that you set AutoPlay to false if AnimationsEnabled is false, to support the accessibility needs of users. Do not do this if the content of the animated GIF is important for the usability of your app.

If your app runs on releases of Windows 10 prior to version 1607, you must use the ApiInformation class to check for the presence of these members before you use them. For more info, see Version adaptive code: Use new APIs while maintaining compatibility with previous versions.

This example shows how to use an animated GIF. A button lets the user start or stop the animation. This example uses version adaptive code so it can run on all versions of Windows 10. On versions prior to version 1607, the first frame of the GIF is shown, but it is not animated.

<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
    <Image Loaded="Image_Loaded">
        <Image.Source>
            <BitmapImage x:Name="imageSource"
                         UriSource="Assets/example.gif"
                         ImageOpened="imageSource_ImageOpened"/>
        </Image.Source>
    </Image>

    <AppBarButton x:Name="playButton"
              Icon="Play"
              Visibility="Collapsed"
              Click="playButton_Click"/>
</Grid>
// Set the AutoPlay property.
private void Image_Loaded(object sender, RoutedEventArgs e)
{
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "AutoPlay") == true)
    {
        imageSource.AutoPlay = false;
    }
}

// Show the play/stop button if the image is animated.
private void imageSource_ImageOpened(object sender, RoutedEventArgs e)
{
    var bitmapImage = (BitmapImage)sender;
    // At this point you can query whether the image is animated or not.
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "IsAnimatedBitmap") 
        && bitmapImage.IsAnimatedBitmap == true)
    {
        // Enable the play button
        playButton.Visibility = Visibility.Visible;
    }
}

// Play or stop the animated bitmap.
void playButton_Click(object sender, RoutedEventArgs e)
{
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "IsPlaying"))
    {
        // You can call the Play and Stop methods safely because is the IsPlaying property is
        // present, these methods are also present.
        if (imageSource.IsPlaying == true)
        {
            playButton.Icon = new SymbolIcon(Symbol.Play);
            imageSource.Stop();
        }
        else
        {
            playButton.Icon = new SymbolIcon(Symbol.Stop);
            imageSource.Play();
        }
    }
}

For more examples, see the Animated GIF playback sample.

Examples

Here's an example of using a BitmapImage object to set 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.

<Image Loaded="Image_Loaded"/>
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.
    // You don't need to set Height; the system maintains aspect ratio, and calculates the other
    // dimension, as long as one dimension measurement is provided.
    bitmapImage.UriSource = new Uri(img.BaseUri,"Images/myimage.png");
}

Constructors summary

Initializes a new instance of the BitmapImage class.

Initializes a new instance of the BitmapImage class, using the supplied Uniform Resource Identifier (URI).

Properties summary

Gets or sets a value that indicates whether an animated image should play as soon as it loads.

Identifies the AutoPlay dependency property.

Gets or sets the BitmapCreateOptions for a BitmapImage.

Identifies the CreateOptions dependency property.

Gets or sets the height to use for image decoding operations.

Identifies the DecodePixelHeight dependency property.

Gets or sets a value that determines how DecodePixelWidth and DecodePixelHeight values are interpreted for decoding operations.

Identifies the DecodePixelType dependency property.

Gets or sets the width to use for image decoding operations.

Identifies the DecodePixelWidth dependency property.

Gets a value that indicates whether an image is animated.

Identifies the IsAnimatedBitmap dependency property.

Gets a value that indicates whether an animated image is playing.

Identifies the IsPlaying dependency property.

Gets or sets the Uniform Resource Identifier (URI) of the graphics source file that generated this BitmapImage.

Identifies the UriSource dependency property.

Methods summary

Starts the animation of an animated image.

Ends the animation of an animated image.

Events summary

Occurs when a significant change has occurred in the download progress of the BitmapImage content.

Occurs when there is an error associated with image retrieval or format.

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.

Constructors

  • BitmapImage()
    BitmapImage()
    BitmapImage()
    BitmapImage()

    Initializes a new instance of the BitmapImage class.

    public BitmapImage()public BitmapImage()Public Function BitmapImage() As
  • BitmapImage(Windows.Foundation.Uri)
    BitmapImage(Windows.Foundation.Uri)
    BitmapImage(Windows.Foundation.Uri)
    BitmapImage(Windows.Foundation.Uri)

    Initializes a new instance of the BitmapImage class, using the supplied Uniform Resource Identifier (URI).

    public BitmapImage(Windows.Foundation.Uri)public BitmapImage(Windows.Foundation.Uri)Public Function BitmapImage(Windows.Foundation.Uri) As

    Parameters

    • uriSource

      A reference to the image source file.

Properties

  • AutoPlay
    AutoPlay
    AutoPlay
    AutoPlay

    Gets or sets a value that indicates whether an animated image should play as soon as it loads.

    public bool AutoPlay { get; set; }public bool AutoPlay { get; set; }Public ReadWrite Property AutoPlay As bool

    Property Value

    • bool
      bool
      bool

      true if an animated image should play as soon as it loads; otherwise, false. The default is true.

    Remarks

    Starting in Windows 10, version 1607, the XAML Image element supports animated GIF images. When you use a BitmapImage as the image Source, you can access BitmapImage API to control playback of the animated GIF image. For more info, see the 'Animated images' section of the BitmapImage class Remarks and the Animated GIF playback sample.

    Use the AutoPlay property, which defaults to true, to specify whether or not an animated bitmap plays as soon as it loads.

    Note

    For most apps, we recommend that you set AutoPlay to false if AnimationsEnabled is false, to support the accessibility needs of users. Do not do this if the content of the animated GIF is important for the usability of your app.

    Compatibility notes

    If your app runs on releases of Windows 10 prior to version 1607, you must set this property in code and use the ApiInformation class to check for the presence of this property before you use it. If you set this property in XAML, you will get a XAML compiler error. For more info, see Version adaptive code: Use new APIs while maintaining compatibility with previous versions.

    Examples

    This example shows how to use version adaptive code to use this property in an app that runs on all versions of Windows 10. On versions prior to version 1607, the first frame of the GIF is shown, but it is not animated.

    
    <Image Loaded="Image_Loaded">
        <Image.Source>
            <BitmapImage x:Name="imageSource"
                         UriSource="Assets/example.gif"/>
        </Image.Source>
    </Image>
    
    // Set the AutoPlay property.
    private void Image_Loaded(object sender, RoutedEventArgs e)
    {
        if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "AutoPlay") == true)
        {
            imageSource.AutoPlay = false;
        }
    }
    
  • AutoPlayProperty
    AutoPlayProperty
    AutoPlayProperty
    AutoPlayProperty

    Identifies the AutoPlay dependency property.

    public static DependencyProperty AutoPlayProperty { get; }public static DependencyProperty AutoPlayProperty { get; }Public Static ReadOnly Property AutoPlayProperty As DependencyProperty

    Property Value

  • CreateOptions
    CreateOptions
    CreateOptions
    CreateOptions

    Gets or sets the BitmapCreateOptions for a BitmapImage.

    public BitmapCreateOptions CreateOptions { get; set; }public BitmapCreateOptions CreateOptions { get; set; }Public ReadWrite Property CreateOptions As BitmapCreateOptions
    <BitmapImage CreateOptions="bitmapCreateOptionsMemberName"/>
    

    Property Value

    Remarks

    The other possible value for CreateOptions is BitmapCreateOptions. You should only use BitmapCreateOptions in cases where you know that the source image file as retrieved by Uniform Resource Identifier (URI) has the potential to change over time. Otherwise, setting CreateOptions to use BitmapCreateOptions causes all newly retrieved image sources to be decoded again, which can negatively impact performance. BitmapCreateOptions is typically only used by design tools that directly manipulate an image in a file location and need to enforce that any URI-determined content is always reloaded from the location, not from the cache.

  • CreateOptionsProperty
    CreateOptionsProperty
    CreateOptionsProperty
    CreateOptionsProperty

    Identifies the CreateOptions dependency property.

    public static DependencyProperty CreateOptionsProperty { get; }public static DependencyProperty CreateOptionsProperty { get; }Public Static ReadOnly Property CreateOptionsProperty As DependencyProperty

    Property Value

  • DecodePixelHeight
    DecodePixelHeight
    DecodePixelHeight
    DecodePixelHeight

    Gets or sets the height to use for image decoding operations.

    public int DecodePixelHeight { get; set; }public int DecodePixelHeight { get; set; }Public ReadWrite Property DecodePixelHeight As int
    <BitmapImage DecodePixelHeight="int" />
    

    Property Value

    • int
      int
      int

      The height (in pixels) to use for image decoding operations.

  • DecodePixelHeightProperty
    DecodePixelHeightProperty
    DecodePixelHeightProperty
    DecodePixelHeightProperty

    Identifies the DecodePixelHeight dependency property.

    public static DependencyProperty DecodePixelHeightProperty { get; }public static DependencyProperty DecodePixelHeightProperty { get; }Public Static ReadOnly Property DecodePixelHeightProperty As DependencyProperty

    Property Value

  • DecodePixelType
    DecodePixelType
    DecodePixelType
    DecodePixelType

    Gets or sets a value that determines how DecodePixelWidth and DecodePixelHeight values are interpreted for decoding operations.

    public DecodePixelType DecodePixelType { get; set; }public DecodePixelType DecodePixelType { get; set; }Public ReadWrite Property DecodePixelType As DecodePixelType

    Property Value

    Remarks

    DecodePixelType can be set to Logical or Physical. The default value is Physical. If DecodePixelType is not set, or set to Physical, the image is decoded using DecodePixelWidth and DecodePixelHeight values that represent physical pixels, and the decode operation uses these values directly. If DecodePixelType is set to Logical, the image is decoded using DecodePixelWidth and DecodePixelHeight values that represent logical pixels. Internal logic converts the decode width and height based on device resolution info and how logical and physical pixels are factored on the target device.

    Width and Height for the Image element are specified in logical pixels once the image is rendered, but those logical pixels are influenced by the device resolution. For the BitmapImage element that represents the image file source, DecodePixelWidth and DecodePixelHeight are specified in physical pixels, by default. The physical pixel values for provided for the decode operation influences the size of the bitmap that's created in memory. By specifying DecodePixelType as Logical, the image is decoded using values that are pre-factored for the logical resolution, and it potentially won't use as much memory. For more info on device resolution and image sources, see UX guidelines for layout and scaling.

  • DecodePixelTypeProperty
    DecodePixelTypeProperty
    DecodePixelTypeProperty
    DecodePixelTypeProperty

    Identifies the DecodePixelType dependency property.

    public static DependencyProperty DecodePixelTypeProperty { get; }public static DependencyProperty DecodePixelTypeProperty { get; }Public Static ReadOnly Property DecodePixelTypeProperty As DependencyProperty

    Property Value

  • DecodePixelWidth
    DecodePixelWidth
    DecodePixelWidth
    DecodePixelWidth

    Gets or sets the width to use for image decoding operations.

    public int DecodePixelWidth { get; set; }public int DecodePixelWidth { get; set; }Public ReadWrite Property DecodePixelWidth As int
    <BitmapImage DecodePixelWidth="int" />
    

    Property Value

    • int
      int
      int

      The width (in pixels) to use for image decoding operations.

  • DecodePixelWidthProperty
    DecodePixelWidthProperty
    DecodePixelWidthProperty
    DecodePixelWidthProperty

    Identifies the DecodePixelWidth dependency property.

    public static DependencyProperty DecodePixelWidthProperty { get; }public static DependencyProperty DecodePixelWidthProperty { get; }Public Static ReadOnly Property DecodePixelWidthProperty As DependencyProperty

    Property Value

  • IsAnimatedBitmap
    IsAnimatedBitmap
    IsAnimatedBitmap
    IsAnimatedBitmap

    Gets a value that indicates whether an image is animated.

    public bool IsAnimatedBitmap { get; }public bool IsAnimatedBitmap { get; }Public ReadOnly Property IsAnimatedBitmap As bool

    Property Value

    • bool
      bool
      bool

      true if the image is animated; otherwise, false.

    Remarks

    Starting in Windows 10, version 1607, the XAML Image element supports animated GIF images. When you use a BitmapImage as the image Source, you can access BitmapImage API to control playback of the animated GIF image. For more info, see the 'Animated images' section of the BitmapImage class Remarks and the Animated GIF playback sample.

    Compatibility notes

    If your app runs on releases of Windows 10 prior to version 1607, you must use the ApiInformation class to check for the presence of this property before you use it. For more info, see Version adaptive code: Use new APIs while maintaining compatibility with previous versions.

    Examples

    This example shows how to use an animated GIF. A button lets the user start or stop the animation. The IsAnimatedBitmap property is checked to determine whether the button is shown or hidden.

    The example uses version adaptive code so it can run on all versions of Windows 10. On versions prior to version 1607, the first frame of the GIF is shown, but it is not animated.

    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <Image>
            <Image.Source>
                <BitmapImage x:Name="imageSource"
                             UriSource="Assets/example.gif"
                             ImageOpened="imageSource_ImageOpened"/>
            </Image.Source>
        </Image>
    
        <AppBarButton x:Name="playButton"
                  Icon="Play"
                  Visibility="Collapsed"
                  Click="playButton_Click"/>
    </Grid>
    
    
    // Show the play/stop button if the image is animated.
    private void imageSource_ImageOpened(object sender, RoutedEventArgs e)
    {
        var bitmapImage = (BitmapImage)sender;
        // At this point you can query whether the image is animated or not.
        if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "IsAnimatedBitmap") 
            && bitmapImage.IsAnimatedBitmap == true)
        {
            // Enable the play button
            playButton.Visibility = Visibility.Visible;
        }
    }
    
  • IsAnimatedBitmapProperty
    IsAnimatedBitmapProperty
    IsAnimatedBitmapProperty
    IsAnimatedBitmapProperty

    Identifies the IsAnimatedBitmap dependency property.

    public static DependencyProperty IsAnimatedBitmapProperty { get; }public static DependencyProperty IsAnimatedBitmapProperty { get; }Public Static ReadOnly Property IsAnimatedBitmapProperty As DependencyProperty

    Property Value

  • IsPlaying
    IsPlaying
    IsPlaying
    IsPlaying

    Gets a value that indicates whether an animated image is playing.

    public bool IsPlaying { get; }public bool IsPlaying { get; }Public ReadOnly Property IsPlaying As bool

    Property Value

    • bool
      bool
      bool

      true if the animated image is playing; otherwise, false.

    Remarks

    Starting in Windows 10, version 1607, the XAML Image element supports animated GIF images. When you use a BitmapImage as the image Source, you can access BitmapImage API to control playback of the animated GIF image. For more info, see the 'Animated images' section of the BitmapImage class Remarks and the Animated GIF playback sample.

    Use the IsPlaying property along with the Play() and Stop() methods to control the playback of an animated bitmap.

    Compatibility notes

    If your app runs on releases of Windows 10 prior to version 1607, you must use the ApiInformation class to check for the presence of this property before you use it. For more info, see Version adaptive code: Use new APIs while maintaining compatibility with previous versions.

    Examples

    This example shows how to use an animated GIF. A button lets the user start or stop the animation. The IsPlaying property is checked to determine whether the Play() or Stop() method is called to toggle playback.

    The example uses version adaptive code so it can run on all versions of Windows 10. On versions prior to version 1607, the first frame of the GIF is shown, but it is not animated.

    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <Image>
            <Image.Source>
                <BitmapImage x:Name="imageSource"
                             UriSource="Assets/example.gif"/>
            </Image.Source>
        </Image>
    
        <AppBarButton x:Name="playButton"
                  Icon="Play"
                  Click="playButton_Click"/>
    </Grid>
    
    
    // Play or stop the animated bitmap.
    void playButton_Click(object sender, RoutedEventArgs e)
    {
        if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "IsPlaying") 
            && imageSource.IsPlaying == true)
        {
            playButton.Icon = new SymbolIcon(Symbol.Play);
            imageSource.Stop();
        }
        else
        {
            playButton.Icon = new SymbolIcon(Symbol.Stop);
            imageSource.Play();
        }   
    }
    
  • IsPlayingProperty
    IsPlayingProperty
    IsPlayingProperty
    IsPlayingProperty

    Identifies the IsPlaying dependency property.

    public static DependencyProperty IsPlayingProperty { get; }public static DependencyProperty IsPlayingProperty { get; }Public Static ReadOnly Property IsPlayingProperty As DependencyProperty

    Property Value

  • UriSource
    UriSource
    UriSource
    UriSource

    Gets or sets the Uniform Resource Identifier (URI) of the graphics source file that generated this BitmapImage.

    public Uri UriSource { get; set; }public Uri UriSource { get; set; }Public ReadWrite Property UriSource As Uri
    <BitmapImage UriSource="uri" />
    

    Property Value

    • An object describing the Uniform Resource Identifier (URI) of the graphics source file that generated this BitmapImage.

    Remarks

    The BaseUri property might be useful for forming the URI if you're applying an image source file to a particular Image element.

    In low memory situations (most likely on lower-memory phones), it is possible for an exception to be raised with the message "The image is unrecognized" and an HRESULT of 0x88982F60. While this exception ordinarily indicates bad data, if your app is close to its memory limit then the cause of the exception is likely to be low memory. In that case, we recommend that you free memory and try again.

    Windows 8 behavior

    Windows 8 had URI validation logic associated with this property's setter. Starting with Windows 8.1 that validation on the property setter is removed. That doesn't mean you get no validation, it means that you get the same final validation you should be using anyway: handling for ImageOpened or ImageFailed events on the Image where the source is applied.

    Apps that were compiled for Windows 8 but running on Windows 8.1 use the new Windows 8.1 behavior.

  • UriSourceProperty
    UriSourceProperty
    UriSourceProperty
    UriSourceProperty

    Identifies the UriSource dependency property.

    public static DependencyProperty UriSourceProperty { get; }public static DependencyProperty UriSourceProperty { get; }Public Static ReadOnly Property UriSourceProperty As DependencyProperty

    Property Value

Methods

  • Play()
    Play()
    Play()
    Play()

    Starts the animation of an animated image.

    public void Play()public void Play()Public Function Play() As void

    Remarks

    Starting in Windows 10, version 1607, the XAML Image element supports animated GIF images. When you use a BitmapImage as the image Source, you can access BitmapImage API to control playback of the animated GIF image. For more info, see the 'Animated images' section of the BitmapImage class Remarks and the Animated GIF playback sample.

    Use the IsPlaying property along with the Play() and Stop() methods to control the playback of an animated bitmap.

    Compatibility notes

    If your app runs on releases of Windows 10 prior to version 1607, you must use the ApiInformation class to check for the presence of this method before you use it. For more info, see Version adaptive code: Use new APIs while maintaining compatibility with previous versions.

    Examples

    Here's how to use the IsMethodPresent(System.String,System.String) to check for the presence of the Play() method before you call it.

    if (ApiInformation.IsMethodPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "Play"))
    {
        imageSource.Play();
    }
    

    This example shows how to use an animated GIF. A button lets the user start or stop the animation. The IsPlaying property is checked to determine whether the Play() or Stop() method is called to toggle playback.

    The example uses version adaptive code so it can run on all versions of Windows 10. In this case, the presence of the IsPlaying property indicates that the Play() and Stop() methods are also present, so an additional API check is not needed.

    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <Image>
            <Image.Source>
                <BitmapImage x:Name="imageSource"
                             UriSource="Assets/example.gif"/>
            </Image.Source>
        </Image>
    
        <AppBarButton x:Name="playButton"
                  Icon="Play"
                  Click="playButton_Click"/>
    </Grid>
    
    
    // Play or stop the animated bitmap.
    void playButton_Click(object sender, RoutedEventArgs e)
    {
        if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "IsPlaying") 
            && imageSource.IsPlaying == true)
        {
            playButton.Icon = new SymbolIcon(Symbol.Play);
            imageSource.Stop();
        }
        else
        {
            playButton.Icon = new SymbolIcon(Symbol.Stop);
            imageSource.Play();
        }   
    }
    
  • Stop()
    Stop()
    Stop()
    Stop()

    Ends the animation of an animated image.

    public void Stop()public void Stop()Public Function Stop() As void

    Remarks

    Starting in Windows 10, version 1607, the XAML Image element supports animated GIF images. When you use a BitmapImage as the image Source, you can access BitmapImage API to control playback of the animated GIF image. For more info, see the 'Animated images' section of the BitmapImage class Remarks and the Animated GIF playback sample.

    Use the IsPlaying property along with the Play() and Stop() methods to control the playback of an animated bitmap.

    Compatibility notes

    If your app runs on releases of Windows 10 prior to version 1607, you must use the ApiInformation class to check for the presence of this method before you use it. For more info, see Version adaptive code: Use new APIs while maintaining compatibility with previous versions.

    Examples

    Here's how to use the IsMethodPresent(System.String,System.String) to check for the presence of the Stop() method before you call it.

    if (ApiInformation.IsMethodPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "Stop"))
    {
        imageSource.Stop();
    }
    

    This example shows how to use an animated GIF. A button lets the user start or stop the animation. The IsPlaying property is checked to determine whether the Play() or Stop() method is called to toggle playback.

    The example uses version adaptive code so it can run on all versions of Windows 10. In this case, the presence of the IsPlaying property indicates that the Play() and Stop() methods are also present, so an additional API check is not needed.

    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <Image>
            <Image.Source>
                <BitmapImage x:Name="imageSource"
                             UriSource="Assets/example.gif"/>
            </Image.Source>
        </Image>
    
        <AppBarButton x:Name="playButton"
                  Icon="Play"
                  Click="playButton_Click"/>
    </Grid>
    
    
    // Play or stop the animated bitmap.
    void playButton_Click(object sender, RoutedEventArgs e)
    {
        if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "IsPlaying") 
            && imageSource.IsPlaying == true)
        {
            playButton.Icon = new SymbolIcon(Symbol.Play);
            imageSource.Stop();
        }
        else
        {
            playButton.Icon = new SymbolIcon(Symbol.Stop);
            imageSource.Play();
        }   
    }
    

Events

  • DownloadProgress
    DownloadProgress
    DownloadProgress
    DownloadProgress

    Occurs when a significant change has occurred in the download progress of the BitmapImage content.

    public event DownloadProgressEventHandler DownloadProgresspublic event DownloadProgressEventHandler DownloadProgressPublic Event DownloadProgress
    <BitmapImage DownloadProgress="eventhandler"/>
    

    Remarks

    For cases where the async loading and decoding of a BitmapImage object are long enough to be noticeable to the user, an app can handle DownloadProgress on the source and display a ProgressRing or ProgressBar to indicate the progress state. These might display in the UI region that the image eventually displays in, or somewhere else in the UI. Use Progress to modify the UI for a ProgressBar.

    Examples

    
    // somewhere in initialization
    bitmapImage.DownloadProgress += new EventHandler<DownloadProgressEventArgs>(bi_DownloadProgress);
    bitmapImage.ImageOpened += new EventHandler<ExceptionRoutedEventArgs>(bi_ImageOpened);
    ...
    //progressBar is an existing control defined in XAML or extracted from a XAML template
    
    void bi_DownloadProgress(object sender, DownloadProgressEventArgs e)
    {
         progressBar.Value = e.Progress;
    }
    void bi_ImageOpened(object sender, RoutedEventArgs e)
    {
         progressBar.Visibility = Visibility.Collapsed;
    }
    
  • ImageFailed
    ImageFailed
    ImageFailed
    ImageFailed

    Occurs when there is an error associated with image retrieval or format.

    public event ExceptionRoutedEventHandler ImageFailedpublic event ExceptionRoutedEventHandler ImageFailedPublic Event ImageFailed
    <BitmapImage ImageFailed="eventhandler"/>
    

    Remarks

    One scenario for handling ImageFailed is to set the UriSource to a different local image file that can serve as a fallback value. For example, if you are trying to display an external image where it's possible that the source is no longer there, or for when the user has no Internet connection, you could set the UriSource to reference a local fallback or placeholder image that's part of your app package and is always guaranteed to be available.

    private void BitmapImage_ImageFailed(object sender, ExceptionRoutedEventArgs e) {
        BitmapImage bitmapImage = sender as BitmapImage;
        bitmapImage.UriSource = new Uri("ms-appx:///Images/fallback.png");
    }
    
  • ImageOpened
    ImageOpened
    ImageOpened
    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.

    public event RoutedEventHandler ImageOpenedpublic event RoutedEventHandler ImageOpenedPublic Event ImageOpened
    <BitmapImage ImageOpened="eventhandler"/>
    

    Remarks

    When ImageOpened fires, that serves as the notification that any asynchronous operations have completed and all the properties of a BitmapImage are ready for use. For example, to determine the size of the image before rendering it, handle ImageOpened, and check the value of the PixelWidth and PixelHeight properties on the BitmapImage that fired the event. The event data for the ImageOpened event isn't typically useful.

    The SurfaceImageSource class also has an ImageOpened event (as does ImageBrush ). For the other ImageOpened events, these fire at a time when the image has probably already rendered. The ImageOpened fires at a time that is potentially before you've assigned your BitmapImage to be the source of an BitmapImage or ImageBrush. If you want to change properties that affect rendering of the image based on reading properties of the BitmapImage, it's often best to handle the underlying BitmapImage 's event prior to assigning it as a source.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ThreadingAttribute

Details

Assembly

Windows.UI.Xaml.Media.Imaging.dll