+Show TOC
×Hide TOC

LoadGroup

Kind of class:	class
Inherits from:	EventDispatcher < CoreObject
Implements:	LoadInterface
Version:	04/09/07
Author:	Aaron Clinger
Classpath:	org.casaframework.load.LoadGroup
File last modified:	Tuesday, 10 April 2007, 09:46:51

► View source

▼ Hide source

/*
    CASA Framework for ActionScript 2.0
    Copyright (C) 2007  CASA Framework
    http://casaframework.org
    
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2.1 of the License, or (at your option) any later version.
    
    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.
    
    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
*/

import org.casaframework.event.EventDispatcher;
import org.casaframework.load.base.LoadInterface;
import org.casaframework.load.base.BytesLoadInterface;
import org.casaframework.load.base.BytesLoad;
import org.casaframework.math.Percent;

/**
    Allows multiple loads to be treated as one larger load item.
    
    @author Aaron Clinger
    @version 04/09/07
    @example
        <code>
            var xmlLoad:XmlLoad = new XmlLoad("test.xml");
            var imageLoad:MediaLoad = new MediaLoad(this.loadZone_mc, "test.jpg");
            
            var myLoadGroup = new LoadGroup();
            this.myLoadGroup.addLoad(this.xmlLoad);
            this.myLoadGroup.addLoad(this.imageLoad);
            this.myLoadGroup.addEventObserver(this, LoadGroup.EVENT_LOAD_PERCENT, "onGroupLoadPercent");
            this.myLoadGroup.addEventObserver(this, LoadGroup.EVENT_LOAD_ERROR, "onGroupLoadError");
            
            function onGroupLoadPercent(sender:LoadGroup, progress:Percent):Void {
                trace("My group is " + progress.getPercentage() + "% loaded.");
            }
            
            function onGroupLoadError(sender:LoadGroup, failedLoad:BytesLoadInterface):Void {
                this.myLoadGroup.removeLoad(failedLoad);
                this.myLoadGroup.start();
            }
            
            this.myLoadGroup.start();
        </code>
*/

class org.casaframework.load.LoadGroup extends EventDispatcher implements LoadInterface {
    public static var EVENT_LOAD_START:String    = 'onLoadStart';
    public static var EVENT_LOAD_STOP:String     = 'onLoadStop';
    public static var EVENT_LOAD_ERROR:String    = 'onLoadError';
    public static var EVENT_LOAD_PERCENT:String  = 'onLoadPercent';
    public static var EVENT_LOAD_COMPLETE:String = 'onLoadComplete';
    private var $hasLoaded:Boolean;
    private var $isLoading:Boolean;
    private var $group: /*Object*/ Array;
    private var $position:Number;
    private var $percent:Number;
    
    
    /**
        Creates a new LoadGroup object.
    */
    public function LoadGroup() {
        super();
        
        this.$group = new Array();
        this.$hasLoaded = this.$isLoading = false;
        
        this.$setClassDescription('org.casaframework.load.LoadGroup');
    }
    
    /**
        Add a load item to the group.
        
        @param loadItem: Load to be added to the load group. Can be any class that implements {@link BytesLoadInterface} and dispatches events <code>"onLoadProgress"</code>, <code>"onLoadComplete"</code> and <code>"onLoadError"</code>.
        @param percentOfGroup: <strong>[optional]</strong> Defines the percentage of the total group the size of the load item represents; defaults to equal increments.
    */
    public function addLoad(loadItem:BytesLoadInterface, percentOfGroup:Percent):Void {
        if (this.isLoading() || this.hasLoaded())
            return;
        
        this.removeLoad(loadItem);
        
        var loadInfo:Object = new Object();
        loadInfo.load       = loadItem;
        loadInfo.percent    = (percentOfGroup != undefined) ? percentOfGroup.clone() : new Percent(.01);
        
        this.$group.push(loadInfo);
    }
    
    /**
        Removes a load item from the group.
        
        @param loadItem: Load to be removed from the load cue.
        @return Returns <code>true</code> if item was successfully found and removed; otherwise <code>false</code>.
        @usageNote You cannot remove a load item when the LoadGroup is in the process of loading.
    */
    public function removeLoad(loadItem:BytesLoadInterface):Boolean {
        if (this.isLoading())
            return;
        
        var l:Number = this.$group.length;
        while (l--) {
            if (loadItem == this.$group[l].load) {
                this.$group.splice(l, 1);
                return true;
            }
        }
        
        return false;
    }
    
