Skip to end of metadata
Go to start of metadata

Remarks

ImageLoader is an innovative control that supports loading for embedded, internal and external image. The ImageLoader provides built-in features to show the image loading progress, which can be optionally disabled or further customized through property sets.

By default, ImageLoader automatically loads the image specified in ImageSource property when the page is loaded. If you do not want to load the image directly, you can set the AutoLoad property to False. You can programmatically load the image in code by using LoadImage() API.

The following examples show how to use the ImageLoader control using XAML and code.

XAML
C#

Working with LoadImage() Method

By default, ImageLoader automatically loads the image specified in ImageSource property when the page is loaded. If you do not want to load the image directly, you can set the AutoLoad property to False. You can programmatically load the image in code by using LoadImage() API.

Working with DefaultImageSource Property and UseDefaultImage Property

When an image is being loaded, a progresss bar is displayed to show the download progress in real-time. In some scenarios, you may want to display an image along with the progress bar to enhance the user interface. This scenario can be achieved by using the default image feature, which is shown along with the image. The default image works in conjunction with the progress bar.

To enable this default image, you set the UseDefaultImage property to True, and then set the DefaultImageSource property to an image source. It is recommended to use an image within your project rather than an external image for a better user experience.

XAML

Working with DisplayLoader Property

To hide the progress bar, you set the DisplayLoader property to False. This might be useful for certain scenarios where using default image alone is more appealing.

XAML

Working with TargetDisplay Property

This is an advanced feature of ImageLoader where you can redirect the image loaded by ImageLoader to another Image element or an ImageBrush.

A typical scenario that makes sense to use this approach is when you want to load an external image and apply it to the Background of a UIElement, for example a Border or a Grid, and at the same time showing the download progress indicator which is more compelling to users.

XAML

Working with UseAnimation Property

When an image is loaded, the built-in animation will fade out the progress bar along with the default image and fade in the actual image. This animation delivers a smooth user experience particularly when you load an image from external source. You can also disable this feature if necessary by setting the UseAnimation property to False.

XAML

Definition

public class ImageLoader : ISControl

Summary

The following table summarizes the members exposed in this class.

Public Constructors

ImageLoader Constructor()Initializes a new instance of the ImageLoader class.

Public Properties

AutoLoadGets or sets a value that determines whether the image should be automatically downloaded when the object is registered into visual tree.
AutoSyncPerspectiveReflectionGets or sets a value that determines whether image loader should auto synch image source to content perspective reflection.
BackgroundNot applicable.
BorderBrushNot applicable.
BorderThicknessNot applicable.
CustomLoaderContainerName 
DefaultImageSourceGets or sets the loader default image source.
DisplayLoaderGets or sets a value that determines whether the download progress / loader should be shown.
EnableHighlightAnimationGets or set a value that determines whether progress highlight animation is enabled.
FadeInStoryboardGets the fade in animation.
FadeOutStoryboardGets the fade out animation.
HorizontalContentAlignmentNot applicable.
ImageSourceGets or sets the image source.
ImageStretchGets or sets the strech mode of the image element.
IsImageLoadedGets a value that indicates whether the image has been loaded or not.
LoaderStyleGets or sets the progress bar style.
ParentContentPerspectiveGets parent content reflective.
ParentContentReflectorGets parent content reflector.
ProgressBarHorizontalAlignmentGets or sets the horizontal alignment of progress bar element.
ProgressBarMarginGets or sets the margin of progress bar element.
ProgressBarVerticalAlignmentGets or sets the vertical alignment of progress bar element.
ProgressTextGets or sets text format of progress bar element.
ProgressTextVisibilityGets or sets the visibility of progress bar text.
RootElementGets the root element.
TargetDisplayGets or sets the target element that will be loaded with the image source.
TransitionModeGets or sets the transition mode.
UseAnimationGets or sets a value that determine whether transition animation should be used.
UseAnimationOnParentGets or sets a value that determine whether transition animation at parent level (ContentReflector and ContentPerspective) should be used.
UseDefaultImageGets or sets a value that determine whether the default loader image should be used.
UseLoaderGets or sets a value that determine whether the loader should b used. Turning this property off will make the imagesource assigned directly to the image element, thus eliminating the download progress mechanism.
VerticalContentAlignmentNot applicable.

Protected Properties

ProductProduct Info.

Fields

