API Documentation | All Packages | All Classes | Index | Frames | |
Class ImageLoader | Properties | Methods | Events | |
Package | com.greensock.loading |
Class | public class ImageLoader |
Inheritance | ImageLoader DisplayObjectLoader LoaderItem LoaderCore flash.events.EventDispatcher |
content
refers to a ContentDisplay
(Sprite) that
is created immediately so that you can position/scale/rotate it or add ROLL_OVER/ROLL_OUT/CLICK listeners
before (or while) the image loads. Use the ImageLoader's content
property to get the ContentDisplay
Sprite, or use the rawContent
property to get the actual Bitmap. If a container
is defined in the vars
object, the ContentDisplay will immediately be added to that container). width
and height
, it will draw a rectangle
in the ContentDisplay so that interactive events fire appropriately (rollovers, etc.) and width/height/bounds
get reported accurately. This rectangle is invisible by default, but you can control its color and alpha
with the bgColor
and bgAlpha
properties. When the image loads, it will be
added to the ContentDisplay at index 0 with addChildAt()
and scaled to fit the width/height
according to the scaleMode
. These are all optional features - you do not need to define a
width
or height
in which case the image will load at its native size.
See the list below for all the special properties that can be passed through the vars
parameter but don't let the list overwhelm you - these are all optional and they are intended to make
your job as a developer much easier.LoaderEvent.SCRIPT_ACCESS_DENIED
event will be dispatched and the scriptAccessDenied
property of the ImageLoader will be set to true
. You can check this value before performing any restricted operations on the content like BitmapData.draw().rawContent
property will be a Loader
instance instead of a Bitmap.smoothing
property will not be set to true
.AllowScriptAccess
to "always"
vars
parameter which can be either a generic object or an ImageLoaderVars
object:LoaderMax.getLoader()
or LoaderMax.getContent()
methods or traced at any time. Each loader's name should be unique. If you don't define one, a unique name will be created automatically, like "loader21".ContentDisplay
Sprite should be added immediately.smoothing
is true
(the default), smoothing will be enabled for the image which typically leads to much better scaling results (otherwise the image can look crunchy/jagged). If your image is loaded from another domain where the appropriate crossdomain.xml file doesn't grant permission, Flash will not allow smoothing to be enabled (it's a security restriction).ContentDisplay
's width
property (applied before rotation, scaleX, and scaleY).ContentDisplay
's height
property (applied before rotation, scaleX, and scaleY).true
, the registration point will be placed in the center of the ContentDisplay which can be useful if, for example, you want to animate its scale and have it grow/shrink from its center.width
and height
are defined, the scaleMode
controls how the loaded image will be scaled to fit the area. The following values are recognized (you may use the com.greensock.layout.ScaleMode
constants if you prefer):
"stretch"
(the default) - The image will fill the width/height exactly."proportionalInside"
- The image will be scaled proportionally to fit inside the area defined by the width/height"proportionalOutside"
- The image will be scaled proportionally to completely fill the area, allowing portions of it to exceed the bounds defined by the width/height."widthOnly"
- Only the width of the image will be adjusted to fit."heightOnly"
- Only the height of the image will be adjusted to fit."none"
- No scaling of the image will occur.width
and height
is defined, the hAlign
determines how the image is horizontally aligned within that area. The following values are recognized (you may use the com.greensock.layout.AlignMode
constants if you prefer):
"center"
(the default) - The image will be centered horizontally in the area"left"
- The image will be aligned with the left side of the area"right"
- The image will be aligned with the right side of the areawidth
and height
is defined, the vAlign
determines how the image is vertically aligned within that area. The following values are recognized (you may use the com.greensock.layout.AlignMode
constants if you prefer):
"center"
(the default) - The image will be centered vertically in the area"top"
- The image will be aligned with the top of the area"bottom"
- The image will be aligned with the bottom of the areawidth
and height
are defined, setting crop
to true
will cause the image to be cropped within that area (by applying a scrollRect
for maximum performance). This is typically useful when the scaleMode
is "proportionalOutside"
or "none"
so that any parts of the image that exceed the dimensions defined by width
and height
are visually chopped off. Use the hAlign
and vAlign
special properties to control the vertical and horizontal alignment within the cropped area.ContentDisplay
's x
property (for positioning on the stage).ContentDisplay
's y
property (for positioning on the stage).ContentDisplay
's scaleX
property.ContentDisplay
's scaleY
property.ContentDisplay
's rotation
property.ContentDisplay
's alpha
property.ContentDisplay
's visible
property.ContentDisplay
's blendMode
property.width
and height
are defined, a rectangle will be drawn inside the ContentDisplay
Sprite immediately in order to ease the development process. It is transparent by default, but you may define a bgAlpha
if you prefer.width
and height
are defined.LoaderContext
object. By default, the policy file will be checked when running remotely, so make sure the appropriate crossdomain.xml file is in place. See Adobe's LoaderContext
documentation for details and precautions. bytesTotal
is set to the estimatedBytes
value (or LoaderMax.defaultEstimatedBytes
if one isn't defined). Then, when the loader begins loading and it can accurately determine the bytesTotal, it will do so. Setting estimatedBytes
is optional, but the more accurate the value, the more accurate your loaders' overall progress will be initially. If the loader will be inserted into a LoaderMax instance (for queue management), its auditSize
feature can attempt to automatically determine the bytesTotal
at runtime (there is a slight performance penalty for this, however - see LoaderMax's documentation for details).alternateURL
, the loader will initially try to load from its original url
and if it fails, it will automatically (and permanently) change the loader's url
to the alternateURL
and try again. Think of it as a fallback or backup url
. It is perfectly acceptable to use the same alternateURL
for multiple loaders (maybe a default image for various ImageLoaders for example).true
, a "cacheBusterID" parameter will be appended to the url with a random set of numbers to prevent caching (don't worry, this info is ignored when you LoaderMax.getLoader()
or LoaderMax.getContent()
by url
or when you're running locally)requireWithRoot
property to your swf's root
. For example, var loader:ImageLoader = new ImageLoader("photo1.jpg", {name:"image1", requireWithRoot:this.root});
autoDispose
is true
, the loader will be disposed immediately after it completes (it calls the dispose()
method internally after dispatching its COMPLETE
event). This will remove any listeners that were defined in the vars object (like onComplete, onProgress, onError, onInit). Once a loader is disposed, it can no longer be found with LoaderMax.getLoader()
or LoaderMax.getContent()
- it is essentially destroyed but its content is not unloaded (you must call unload()
or dispose(true)
to unload its content). The default autoDispose
value is false
.
LoaderEvent.OPEN
events which are dispatched when the loader begins loading. Make sure your onOpen function accepts a single parameter of type LoaderEvent
(com.greensock.events.LoaderEvent
).LoaderEvent.INIT
events which are called when the image has downloaded and has been placed into the ContentDisplay Sprite. Make sure your onInit function accepts a single parameter of type LoaderEvent
(com.greensock.events.LoaderEvent
).LoaderEvent.PROGRESS
events which are dispatched whenever the bytesLoaded
changes. Make sure your onProgress function accepts a single parameter of type LoaderEvent
(com.greensock.events.LoaderEvent
). You can use the LoaderEvent's target.progress
to get the loader's progress value or use its target.bytesLoaded
and target.bytesTotal
.LoaderEvent.COMPLETE
events which are dispatched when the loader has finished loading successfully. Make sure your onComplete function accepts a single parameter of type LoaderEvent
(com.greensock.events.LoaderEvent
).LoaderEvent.CANCEL
events which are dispatched when loading is aborted due to either a failure or because another loader was prioritized or cancel()
was manually called. Make sure your onCancel function accepts a single parameter of type LoaderEvent
(com.greensock.events.LoaderEvent
).LoaderEvent.ERROR
events which are dispatched whenever the loader experiences an error (typically an IO_ERROR or SECURITY_ERROR). An error doesn't necessarily mean the loader failed, however - to listen for when a loader fails, use the onFail
special property. Make sure your onError function accepts a single parameter of type LoaderEvent
(com.greensock.events.LoaderEvent
).LoaderEvent.FAIL
events which are dispatched whenever the loader fails and its status
changes to LoaderStatus.FAILED
. Make sure your onFail function accepts a single parameter of type LoaderEvent
(com.greensock.events.LoaderEvent
).LoaderEvent.IO_ERROR
events which will also call the onError handler, so you can use that as more of a catch-all whereas onIOError
is specifically for LoaderEvent.IO_ERROR events. Make sure your onIOError function accepts a single parameter of type LoaderEvent
(com.greensock.events.LoaderEvent
).LoaderEvent.HTTP_STATUS
events. Make sure your onHTTPStatus function accepts a single parameter of type LoaderEvent
(com.greensock.events.LoaderEvent
). You can determine the httpStatus code using the LoaderEvent's target.httpStatus
(LoaderItems keep track of their httpStatus
when possible, although certain environments prevent Flash from getting httpStatus information).LoaderEvent.SECURITY_ERROR
events which onError handles as well, so you can use that as more of a catch-all whereas onSecurityError is specifically for SECURITY_ERROR events. Make sure your onSecurityError function accepts a single parameter of type LoaderEvent
(com.greensock.events.LoaderEvent
).LoaderEvent.SCRIPT_ACCESS_DENIED
events which are dispatched when the image is loaded from another domain and no crossdomain.xml is in place to grant full script access for things like smoothing or BitmapData manipulation. You can also check the loader's scriptAccessDenied
property after the image has loaded. Make sure your function accepts a single parameter of type LoaderEvent
(com.greensock.events.LoaderEvent
).ImageLoaderVars
instance
instead of a generic object to define your vars
is a bit more verbose but provides
code hinting and improved debugging because it enforces strict data typing. Use whichever one you prefer.pixelSnapping
is "auto"
when their scaleX/scaleY are 1.content
data type: com.greensock.loading.display.ContentDisplay
(a Sprite).
When the image has finished loading, the rawContent
will be added to the ContentDisplay
Sprite
at index 0 using addChildAt()
. rawContent
will be a flash.display.Bitmap
unless
unless script access is denied in which case it will be a flash.display.Loader
(to avoid security errors).import com.greensock.*; import com.greensock.events.LoaderEvent; import com.greensock.loading.*; //create an ImageLoader: var loader:ImageLoader = new ImageLoader("img/photo1.jpg", {name:"photo1", container:this, x:180, y:100, width:200, height:150, scaleMode:"proportionalInside", centerRegistration:true, onComplete:onImageLoad}); //begin loading loader.load(); //when the image loads, fade it in from alpha:0 using TweenLite function onImageLoad(event:LoaderEvent):void { TweenLite.from(event.target.content, 1, {alpha:0}); } //Or you could put the ImageLoader into a LoaderMax. Create one first... var queue:LoaderMax = new LoaderMax({name:"mainQueue", onProgress:progressHandler, onComplete:completeHandler, onError:errorHandler}); //append the ImageLoader and several other loaders queue.append( loader ); queue.append( new XMLLoader("xml/doc.xml", {name:"xmlDoc", estimatedBytes:425}) ); queue.append( new SWFLoader("swf/main.swf", {name:"mainClip", estimatedBytes:3000, container:this, autoPlay:false}) ); //start loading queue.load(); function progressHandler(event:LoaderEvent):void { trace("progress: " + queue.progress); } function completeHandler(event:LoaderEvent):void { trace(event.target + " is complete!"); } function errorHandler(event:LoaderEvent):void { trace("error occured with " + event.target + ": " + event.text); }
container
special property (see above).See also
Method | Defined by | ||
---|---|---|---|
ImageLoader(urlOrRequest:*, vars:Object = null)
Constructor
| ImageLoader | ||
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
| LoaderCore | ||
auditSize():void
Attempts loading just enough of the content to accurately determine the
bytesTotal
in order to improve the accuracy of the progress property. | LoaderItem | ||
cancel():void
If the loader is currently loading (
status is LoaderStatus.LOADING ), it will be canceled
immediately and its status will change to LoaderStatus.READY . | LoaderCore | ||
dispose(flushContent:Boolean = false):void
Disposes of the loader and releases it internally for garbage collection.
| LoaderCore | ||
load(flushContent:Boolean = false):void
Loads the loader's content, optionally flushing any previously loaded content first.
| LoaderCore | ||
pause():void
Pauses the loader immediately.
| LoaderCore | ||
prioritize(loadNow:Boolean = true):void
Immediately prioritizes the loader inside any LoaderMax instances that contain it,
forcing it to the top position in their queue and optionally calls
load()
immediately as well. | LoaderCore | ||
resume():void
Unpauses the loader and resumes loading immediately.
| LoaderCore | ||
toString():String
Returns information about the loader, like its type, its
name , and its url (if it has one). | LoaderCore | ||
unload():void
Removes any content that was loaded and sets
bytesLoaded back to zero. | LoaderCore |
ImageLoader | () | constructor |
public function ImageLoader(urlOrRequest:*, vars:Object = null)
Constructor
ParametersurlOrRequest:* — The url (String ) or URLRequest from which the loader should get its content
|
|
vars:Object (default = null ) — An object containing optional configuration details. For example: new ImageLoader("img/photo1.jpg", {name:"photo1", container:this, x:100, y:50, alpha:0, onComplete:completeHandler, onProgress:progressHandler}) .The following special properties can be passed into the constructor via the vars parameter
which can be either a generic object or an ImageLoaderVars object:
|
See also