Loader

Kind of class:	class
Inherits from:	Dispatcher
Author:	Arthur Clemens, Martijn de Visser (rewritten for EventDispatcher usage and added check for already loaded data)
Classpath:	org.asapframework.util.loader.Loader
File last modified:	Monday, 09 October 2006, 15:26:50

► View source

▼ Hide source

    /*
Copyright 2005-2006 by the authors of asapframework, http://asapframework.org

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

// ASAP classes
import org.asapframework.events.Dispatcher;
import org.asapframework.util.debug.Log;
import org.asapframework.util.loader.FileData;
import org.asapframework.util.loader.LoaderEvent;
import org.asapframework.util.loader.LoaderWorker;
import org.asapframework.util.loader.LoaderWorkerEvent;
import org.asapframework.util.FrameDelay;

/**
Loads SWF movies or JPEG images into a clip. Multiple/subsequent movies that are added are queued. Loader can deal with multiple loading threads simultaneously (but the real life efficiency is dependent on the capability of the browser).
@author Arthur Clemens, Martijn de Visser (rewritten for EventDispatcher usage and added check for already loaded data)
@see LoaderWorker
@example
Example to load multiple images:
<code>
var loader:Loader = new Loader();
</code>
Listen for feedback during loading:
<code>
loader.addEventListener(LoaderEvent.ON_PROGRESS, this);
loader.addEventListener(LoaderEvent.ON_DONE, this);
</code>
Load the assets. We will make them invisible first, and turn them visible once they are loaded:
<code>
loader.load( movieholder1_mc, "seaside.jpg", "Seaside", false );
loader.load( movieholder2_mc, "tree.jpg", "Woods", false );
</code>
To keep track of loading progress, implement the listener method - we will update a progress bar with the incoming data:
<code>
private function onLoadProgress (e:LoaderEvent) : Void {
    progressbar._xscale = 100 / e.total * e.loaded;
}
</code>
And the method that is called when each asset has finished loading:
<code>
private function onLoadDone (e:LoaderEvent) : Void {
    trace(e.name + " is loaded");
    e.targetClip._visible = true; // or use {@link ActionQueue ActionQueue} to fade in the clip
}
</code>
We could also have implemented {@link LoaderEvent#ON_ALL_LOADED} to find out when everything is done.
*/

class org.asapframework.util.loader.Loader extends Dispatcher {

    private var STATE_NONE:Number = 0;
    private var STATE_LOADING:Number = 1;
    private var STATE_PAUSED:Number = 2;
    
    private var mWorkerCount:Number = 4; /**< The number of LoaderWorker objects that will be doing loading work simultaneously. */
    private var mFileQueue:Array;        /**< Array of {@link FileData} objects. */
    private var mCurrentLoadList:Array;    /**< Array of {@link FileData} objects that are currently being loaded. */
    private var mWorkers:Array;            /**< Array of {@link LoaderWorker} objects. */
    private var mLoadingState:Number;    /**< Loading state of the Loader. */


    
    /**
    @param inThreadCount (optional) The number of threads the Loader should be using. Default (when left empty) is 4. This means that (theoretically) 4 files will be loaded at once. The actual number that Flash uses is dependent on the browser. When the number of threads is 1, the next file will only be loaded when the first is done loading.
    */
    public function Loader (inThreadCount:Number) {

        super();
        mLoadingState = STATE_NONE;
        
        if (inThreadCount > 0) {
            mWorkerCount = inThreadCount;
        }
        mFileQueue = new Array();
        mCurrentLoadList = new Array();
        mWorkers = new Array();
        for (var i:Number = 0; i<mWorkerCount; ++i) {
            var worker:LoaderWorker = new LoaderWorker(i);            
            worker.addEventListener(LoaderWorkerEvent.ON_PROGRESS, this);
            worker.addEventListener(LoaderWorkerEvent.ON_ERROR, this);
            worker.addEventListener(LoaderWorkerEvent.ON_DONE, this);            
            mWorkers.push(worker);
        }
    }

