ImageProvider Class

public class ImageProvider

public ImageProvider()

public ImageChromaticAdaptationMode ChromaticAdaptationMode { get; set; }

Property Value

ImageChromaticAdaptationMode:

An ImageChromaticAdaptationMode indicating the chromatic adaptation (color shifting) mode to apply to images. The default value is Never.

Remarks

Chromatic adaptation is the process of taking an image designed for a light theme and dynamically creating a variation of it that renders clearly on a specified background color, sometimes adjusting the brightness and hue as needed. This feature is useful when wanting to have a single set of original images that can be adjusted at run-time to render well in dark themes. This feature should not be used if ThemeNames are used, where specific images are supplied for alternate themes like dark themes. This value should be set prior to UI being loaded.

public static ImageProvider Default { get; set; }

Property Value

ImageProvider:

The default ImageProvider instance.

public Color? DesignForegroundColor { get; set; }

Property Value

Color?:

A Color used in images that when specified, can be swapped out with a Color specified in ForegroundColor.

Remarks

This property should generally only be specified when using monochrome vector icons. Specifying a value allows images to switch their foreground dynamically based on a containing control's state (normal, highlighted, etc.). This is necessary when the foreground of the containing control changes drastically and requires an image's foreground to also change to retain a proper contrast ratio.

public byte MonochromeBrightnessThreshold { get; set; }

Property Value

byte

Remarks

Pixels with brightness at or above this threshold will be made transparent. Pixels with brightness below this threshold will be made a single color, specified in ForegroundColor. Set this value to 0 to prevent monochrome image variations from being supported. This value should be set prior to UI being loaded.

public IList<double> Scales { get; }

Property Value

IList<double>:

The collection of high-DPI (non-100%) scales (e.g. 2.0 means 200% DPI) supported by raster images using this provider.

Remarks

Do not add 1.0 to this collection since it is the default scale. Add a 2.0 entry to tell the ImageProvider that there are specific high-DPI 200% scale variations of all raster images using this provider available. This value should be set prior to UI being loaded.

See Also

• GetScalePathPath(double)
• TransformBaseImageUriSource(Uri?, ImageProviderRequest)

public IList<string> ThemeNames { get; }

Property Value

IList<string>:

The collection of non-default theme names supported by raster images using this provider.

Remarks

As an example, if the default application theme name is "Light" then exclude "Light" from this collection. Non-suffixed images will be used for any themes not in this collection. Add a "Dark" entry to tell the ImageProvider that there are specific "Dark" theme variations of all raster images using this provider available. This feature should not be used if ChromaticAdaptationMode is enabled. This value should be set prior to UI being loaded.

See Also

• GetThemeNamePathPart(string?)
• TransformBaseImageUriSource(Uri?, ImageProviderRequest)

public bool UseMonochromeInHighContrast { get; set; }

Property Value

bool:

true if requests should use monochrome images in high-contrast themes; otherwise, false. The default value is false.

protected virtual Color AdaptColor(Color color, ImageProviderRequest? request)

Parameter	Type	Description
color	Color	The Color to adapt.
request	ImageProviderRequest	An ImageProviderRequest that contains request information.

Returns

Color:

The adapted color.

protected virtual double FindBestScale(double targetScale)

Parameter	Type	Description
targetScale	double	The target scale.

Returns

double:

The best scale value to use, which by default is the same or next-highest scale value in the supported Scales collection. A scale value of 1.0 is returned if the Scales collection is empty.

See Also

• Scales

public static bool GetCanAdapt(DependencyObject obj)

Parameter	Type	Description
obj	DependencyObject	The object from which the property value is read.

Returns

bool:

The object's value.

public static Color? GetColorFromBrush(Brush? brush)

Parameter	Type	Description
brush	Brush	The Brush to examine.

Returns

Color?:

The Color associated with the specified Brush.

public virtual ImageSource? GetImageSource(string key)

Parameter	Type	Description
key	string	The key which identifies the image.

Returns

ImageSource:

The ImageSource identified by the key; or null if an ImageSource could not be identified.

See Also

• SharedImageSourceKeys

public virtual ImageSource? GetImageSource(string key, ImageProviderRequest request)

Parameter	Type	Description
key	string	The key which identifies the image.
request	ImageProviderRequest	An ImageProviderRequest that contains request information.

Returns

ImageSource:

The same or alternate variation of the ImageSource identified by the key; or null if an ImageSource could not be identified.

See Also

• SharedImageSourceKeys

public virtual ImageSource? GetImageSource(ImageSource originalImageSource, ImageProviderRequest request)

Parameter	Type	Description
originalImageSource	ImageSource	The ImageSource to examine.
request	ImageProviderRequest	An ImageProviderRequest that contains request information.

Returns

ImageSource:

The same or alternate variation of the specified ImageSource.

public static ImageSource GetImageSourceWithColorSwatch(ImageSource originalImageSource, Rect swatchBounds, Color color)

Parameter	Type	Description
originalImageSource	ImageSource	The ImageSource under which to render a color swatch.
swatchBounds	Rect	The color swatch bounds, relative to the originalImageSource's bounds.
color	Color	The Color to render in the swatch.

Returns

ImageSource:

The ImageSource that was created.

public static ImageProvider GetProvider(DependencyObject obj)

Parameter	Type	Description
obj	DependencyObject	The object from which the property value is read.

Returns

ImageProvider:

The object's value.

protected virtual string GetScalePathPath(double scale)

Parameter	Type	Description
scale	double	The scale to examine.

Returns

string:

The scale-oriented path part that was generated.

Remarks

This method is called by TransformBaseImageUriSource(Uri?, ImageProviderRequest) to assist in building the System.Uri for locating a scale-oriented variant of an image. The default implementation of this method returns an empty string if the scale value is 1.0 or is not within the Scales collection. If the scale is found within the collection, a string such as "Scale-200" would be returned for a scale 2.0.

See Also

• Scales
• TransformBaseImageUriSource(Uri?, ImageProviderRequest)

protected virtual string GetThemeNamePathPart(string? themeName)

Parameter	Type	Description
themeName	string	The theme name to examine.

Returns

string:

The theme name-oriented path part that was generated.

Remarks

This method is called by TransformBaseImageUriSource(Uri?, ImageProviderRequest) to assist in building the System.Uri for locating a theme name-oriented variant of an image. The default implementation of this method returns an empty string if the themeName value is not within the ThemeNames collection. If the themeName is found within the collection, a string such as "Theme-Dark" would be returned for a theme name "Dark". Note that spaces in the theme name are removed.

See Also

• ThemeNames
• TransformBaseImageUriSource(Uri?, ImageProviderRequest)

protected virtual bool HasThemeVariation(string? themeName)

Parameter	Type	Description
themeName	string	The theme name to examine.

Returns

bool:

true if the provider has any raster image variations for the specified theme name; otherwise, false.

public static void SetCanAdapt(DependencyObject obj, bool value)

Parameter	Type	Description
obj	DependencyObject	The object to which the attached property is written.
value	bool	The value to set.

public static void SetProvider(DependencyObject obj, ImageProvider value)

Parameter	Type	Description
obj	DependencyObject	The object to which the attached property is written.
value	ImageProvider	The value to set.

protected virtual Uri? TransformBaseImageUriSource(Uri? uriSource, ImageProviderRequest request)

Parameter	Type	Description
uriSource	Uri	The System.Uri source for the raster image.
request	ImageProviderRequest	An ImageProviderRequest that contains request information.

Returns

Uri:

The same System.Uri source, or a different one if a variation should be used.

public static readonly DependencyProperty CanAdaptProperty

public static readonly DependencyProperty ProviderProperty