SvgImageSource
SvgImageSource
SvgImageSource
SvgImageSource
Class
Definition
Provides a source object for properties that use a Scalable Vector Graphics (SVG) source. You can define a SvgImageSource by using a Uniform Resource Identifier (URI) that references a SVG file, or by calling SetSourceAsync(IRandomAccessStream) and supplying a stream.
public : class SvgImageSource : ImageSource, ISvgImageSourcepublic class SvgImageSource : ImageSource, ISvgImageSourcePublic Class SvgImageSource Inherits ImageSource Implements ISvgImageSource// This API is not available in Javascript.
- Inheritance
-
SvgImageSourceSvgImageSourceSvgImageSourceSvgImageSource
- Attributes
| Device family |
Windows 10 Creators Update (introduced v10.0.15063.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v4)
|
Inherited Members
Inherited methods
Inherited properties
Remarks
Remarks
SvgImageSource lets you use a SVG source to be displayed using an ImageBrush or directly in an Image control. SvgImageSource supports secure static mode from the SVG specification and does not support animations or interactions. The Direct2D API supplies the underlying SVG rendering support and for more info on specific SVG element and attribute support, see SVG Support. 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 SvgImageSource represents an abstraction so that a SVG 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 SvgImageSource object in code, it initially has no valid source. You should then set its source using one of these techniques:
- Use the SvgImageSource(Uri) constructor rather than the default constructor. Although it's a constructor, you can think of this as having an implicit asynchronous behavior: the SvgImageSource(svgimagesource.md) won't be ready for use until it raises an Opened event that indicates a successful async source set operation.
- Set the UriSource property. As with the Uri constructor, this action is implicitly asynchronous, and the SvgImageSource won't be ready for use until it raises an Opened event.
- Use SetSourceAsync(IRandomAccessStream). This method is explicitly asynchronous. The properties where you might use a SvgImageSource, such as Source, are designed for this asynchronous behavior, and won't throw exceptions if they are set using a SvgImageSource that doesn't have a complete source yet. Rather than handling exceptions, you should handle Opened or OpenFailed events either on the SvgImageSource directly or on the control that uses the source (if those events are available on the control class).
Opened and OpenFailed are mutually exclusive. One event or the other will always be raised whenever a SvgImageSource object has its source value set or reset.
Sizing
Depending on your intended use case, you can specify the size of a SvgImageSource in several different ways:
- Use the RasterizePixelHeight and RasterizePixelWidth properties to specify an explicit height and width in logical pixels to decode the SVG source at.
- If you don't specify a RasterizePixelHeight or RasterizePixelWidth, then the application's layout will dictate the decode size while still preserving aspect ratio. If no size can be determined from the application's layout, then the SVG source will be decoded to the maximum window size.
Version compatibility
The SvgImageSource class is not available prior to Windows 10, version 1703. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you will not be able to use SvgImageSource. For more info, see Version adaptive code.
To avoid exceptions when your app runs on previous versions of Windows 10, do not set this property in XAML or use it without performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this class before you use it.
Examples
Here's an example of how to set the source of an Image to a SVG file. Since there is no height or width explicitly specified, the application layout will dictate the appropriate size for the SVG to decode at.
<Image Source="Assets/mysvg.svg"/>
Constructors
SvgImageSource() SvgImageSource() SvgImageSource() SvgImageSource()
Initializes a new instance of the SvgImageSource class.
public : SvgImageSource()public SvgImageSource()Public Sub New()// This API is not available in Javascript.
SvgImageSource(Uri) SvgImageSource(Uri) SvgImageSource(Uri) SvgImageSource(Uri)
Initializes a new instance of the SvgImageSource class, using the supplied Uniform Resource Identifier (URI).
public : SvgImageSource(Uri uriSource)public SvgImageSource(Uri uriSource)Public Sub New(uriSource As Uri)// This API is not available in Javascript.
- uriSource
- Uri Uri Uri Uri
A reference to the SVG source file.
Properties
RasterizePixelHeight RasterizePixelHeight RasterizePixelHeight RasterizePixelHeight
Gets or sets the height to use for SVG rasterization operations.
public : double RasterizePixelHeight { get; set; }public double RasterizePixelHeight { get; set; }Public ReadWrite Property RasterizePixelHeight As double// This API is not available in Javascript.
<SvgImageSource RasterizePixelHeight="double"/>
- Value
- double double double double
The height (in logical pixels) to use for SVG decoding operations. The default is Double.NaN.
Remarks
Since the units are logical pixels, the SVG is decoded using values that are pre-factored for the logical resolution, and it potentially won't use as much memory.
If RasterizePixelHeight and RasterizePixelWidth aren't explicitly set, then the application's layout will determine the decode size so that the SvgImageSource fits in the available space.
RasterizePixelHeightProperty RasterizePixelHeightProperty RasterizePixelHeightProperty RasterizePixelHeightProperty
Identifies the RasterizePixelHeight dependency property.
public : static DependencyProperty RasterizePixelHeightProperty { get; }public static DependencyProperty RasterizePixelHeightProperty { get; }Public Static ReadOnly Property RasterizePixelHeightProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the RasterizePixelHeight dependency property.
RasterizePixelWidth RasterizePixelWidth RasterizePixelWidth RasterizePixelWidth
Gets or sets the width to use for SVG rasterization operations.
public : double RasterizePixelWidth { get; set; }public double RasterizePixelWidth { get; set; }Public ReadWrite Property RasterizePixelWidth As double// This API is not available in Javascript.
<SvgImageSource RasterizePixelWidth="double"/>
- Value
- double double double double
The width (in logical pixels) to use for SVG decoding operations. The default is Double.NaN.
Remarks
Since the units are logical pixels, the SVG is decoded using values that are pre-factored for the logical resolution, and it potentially won't use as much memory.
If RasterizePixelHeight and RasterizePixelWidth aren't explicitly set, then the application's layout will determine the decode size so that the SvgImageSource fits in the available space.
RasterizePixelWidthProperty RasterizePixelWidthProperty RasterizePixelWidthProperty RasterizePixelWidthProperty
Identifies the RasterizePixelWidth dependency property.
public : static DependencyProperty RasterizePixelWidthProperty { get; }public static DependencyProperty RasterizePixelWidthProperty { get; }Public Static ReadOnly Property RasterizePixelWidthProperty As DependencyProperty// This API is not available in Javascript.
The identifier for the RasterizePixelWidth dependency property.
UriSource UriSource UriSource UriSource
Gets or sets the Uniform Resource Identifier (URI) of the SVG source file that generated this SvgImageSource.
public : Uri UriSource { get; set; }public Uri UriSource { get; set; }Public ReadWrite Property UriSource As Uri// This API is not available in Javascript.
<SvgImageSource UriSource="uri" />
- Value
- Uri Uri Uri Uri
An object describing the Uniform Resource Identifier (URI) of the SVG source file that generated this SvgImageSource.
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// This API is not available in Javascript.
The identifier for the UriSource dependency property.
Methods
SetSourceAsync(IRandomAccessStream) SetSourceAsync(IRandomAccessStream) SetSourceAsync(IRandomAccessStream) SetSourceAsync(IRandomAccessStream)
Sets the source SVG for a SvgImageSource by accessing a stream and processing the result asynchronously.
public : IAsyncOperation<SvgImageSourceLoadStatus> SetSourceAsync(IRandomAccessStream streamSource)public IAsyncOperation<SvgImageSourceLoadStatus> SetSourceAsync(IRandomAccessStream streamSource)Public Function SetSourceAsync(streamSource As IRandomAccessStream) As IAsyncOperation( Of SvgImageSourceLoadStatus )// This API is not available in Javascript.
The stream source that sets the SVG source value.
A SvgImageSourceLoadStatus value that indicates whether the operation was successful. If it failed, indicates the reason for the failure.
Examples
This example shown here uses a file stream (obtained using a file picker, not shown) to load an image source by calling SetSourceAsync(IRandomAccessStream). The file picker, stream and call to SetSourceAsync(IRandomAccessStream) are all asynchronous.
// Ensure the stream is disposed once the SVG is loaded
using (IRandomAccessStream fileStream = await file.OpenAsync(Windows.Storage.FileAccessMode.Read))
{
// Set the SVG source to the selected file
SvgImageSource svgImage = new SvgImageSource();
await svgImage.SetSourceAsync(fileStream);
Scenario2Image.Source = svgImage;
}
Remarks
Setting a SVG source by calling the asynchronous SetSourceAsync(IRandomAccessStream) method avoids blocking the UI thread. For more info on how to use async or await, see Call asynchronous APIs in C# or Visual Basic. If the app changes the SVG source again via SetSourceAsync(IRandomAccessStream) or UriSource while a SetSourceAsync(IRandomAccessStream) call is already in progress, the pending SetSourceAsync(IRandomAccessStream) action will throw a TaskCanceledException.
Events
Opened Opened Opened Opened
Occurs when the SVG source is downloaded and decoded with no failure.
public : event TypedEventHandler Opened<SvgImageSource, SvgImageSourceOpenedEventArgs>public event TypedEventHandler Opened<SvgImageSource, SvgImageSourceOpenedEventArgs>Public Event Opened<SvgImageSource, SvgImageSourceOpenedEventArgs>// This API is not available in Javascript.
<SvgImageSource Opened="eventhandler"/>
Remarks
When the Opened event occurs, it serves as the notification that any asynchronous operations have completed and all the properties of an SvgImageSource are ready for use.
OpenFailed OpenFailed OpenFailed OpenFailed
Occurs when there is an error associated with SVG retrieval or format.
public : event TypedEventHandler OpenFailed<SvgImageSource, SvgImageSourceFailedEventArgs>public event TypedEventHandler OpenFailed<SvgImageSource, SvgImageSourceFailedEventArgs>Public Event OpenFailed<SvgImageSource, SvgImageSourceFailedEventArgs>// This API is not available in Javascript.
<SvgImageSource OpenFailed="eventhandler"/>
Remarks
You can use the OpenFailed event to determine why the SVG didn't load correctly by checking the SvgImageSourceFailedEventArgs, which contain error information in the Status property. One scenario for handling OpenFailed is to set the UriSource to a different local SVG source file that can serve as a fallback value. For example, if you are trying to display an external image where it's possible that either the source is no longer there, the user has no Internet connection, or the SVG source is not in the correct format, you could set the UriSource to reference a local fallback or placeholder SVG that's part of your app package and is always guaranteed to be available.
private void SvgImageSource_OpenFailed(SvgImageSource sender, SvgImageSourceFailedEventArgs args) {
if(args.Status != SvgImageSourceLoadStatus.Success) {
sender.UriSource = new Uri("ms-appx:///Assets/fallback.svg");
}
}