    /**
        Starts the group load process and begins reporting of the total load percentage of all files to observers.
        
        @sends onLoadStart = function(sender:LoadGroup) {}
    */
    public function start():Void {
        if (this.isLoading() || this.hasLoaded() || this.$group.length == 0)
            return;
        
        this.$isLoading = true;
        this.$position  = -1;
        this.$percent   = 0;
        
        this.$checkTotalPercentValidity();
        this.$loadNextItem();
        
        this.dispatchEvent(LoadGroup.EVENT_LOAD_START, this);
    }
    
    /**
        Stops the group load process.
        
        @sends onLoadStop = function(sender:LoadGroup) {}
    */
    public function stop():Void {
        if (!this.isLoading())
            return;
        
        this.$stopLoad();
        
        this.dispatchEvent(LoadGroup.EVENT_LOAD_STOP, this);
    }
    
    public function hasLoaded():Boolean {
        return this.$hasLoaded;
    }
    
    public function isLoading():Boolean {
        return this.$isLoading;
    }
    
    /**
        @exclude
        
        This is needed to adhere to LoadInterface but isn't used in this class.
    */
    public function getFilePath():String {
        return null;
    }
    
    public function destroy():Void {
        if (this.isLoading())
            this.$group[this.$position].load.removeEventObserversForScope(this);
        
        var i:Number = this.$group.length;
        while (i--)
            this.$group[i].percent.destroy();
        
        this.$group.splice(0);
        
        delete this.$hasLoaded;
        delete this.$isLoading;
        delete this.$group;
        delete this.$position;
        delete this.$percent;
        
        super.destroy();
    }
    
    private function $stopLoad():Void {
        this.$isLoading = false;
        this.$group[this.$position].load.removeEventObserversForScope(this);
    }
    
    /**
        @sends onLoadComplete = function(sender:LoadGroup) {}
    */
    private function $loadNextItem():Void {
        if (++this.$position >= this.$group.length) {
            this.$hasLoaded = true;
            this.$isLoading = false;
            
            if (this.$percent != 1)
                this.dispatchEvent(LoadGroup.EVENT_LOAD_PERCENT, this, new Percent(1));
            
            this.dispatchEvent(LoadGroup.EVENT_LOAD_COMPLETE, this);
            return;
        }
            
        var loadItem:Object = this.$group[this.$position];
        
        if (loadItem.load.hasLoaded()) {
            this.$loadProgress(loadItem.load, 1, 1);
            this.$loadCompleted(loadItem.load);
            return;
        } else {
            loadItem.load.addEventObserver(this, BytesLoad.EVENT_LOAD_ERROR, '$loadError');
            loadItem.load.addEventObserver(this, BytesLoad.EVENT_LOAD_PROGRESS, '$loadProgress');
            loadItem.load.addEventObserver(this, BytesLoad.EVENT_LOAD_COMPLETE, '$loadCompleted');
            loadItem.load.start();
        }
    }
    
    /**
        @sends onLoadPercent = function(sender:LoadGroup, progress:Percent) {}
    */
    private function $loadProgress(sender:BytesLoadInterface, bytesLoaded:Number, bytesTotal:Number):Void {
        this.dispatchEvent(LoadGroup.EVENT_LOAD_PERCENT, this, new Percent((bytesLoaded / bytesTotal) * this.$group[this.$position].percent.getDecimalPercentage() + this.$percent));
    }
    
    private function $loadCompleted(sender:BytesLoadInterface):Void {
        var loadItem:Object = this.$group[this.$position];
        
        loadItem.load.removeEventObserversForScope(this);
        this.$percent += loadItem.percent.getDecimalPercentage();
        
        this.$loadNextItem();
    }
    
    /**
        @sends onLoadError = function(sender:LoadGroup, failedLoad:BytesLoadInterface) {}
    */
    private function $loadError():Void {
        this.$stopLoad();
        this.dispatchEvent(LoadGroup.EVENT_LOAD_ERROR, this, this.$group[this.$position].load);
    }
    
    private function $checkTotalPercentValidity():Void {
        var l:Number = this.$group.length;
        var perTotal:Number = 0;
        var loadItem:Object;
        
        while (l--) {
            loadItem = this.$group[l];
            
            if (loadItem.percent.getDecimalPercentage() <= 0)
                loadItem.percent.setDecimalPercentage(.01);
            
            perTotal += loadItem.percent.getDecimalPercentage();
        }
        
        if (perTotal != 1) {
            l = this.$group.length;
            
            while (l--) {
                loadItem = this.$group[l];
                loadItem.percent.setDecimalPercentage((loadItem.percent.getDecimalPercentage() / perTotal) * 1);
            }
        }
    }
}

Allows multiple loads to be treated as one larger load item.

Example:

var xmlLoad:XmlLoad = new XmlLoad("test.xml");
var imageLoad:MediaLoad = new MediaLoad(this.loadZone_mc, "test.jpg");

