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;