AutoLoadPropertyIdentifies the AutoLoad dependency property.
AutoSyncPerspectiveReflectionPropertyIdentifies the AutoLoad dependency property.
CustomLoaderContainerNameProperty 
DefaultImageSourcePropertyIdentifies the DefaultImageSource dependency property.
DisplayLoaderPropertyIdentifies the DisplayLoader dependency property.
EnableHighlightAnimationPropertyIdentifies the EnableHighlightAnimation dependency property.
ImageDownloadProgressEventIdentifies the ImageDownloadProgress routed event.
ImageFailedEventIdentifies the ImageFailed routed event.
ImageOpenedEventIdentifies the ImageOpened routed event.
ImageSourcePropertyIdentifies the ImageSource dependency property.
ImageStretchPropertyIdentifies the ImageStretch dependency property.
LoaderStylePropertyIdentifies the ProgressBarMargin dependency property.
ProgressBarHorizontalAlignmentPropertyIdentifies the ProgressBarHorizontalAlignment dependency property.
ProgressBarMarginPropertyIdentifies the ProgressBarMargin dependency property.
ProgressBarVerticalAlignmentPropertyIdentifies the ProgressBarVerticalAlignment dependency property.
ProgressTextPropertyIdentifies the ProgressText dependency property.
ProgressTextVisibilityPropertyIdentifies the ProgressTextVisibility dependency property.
TargetDisplayPropertyIdentifies the TargetDisplay dependency property.
TransitionModePropertyIdentifies the TransitionMode dependency property.
UseAnimationOnParentPropertyIdentifies the UseAnimationOnParent dependency property.
UseAnimationPropertyIdentifies the UseAnimation dependency property.
UseDefaultImagePropertyIdentifies the UseDefaultImage dependency property.
UseLoaderPropertyIdentifies the UseLoader dependency property.

Public Methods

AttachEventHandlers()Attach built-in event handlers to control templates. Call this method if necessary.
DetachedEventHandlers()Detach built-in event handlers from control templates. Call this method if necessary.
HideLoader()Hide the progress bar / loader element.
InitializeStoryboards()Initializes storyboards.
InitializeTemplates()Initializes control templates.
LoadImage()Load the image specified in imagesource.
OnApplyTemplate()Builds the visual tree for the ImageLoader when a new template is applied.
RefreshReflection()Refresh content reflector or content prespective that host Image Loader.
ResumeReflectionLayout()Resume reflection layout.
ShowLoader()Show the progress bar / loader element.
SuspendReflectionLayout()Suspend reflection layout.

Protected Methods

Events

ImageDownloadProgressOccurs when image download is in progress.
ImageFailedOccurs when image download is failed.
ImageOpenedOccurs when image is opened.

Public Constructors

public ImageLoader()

Initializes a new instance of the ImageLoader class.

Public Properties

public bool AutoLoad { get; set; }

Gets or sets a value that determines whether the image should be automatically downloaded when the object is registered into visual tree.

public bool AutoSyncPerspectiveReflection { get; set; }

Gets or sets a value that determines whether image loader should auto synch image source to content perspective reflection.

public Brush Background { get; set; }

Not applicable.

public Brush BorderBrush { get; set; }

Not applicable.

public Thickness BorderThickness { get; set; }

Not applicable.

public string CustomLoaderContainerName { get; set; }

 

public ImageSource DefaultImageSource { get; set; }

Gets or sets the loader default image source.

public bool DisplayLoader { get; set; }

Gets or sets a value that determines whether the download progress / loader should be shown.

public bool EnableHighlightAnimation { get; set; }

Gets or set a value that determines whether progress highlight animation is enabled.

public Storyboard FadeInStoryboard { get; }

Gets the fade in animation.

public Storyboard FadeOutStoryboard { get; }

Gets the fade out animation.

public HorizontalAlignment HorizontalContentAlignment { get; set; }

Not applicable.

public ImageSource ImageSource { get; set; }

Gets or sets the image source.

public Stretch ImageStretch { get; set; }

Gets or sets the strech mode of the image element.

public bool IsImageLoaded { get; }

Gets a value that indicates whether the image has been loaded or not.

public Style LoaderStyle { get; set; }

Gets or sets the progress bar style.

public ContentPerspective ParentContentPerspective { get; }

Gets parent content reflective.

public ContentReflector ParentContentReflector { get; }

Gets parent content reflector.

public HorizontalAlignment ProgressBarHorizontalAlignment { get; set; }

Gets or sets the horizontal alignment of progress bar element.

public Thickness ProgressBarMargin { get; set; }

Gets or sets the margin of progress bar element.

public VerticalAlignment ProgressBarVerticalAlignment { get; set; }

Gets or sets the vertical alignment of progress bar element.

public string ProgressText { get; set; }

Gets or sets text format of progress bar element.

public Visibility ProgressTextVisibility { get; set; }

Gets or sets the visibility of progress bar text.

public Grid RootElement { get; }

Gets the root element.

public DependencyObject TargetDisplay { get; set; }