var myLoadGroup = new LoadGroup();
this.myLoadGroup.addLoad(this.xmlLoad);
this.myLoadGroup.addLoad(this.imageLoad);
this.myLoadGroup.addEventObserver(this, LoadGroup.EVENT_LOAD_PERCENT, "onGroupLoadPercent");
this.myLoadGroup.addEventObserver(this, LoadGroup.EVENT_LOAD_ERROR, "onGroupLoadError");

function onGroupLoadPercent(sender:LoadGroup, progress:Percent):Void {
    trace("My group is " + progress.getPercentage() + "% loaded.");
}

function onGroupLoadError(sender:LoadGroup, failedLoad:BytesLoadInterface):Void {
    this.myLoadGroup.removeLoad(failedLoad);
    this.myLoadGroup.start();
}

this.myLoadGroup.start();

Events broadcast to listeners:

onLoadStart = function (sender:LoadGroup) {}
onLoadStop = function (sender:LoadGroup) {}
onLoadComplete = function (sender:LoadGroup) {}
onLoadPercent = function (sender:LoadGroup, progress:Percent) {}
onLoadError = function (sender:LoadGroup, failedLoad:BytesLoadInterface) {}

Summary

Constructor

LoadGroup

Class properties

EVENT_LOAD_START
EVENT_LOAD_STOP
EVENT_LOAD_ERROR
EVENT_LOAD_PERCENT
EVENT_LOAD_COMPLETE

Instance properties

Instance properties inherited from EventDispatcher

$eventMap

Instance properties inherited from CoreObject

$instanceDescription

Instance methods

addLoad
removeLoad
start
stop
hasLoaded
isLoading
destroy

Instance methods inherited from EventDispatcher

addEventObserver destroy dispatchEvent removeAllEventObservers removeEventObserver removeEventObserversForEvent removeEventObserversForScope

Instance methods inherited from CoreObject

$setClassDescription destroy toString

Constructor

LoadGroup

function LoadGroup (

)

Creates a new LoadGroup object.

Class properties

EVENT_LOAD_COMPLETE

static EVENT_LOAD_COMPLETE:String = 'onLoadComplete'

(read,write)

EVENT_LOAD_ERROR

static EVENT_LOAD_ERROR:String = 'onLoadError'

(read,write)

EVENT_LOAD_PERCENT

static EVENT_LOAD_PERCENT:String = 'onLoadPercent'

(read,write)

EVENT_LOAD_START

static EVENT_LOAD_START:String = 'onLoadStart'

(read,write)

EVENT_LOAD_STOP

static EVENT_LOAD_STOP:String = 'onLoadStop'

(read,write)

Instance methods

addLoad

function addLoad (

loadItem:BytesLoadInterface, percentOfGroup:Percent) : Void

Add a load item to the group.

Parameters:

loadItem :

Load to be added to the load group. Can be any class that implements org.casaframework.load.base.BytesLoadInterface and dispatches events "onLoadProgress", "onLoadComplete" and "onLoadError".

percentOfGroup:

[optional] Defines the percentage of the total group the size of the load item represents; defaults to equal increments.

destroy

function destroy (

) : Void

Removes any internal variables, intervals, enter frames, internal MovieClips and event observers to allow the object to be garbage collected.

Always call destroy() before deleting last object pointer.

Overrides:

org.casaframework.event.EventDispatcher.destroy

Specified by:

org.casaframework.core.CoreInterface.destroy

hasLoaded

function hasLoaded (

) : Boolean

Determines whether the requested file has finished loading.

Returns:

Returns true if file has completely loaded; otherwise false.

Specified by:

org.casaframework.load.base.LoadInterface.hasLoaded

isLoading

function isLoading (

) : Boolean

Determines whether the requested file is in the process of loading.

Returns:

Returns true if the file is currently loading; otherwise false.

Specified by:

org.casaframework.load.base.LoadInterface.isLoading

removeLoad

function removeLoad (

loadItem:BytesLoadInterface) : Boolean

Removes a load item from the group.

Parameters:

loadItem:

Load to be removed from the load cue.

Returns:

Returns true if item was successfully found and removed; otherwise false.

Usage note:

You cannot remove a load item when the LoadGroup is in the process of loading.

start

function start (

) : Void

Starts the group load process and begins reporting of the total load percentage of all files to observers.

Events broadcast to listeners:

onLoadStart = function (sender:LoadGroup) {}

Specified by:

org.casaframework.control.RunnableInterface.start

stop

function stop (

) : Void

Stops the group load process.

Events broadcast to listeners:

onLoadStop = function (sender:LoadGroup) {}

Specified by:

org.casaframework.control.RunnableInterface.stop