Skip to content

Xamarin.Forms API

Jump to bottom Edit New page
Louis Haußknecht edited this page Jun 17, 2016 · 23 revisions

FFImageLoading for Forms provides CachedImage - a direct Image class replacement. It’s used just the same but it has some additional properties.

Important

You must add this line to your platform specific project (AppDelegate.cs, MainActivity.cs, etc) before you use FFImageLoading:

CachedImageRenderer.Init();

Basic Example

C#

var cachedImage = new CachedImage() {
	HorizontalOptions = LayoutOptions.Center,
	VerticalOptions = LayoutOptions.Center,
	WidthRequest = 300,
	HeightRequest = 300,
	CacheDuration = TimeSpan.FromDays(30),
	DownsampleToViewSize = true,
	RetryCount = 0,
	RetryDelay = 250,
	TransparencyEnabled = false,
	LoadingPlaceholder = "loading.png",
	ErrorPlaceholder = "error.png",
	Source = "http://loremflickr.com/600/600/nature?filename=simple.jpg"
};
## XAML 
<?xml version="1.0" encoding="UTF-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms" xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml" 
	x:Class="FFImageLoading.Forms.Sample.Pages.XamlSimpleExamplePage"
	xmlns:ffimageloading="clr-namespace:FFImageLoading.Forms;assembly=FFImageLoading.Forms"
    Title="Basic XAML Example">
	<ContentPage.Content>
		<ffimageloading:CachedImage HorizontalOptions="Center" VerticalOptions="Center"
			WidthRequest="300" HeightRequest="300"
			DownsampleToViewSize="true"
			Source = "http://loremflickr.com/600/600/nature?filename=simple.jpg">
		</ffimageloading:CachedImage>
	</ContentPage.Content>
</PFContentPage>

Properties

Image Sources properties

Source

ImageSource property. It supports UriImageSource, FileImageSource and StreamImageSource. # LoadingPlaceholder ImageSource property. If set, a loading placeholder is shown while loading. It supports UriImageSource, FileImageSource and StreamImageSource. # ErrorPlaceholder ImageSource property. If set, if error occurs while loading image, an error placeholder is shown. It supports UriImageSource, FileImageSource and StreamImageSource. Image downloading properties # RetryCount (int, default: 3) If image download failed, or something wrong happened, it can be automatically retried. Defines retries count. # RetryDelay (int, default: 250) If image download failed, or something wrong happened, it can be automatically retried. Defines retry delay. # CacheDuration (Timespan `, default: `TimeSpan.FromDays(90)) Defines how long file cache of downloaded image is valid. ## Downsampling properties

DownSample always maintain original image aspect ratio. If you set both DownsampleWidth and DownsampleHeight, one of them is ignored.

DownsampleWidth (int, default: 0)

