How to use the Feathers ImageLoader component

The ImageLoader class wraps starling.display.Image inside a Feathers component to add additional features. For instance, you can easily load an image from a URL and automatically convert it to a texture that is fully managed by the ImageLoader. The texture will be disposed when the ImageLoader is disposed. A number of other useful properties have been added to ImageLoader. See below for more details.

The Basics

First, let's create an ImageLoader control, pass in a texture to display, and add it to the display list:

var loader:ImageLoader = new ImageLoader();
loader.source = texture;
this.addChild( loader );

Alternatively, you can pass a URL to the source property to load an external image:

loader.source = "http://www.example.com/image.png";

The URL may point to any image file that may be loaded by flash.display.Loader to create a flash.display.BitmapData object. The loaded image will be converted to a starling.textures.Texture.

Events

You can listen for Event.COMPLETE to know when the image is fully loaded:

loader.addEventListener( Event.COMPLETE, loader_completeHandler );

The listener might look like this:

function loader_completeHandler( event:Event ):void
{
    // image loaded and texture ready
}

You can also listen for errors to know if the ImageLoader is unable to load the texture:

loader.addEventListener( FeathersEventType.ERROR, loader_errorHandler );

The listener for FeathersEventType.ERROR might look like this:

function loader_errorHandler( event:Event, data:ErrorEvent ):void
{
    // loader error
}

The data parameter in the function signature is optional, as always. It is a flash.events.ErrorEvent that is dispatched by the internal flash.display.Loader used internally by the ImageLoader. It may be of type IOErrorEvent.IO_ERROR or of type SecurityErrorEvent.SECURITY_ERROR.

Other Properties

You can snap the position of an ImageLoader to the nearest whole pixel using the snapToPixels property:

loader.snapToPixels = true;

Pixel snapping is most useful for icons where crisp edges are especially important.

When images are loaded in a component like a List, it's often more desirable to avoid creating new textures on the GPU while the list is scrolling. Since texture uploads are expensive, this keeps the list feeling smooth and responsive.

loader.delayTextureCreation = true;

Set the delayTextureCreation property to true when the container starts scrolling and set it back to false after scrolling finishes. While this property is true, the image may load from a URL, but the BitmapData will be kept in memory without being converted to a texture on the GPU. Once the property is set back to false, the texture will be created immediately.

If desired, we can set the textureQueueDuration property to a specific number of seconds. When delayTextureCreation is true, the loaded image will be converted to a Texture after a short delay instead of waiting for delayTextureCreation to be set back to false.

When you resize a regular starling.display.Image, it may distort. ImageLoader allows you control whether the image maintains its aspect ratio within the dimensions of the ImageLoader:

loader.maintainAspectRatio = true;

When the maintainAspectRatio property is true, the image may be letter-boxed inside the ImageLoader, adding transparent edges on the top and bottom or on the left and right.

You can use the isLoaded getter to know if a texture is fully loaded (in addition to listening for Event.COMPLETE, mentioned above):

if( loader.isLoaded )
{
    // ready
}
else
{
    // not loaded
}

You can scale the original dimensions of the loaded texture:

loader.textureScale = 0.5;

This value is mainly used when the ImageLoader needs to resize after loading a new source. The original width and height of the loaded texture are multiplied by the textureScale and that's the width and height of the ImageLoader.

Finally, just like starling.display.Image, ImageLoader allows you to customize the color and smoothing properties:

loader.color = 0xff0000;
loader.smoothing = TextureSmoothing.NONE;