    /**
    Adds a file to the load queue. The file will be ordered to load as soon as one of the loader workers is idle. Supported file types are: swf, jpg
    @param loc : Movieclip in where the file should be loaded
    @param url : File's url or disk location
    @param name : (optional) Unique identifying name for the loading request
    @param isVisible : (optional) The visible state of the movieclip once the file is loaded; if not specified, visible = true is assumed
    @return Error state; false if an error occurred, true if successfully added to the queue
    */
    public function load (inLoc:MovieClip, inUrl:String, inName:String, inIsVisible:Boolean) : Boolean {
        // Error checking
        // check if location is valid
        if (inLoc == undefined) {
            Log.error("load; location is not valid", toString());
            return false;
        }
        // Check if url is valid
        if (inUrl.length == 0) {
            Log.error("load; url is not valid", toString());
            return false;
        }
        // check for formal validity of url
        var urlComponents:Array = inUrl.split(".");
        if (urlComponents.length <= 1) {
            Log.error("load; filename is wrong: '" + inUrl + "'", toString());
            return false;
        }
        var isVisible:Boolean = (inIsVisible != undefined) ? inIsVisible : true;
        var fileData:FileData = new FileData(inLoc, inUrl, inName, isVisible);
        mFileQueue.push(fileData);
        // start loading the file one frame later
        var fd:FrameDelay = new FrameDelay(this, getNextInQueue);
        // return start loading succesful
        return true;
    }
    
    /**
    
    */
    public function getFileCount () : Number {
        return mFileQueue.length;
    }

    /**
    Stops the loading of one file.
    @param name : Name of the loading request as passed with {@link #load}
    */
    public function stopLoading (inName:String) : Void {
        stopLoadingWorkers(inName);
    }

    /**
    Stops the loading of all files, clears the loading queue and frees the loader workers.
    */
    public function stopAllLoading () : Void {
        stopLoadingWorkers();
        delete mFileQueue;
        mFileQueue = new Array();
    }
    
    /**
    Stops the loading of all files until resumeAllLoading is called.
    */
    public function pauseAllLoading () : Void {
        stopLoadingWorkers();
        mLoadingState = STATE_PAUSED;
    }
    
    /**
    Stops the loading of all files until resumeAllLoading is called.
    */
    public function resumeAllLoading () : Void {
        getNextInQueue();
    }
    
    /**
    The Loader's loading state.
    @return True when one of the workers is still loading, false when all workers have finished.
    */
    public function isLoading () : Boolean {
        return mLoadingState == STATE_LOADING;
    }
    
    /**
    Calculates the total number of bytes loading and loaded of all workers.
    @return A value object {total:Number, loaded:Number}.
    */
    public function getTotalAndLoaded () : Object {
        var totalAndLoaded:Object = {total:0, loaded:0};
        var i:Number, len:Number = mWorkers.length;
        for (i=0; i<len; ++i) {
            var worker:LoaderWorker = LoaderWorker(mWorkers[i]);
            if (worker.loading) {
                var data:FileData = worker.loadingData;
                var dataTotal:Number = data.bytesTotal;
                if (dataTotal != undefined) totalAndLoaded.total += dataTotal;
                var dataLoaded:Number = data.bytesLoaded;
                if (dataLoaded != undefined) totalAndLoaded.loaded += dataLoaded; 
            }
        }
        return totalAndLoaded;
    }

    /**
    *
    */
    public function toString () : String {
        return "; org.asapframework.util.loader.Loader";
    }
    
    /**
    @sends LoaderEvent#ON_ALL_LOADED When no more assets are in the queue
    @sends LoaderEvent#ON_START When a new LoaderWorker starts loading
    */
    private function getNextInQueue () : Void {

        updateLoadingState();
        
        if (mFileQueue.length == 0) {
            if (!isLoading()) {
                dispatchEvent(new LoaderEvent(LoaderEvent.ON_ALL_LOADED, this));                
            }
            return;
        }

        // Not done yet, so get next free Worker
        var i:Number, len:Number = mWorkers.length;
        for (i=0; i<len; ++i) {
            var worker:LoaderWorker = LoaderWorker(mWorkers[i]);
            if (!worker.loading) {
                // get the first item
                var fileData:FileData = FileData(mFileQueue.shift());
                mCurrentLoadList.push(fileData);
                worker.load(fileData);
                mLoadingState = STATE_LOADING;
                dispatchEvent(new LoaderEvent(LoaderEvent.ON_START, this, fileData.name, 0, 0));
                break;
            }
        }

    }
    
    /**
    Updates the loading state; sets mLoadingState to true if one of the workers is loading; to false if all loader workers are free.
    */
    private function updateLoadingState () : Void {
        if (mLoadingState == STATE_PAUSED) {
            return;
        }
        if (mCurrentLoadList.length > 0) {
            mLoadingState = STATE_LOADING;
        } else {
            mLoadingState = STATE_NONE;
        }
    }

    /**
    Monitors the loading progress of one LoaderWorker object. This event is passed on to listeners of the Loader.
    @param e: event object with properties: .name, .type, .target
    @sends LoaderEvent#ON_PROGRESS When some data has been received
    */
    private function onWorkerLoadProgress (e:LoaderWorkerEvent) : Void {
        // calculate the total amount of data of all workers,
        // then send this information out
        var totalAndLoaded:Object = getTotalAndLoaded();
        dispatchEvent(new LoaderEvent(LoaderEvent.ON_PROGRESS, this, e.name, e.targetClip, totalAndLoaded.total, totalAndLoaded.loaded));
    }