Resizes image to defined width in pixels (or DIP if DownsampleUseDipUnits property is set to true. If you set this property don’t set DownsampleHeight as aspect ratio will be maintained. # DownsampleHeight (int, default: 0) Resizes image to defined height in pixels (or DIP if DownsampleUseDipUnits property is set to true. If you set this property don’t set DownsampleWidth ` as aspect ratio will be maintained. # DownsampleUseDipUnits (`bool, default: false) If set to true, DownsampleWidth and DownsampleHeight properties will use DIP units (device independent points). # DownsampleToViewSize (bool, default: false) If set to true image will resize to an image view size. Please note: this could not work on some layouts (eg. absolute layouts without RequestWidth/RequestWidthHeight specified, LayoutOptions.Start, etc). Algorithm for choosing size: First View.Width/View.Height is checked, if it’s ⇐ 0 it falls back to: View.RequestWidth/View.RequestHeight, if it’s ⇐ 0 it falls back to using DownsampleWidth/DownsampleHeight properties. It’s not the best option for image views that have no initial size defined. For that you should use DownsampleWidth or DownsampleHeight properties and set your downsample size manually. Transformations properties # Transformations (List<ITransformation>, default: null)

Images can be transformed when loading (original files won’t be modified). To use predefined transformations, just add FFImageLoading.Transformations package to your projects.

Example:

This transformation will transform source image to grayscale, circle-cropped image
var cachedImage = new CachedImage() {
	HorizontalOptions = LayoutOptions.FillAndExpand,
	VerticalOptions = LayoutOptions.FillAndExpand,
	DownsampleToViewSize = true,
	LoadingPlaceholder = "loading.png",
	ErrorPlaceholder = "error.png",
	Transformations = new System.Collections.Generic.List<ITransformation>() {
		new GrayscaleTransformation(),
		new CircleTransformation(),
	},
	Source = "http://loremflickr.com/600/600/nature?filename=simple.jpg"
};
# This transformation will transform source image to grayscale 
<?xml version="1.0" encoding="UTF-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms" xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml" 
	x:Class="FFImageLoading.Forms.Sample.Pages.XamlSimpleExamplePage"
	xmlns:ffimageloading="clr-namespace:FFImageLoading.Forms;assembly=FFImageLoading.Forms"
	xmlns:fftransformations="clr-namespace:FFImageLoading.Transformations;assembly=FFImageLoading.Transformations"
    Title="Basic XAML Example">
	<ContentPage.Content>
		<ffimageloading:CachedImage HorizontalOptions="Center" VerticalOptions="Center"
			WidthRequest="300" HeightRequest="300"
			DownsampleToViewSize="true"
			Source = "http://loremflickr.com/600/600/nature?filename=simple.jpg">
			<ffimageloading:CachedImage.Transformations>
				<fftransformations:GrayscaleTransformation />
			</ffimageloading:CachedImage.Transformations>
		</ffimageloading:CachedImage>
	</ContentPage.Content>
</ContentPage>

TransformPlaceholders (bool?, default: null)'

Indicates if transforms should be applied to placeholders. By default this value comes from ImageService.Instance.Config.TransformPlaceholders

Other properties

TransparencyEnabled (bool?, default: null)

On Android transparency is disabled by default. This feature is not yet implemented on iOS or Windows Phone. Transparency causes images to consume twice more memory. With this property you can enable transparency for a view. Please note: Some transformations force transparency (like CircleTransformation) even when this option is disabled. # FadeAnimationEnabled (bool?, default: null) Sets if fade animation on image loading should be enabled or disabled. # CacheKeyFactory Gets or sets the cache custom key factory. More here: [Custom cache keys](https://github.com/molinch/FFImageLoading/wiki/Xamarin.Forms-Advanced#custom-cache-keys)

Methods

Instance methods

Cancel()

Cancels image loading. # GetImageAsJpgAsync(int quality = 90, int desiredWidth = 0, int desiredHeight = 0) Gets the currently visible image as JPG byte array. # GetImageAsPngAsync(int desiredWidth = 0, int desiredHeight = 0) Gets the currently visible image as PNG byte array.

Clear cache

Single item

For a single item some static methods exists directly on CachedImage.

Using name (string)

CachedImage.InvalidateCache(string key, Cache.CacheType cacheType, bool removeSimilar = false)
Clears the cache for a specified entry (Memory, Disk, All). Could be an url or filename / file path. If removeSimilar is set to true then it also removes all image cache variants ## Using an ImageSource 
CachedImage.InvalidateCache(ImageSource source, Cache.CacheType cacheType, bool removeSimilar = false)
Same but with an ImageSource.

Multiple items

For multiple items please read ImageService section: https://github.com/luberda-molinet/FFImageLoading/wiki/Advanced-Usage#clear-cache

Events

Success

Occurs after every image loading success. Returns: original ImageSize, LoadingResult # Error Occurs after every image loading error. Returns: Exception # Finish Occurs after every image loading. Returns: IScheduledWork

nice

Add a custom sidebar

Clone this wiki locally