Gets or sets the target element that will be loaded with the image source.

Remarks

Specifing the target display will make the loader to load the image into the specified value.

 

public ImageTransitionMode TransitionMode { get; set; }

Gets or sets the transition mode.

public bool UseAnimation { get; set; }

Gets or sets a value that determine whether transition animation should be used.

public bool UseAnimationOnParent { get; set; }

Gets or sets a value that determine whether transition animation at parent level (ContentReflector and ContentPerspective) should be used.

public bool UseDefaultImage { get; set; }

Gets or sets a value that determine whether the default loader image should be used.

public bool UseLoader { get; set; }

Gets or sets a value that determine whether the loader should b used. Turning this property off will make the imagesource assigned directly to the image element, thus eliminating the download progress mechanism.

public VerticalAlignment VerticalContentAlignment { get; set; }

Not applicable.

Protected Properties

protected ProductInfo Product { get; }

Product Info.

Fields

public static readonly DependencyProperty AutoLoadProperty

Identifies the AutoLoad dependency property.

public static readonly DependencyProperty AutoSyncPerspectiveReflectionProperty

Identifies the AutoLoad dependency property.

public static readonly DependencyProperty CustomLoaderContainerNameProperty

 

public static readonly DependencyProperty DefaultImageSourceProperty

Identifies the DefaultImageSource dependency property.

public static readonly DependencyProperty DisplayLoaderProperty

Identifies the DisplayLoader dependency property.

public static readonly DependencyProperty EnableHighlightAnimationProperty

Identifies the EnableHighlightAnimation dependency property.

public static readonly RoutedEvent ImageDownloadProgressEvent

Identifies the ImageDownloadProgress routed event.

public static readonly RoutedEvent ImageFailedEvent

Identifies the ImageFailed routed event.

public static readonly RoutedEvent ImageOpenedEvent

Identifies the ImageOpened routed event.

public static readonly DependencyProperty ImageSourceProperty

Identifies the ImageSource dependency property.

public static readonly DependencyProperty ImageStretchProperty

Identifies the ImageStretch dependency property.

public static readonly DependencyProperty LoaderStyleProperty

Identifies the ProgressBarMargin dependency property.

public static readonly DependencyProperty ProgressBarHorizontalAlignmentProperty

Identifies the ProgressBarHorizontalAlignment dependency property.

public static readonly DependencyProperty ProgressBarMarginProperty

Identifies the ProgressBarMargin dependency property.

public static readonly DependencyProperty ProgressBarVerticalAlignmentProperty

Identifies the ProgressBarVerticalAlignment dependency property.

public static readonly DependencyProperty ProgressTextProperty

Identifies the ProgressText dependency property.

public static readonly DependencyProperty ProgressTextVisibilityProperty

Identifies the ProgressTextVisibility dependency property.

public static readonly DependencyProperty TargetDisplayProperty

Identifies the TargetDisplay dependency property.

public static readonly DependencyProperty TransitionModeProperty

Identifies the TransitionMode dependency property.

public static readonly DependencyProperty UseAnimationOnParentProperty

Identifies the UseAnimationOnParent dependency property.

public static readonly DependencyProperty UseAnimationProperty

Identifies the UseAnimation dependency property.

public static readonly DependencyProperty UseDefaultImageProperty

Identifies the UseDefaultImage dependency property.

public static readonly DependencyProperty UseLoaderProperty

Identifies the UseLoader dependency property.

Public Methods

public void AttachEventHandlers()

Attach built-in event handlers to control templates. Call this method if necessary.

public void DetachedEventHandlers()

Detach built-in event handlers from control templates. Call this method if necessary.

public void HideLoader()

Hide the progress bar / loader element.

public void InitializeStoryboards()

Initializes storyboards.

public void InitializeTemplates()

Initializes control templates.

public void LoadImage()

Load the image specified in imagesource.

public void OnApplyTemplate()

Builds the visual tree for the ImageLoader when a new template is applied.

public void RefreshReflection()

Refresh content reflector or content prespective that host Image Loader.

public void ResumeReflectionLayout()

Resume reflection layout.

public void ShowLoader()

Show the progress bar / loader element.

public void SuspendReflectionLayout()

Suspend reflection layout.

Protected Methods

protected void GoToHideLoaderState(bool animate)

 

Parameters

animate 

 

protected void GoToShowLoaderState(bool animate)

 

Parameters

animate 

 

Events

public event DownloadProgressRoutedEventHandler ImageDownloadProgress

Occurs when image download is in progress.

public event ExceptionRoutedEventHandler ImageFailed

Occurs when image download is failed.

public event ISRoutedEventHandler ImageOpened

Occurs when image is opened.

  • No labels