    /**
    Received when a LoaderWorker object is finished or stopped loading. This event is passed on to listeners of the Loader.
    @param e: event object with properties: .name, .type, .target
    @sends LoaderEvent#ON_DONE When one asset has finished loading
    @implementationNote Calls {@link #getTotalAndLoaded}.
    */
    private function onWorkerLoadDone (e:LoaderWorkerEvent) : Void {

        var totalAndLoaded:Object = getTotalAndLoaded();
        dispatchEvent(new LoaderEvent(LoaderEvent.ON_DONE, this, e.name, e.targetClip, totalAndLoaded.total, totalAndLoaded.loaded));
        removeFromCurrentlyLoading(e.target.loadingData);
        getNextInQueue();
    }

    /**
    Received when a LoaderWorker object encounters an error during loading. This event is passed on to listeners of the Loader.
    @param e: event object with properties: .name, .target
    @sends LoaderEvent#ON_ERROR When an error happened during loading
    */
    private function onWorkerLoadError (e:LoaderWorkerEvent) : Void {
        
        // dispatch onLoadError event
        dispatchEvent(new LoaderEvent(LoaderEvent.ON_ERROR, this, e.name, e.targetClip));
    }
    
    /**
    Stops all workers loading.
    @param name : (optional) name of the loading request as passed with {@link #load}; if name is passed only the worker with that loading request name will be stopped; otherwise all workers will be stopped
    */
    private function stopLoadingWorkers (inName:String) : Void {
        var i:Number, len:Number = mWorkers.length;
        for (i=0; i<len; ++i) {
            var worker:LoaderWorker = LoaderWorker(mWorkers[i]);
            if (worker.loading) {
                if (inName != undefined) {
                    if (worker.loadingData.name == inName) {
                        worker.stopLoading();
                    }
                } else {
                    worker.stopLoading();
                }
            }
        }
    }
    
    /**
    Removes a FileData object from mCurrentLoadList.
    @param inFileData: object to remove
    */
    private function removeFromCurrentlyLoading (inFileData:FileData) : Void {
        var i:Number, ilen:Number = mCurrentLoadList.length;
        for (i=0; i<ilen; ++i) {
            if (mCurrentLoadList[i] == inFileData) {
                mCurrentLoadList.splice(i,1);
            }
        }
    }
    
    
}

Loads SWF movies or JPEG images into a clip. Multiple/subsequent movies that are added are queued. Loader can deal with multiple loading threads simultaneously (but the real life efficiency is dependent on the capability of the browser).

Summary

Constructor

Loader (inThreadCount:Number)

Instance properties

STATE_NONE : Number
STATE_LOADING : Number
STATE_PAUSED : Number
mWorkerCount : Number
- The number of LoaderWorker objects that will be doing loading work simultaneously.
mFileQueue : Array
- Array of FileData objects.
mCurrentLoadList : Array
- Array of FileData objects that are currently being loaded.
mWorkers : Array
- Array of LoaderWorker objects.
mLoadingState : Number
- Loading state of the Loader.

Instance properties inherited from Dispatcher

addEventListener dispatchEvent removeEventListener

Instance methods

load (inLoc:MovieClip, inUrl:String, inName:String, inIsVisible:Boolean) : Boolean
- Adds a file to the load queue.
getFileCount : Number
stopLoading (inName:String) : Void
- Stops the loading of one file.
stopAllLoading : Void
- Stops the loading of all files, clears the loading queue and frees the loader workers.
pauseAllLoading : Void
- Stops the loading of all files until resumeAllLoading is called.
resumeAllLoading : Void
- Stops the loading of all files until resumeAllLoading is called.
isLoading : Boolean
- The Loader's loading state.
getTotalAndLoaded : Object
- Calculates the total number of bytes loading and loaded of all workers.
toString : String
getNextInQueue : Void
updateLoadingState : Void
- Updates the loading state; sets mLoadingState to true if one of the workers is loading; to false if all loader workers are free.
stopLoadingWorkers (inName:String) : Void
- Stops all workers loading.
removeFromCurrentlyLoading (inFileData:FileData) : Void
- Removes a FileData object from mCurrentLoadList.

Event handlers

onWorkerLoadProgress (e:LoaderWorkerEvent) : Void
- Monitors the loading progress of one LoaderWorker object.
onWorkerLoadDone (e:LoaderWorkerEvent) : Void
- Received when a LoaderWorker object is finished or stopped loading.
onWorkerLoadError (e:LoaderWorkerEvent) : Void
- Received when a LoaderWorker object encounters an error during loading.

Constructor

Loader

function Loader (

inThreadCount:Number)

Parameters:

inThreadCount:

(optional) The number of threads the Loader should be using. Default (when left empty) is 4. This means that (theoretically) 4 files will be loaded at once. The actual number that Flash uses is dependent on the browser. When the number of threads is 1, the next file will only be loaded when the first is done loading.

Instance properties

mCurrentLoadList

private mCurrentLoadList:Array

(read)

Array of FileData objects that are currently being loaded.

mFileQueue

private mFileQueue:Array

(read)

Array of FileData objects.

mLoadingState

private mLoadingState:Number

(read)

Loading state of the Loader.

mWorkerCount

private mWorkerCount:Number = 4

(read)

The number of LoaderWorker objects that will be doing loading work simultaneously.

mWorkers

private mWorkers:Array

(read)

Array of LoaderWorker objects.

STATE_LOADING

private STATE_LOADING:Number = 1

(read)

STATE_NONE

private STATE_NONE:Number = 0

(read)

STATE_PAUSED

private STATE_PAUSED:Number = 2

(read)

Instance methods

getFileCount

function getFileCount (

) : Number

getNextInQueue

private function getNextInQueue (

) : Void

Events broadcasted to listeners:

LoaderEvent with type: ON_ALL_LOADED When no more assets are in the queue
- (null)
LoaderEvent with type: ON_START When a new LoaderWorker starts loading
- (null)

getTotalAndLoaded

function getTotalAndLoaded (

) : Object

Calculates the total number of bytes loading and loaded of all workers.

Returns:

A value object {total:Number, loaded:Number}.

isLoading

function isLoading (

) : Boolean

The Loader's loading state.

Returns:

True when one of the workers is still loading, false when all workers have finished.

load

function load (

inLoc:MovieClip, inUrl:String, inName:String, inIsVisible:Boolean) : Boolean

Adds a file to the load queue. The file will be ordered to load as soon as one of the loader workers is idle. Supported file types are: swf, jpg

Parameters:

loc :

Movieclip in where the file should be loaded

url :

File's url or disk location

name :

(optional) Unique identifying name for the loading request

isVisible:

(optional) The visible state of the movieclip once the file is loaded; if not specified, visible = true is assumed

Returns:

Error state; false if an error occurred, true if successfully added to the queue

pauseAllLoading

function pauseAllLoading (

) : Void

Stops the loading of all files until resumeAllLoading is called.

removeFromCurrentlyLoading

private function removeFromCurrentlyLoading (

inFileData:FileData) : Void

Removes a FileData object from mCurrentLoadList.

Parameters:

inFileData:

object to remove

resumeAllLoading

function resumeAllLoading (

) : Void

Stops the loading of all files until resumeAllLoading is called.

stopAllLoading

function stopAllLoading (

) : Void

Stops the loading of all files, clears the loading queue and frees the loader workers.

stopLoading

function stopLoading (

inName:String) : Void

Stops the loading of one file.

Parameters:

name:

Name of the loading request as passed with load

stopLoadingWorkers

private function stopLoadingWorkers (

inName:String) : Void

Stops all workers loading.

Parameters:

name:

(optional) name of the loading request as passed with load; if name is passed only the worker with that loading request name will be stopped; otherwise all workers will be stopped

toString

function toString (

) : String

updateLoadingState

private function updateLoadingState (

) : Void

Updates the loading state; sets mLoadingState to true if one of the workers is loading; to false if all loader workers are free.

Event handlers

onWorkerLoadDone

private function onWorkerLoadDone (

e:LoaderWorkerEvent) : Void

Received when a LoaderWorker object is finished or stopped loading. This event is passed on to listeners of the Loader.

Parameters:

event object with properties: .name, .type, .target

Events broadcasted to listeners:

LoaderEvent with type: ON_DONE When one asset has finished loading
- (null)

Implementation note:

Calls getTotalAndLoaded.

onWorkerLoadError

private function onWorkerLoadError (

e:LoaderWorkerEvent) : Void

Received when a LoaderWorker object encounters an error during loading. This event is passed on to listeners of the Loader.

Parameters:

event object with properties: .name, .target

Events broadcasted to listeners:

LoaderEvent with type: ON_ERROR When an error happened during loading
- (null)

onWorkerLoadProgress

private function onWorkerLoadProgress (

e:LoaderWorkerEvent) : Void

Monitors the loading progress of one LoaderWorker object. This event is passed on to listeners of the Loader.

Parameters:

event object with properties: .name, .type, .target

Events broadcasted to listeners:

LoaderEvent with type: ON_PROGRESS When some data has been received
- (null)