+Show TOC
×Hide TOC

GroupLoad

Kind of class:	public class
Package:	org.casalib.load
Inherits from:	ProcessGroup < Process < RemovableEventDispatcher < EventDispatcher
Version:	09/06/09
Author:	Aaron Clinger
Classpath:	org.casalib.load.GroupLoad
File last modified:	Sunday, 06 September 2009, 09:05:44

► View source

▼ Hide source

/*
    CASA Lib for ActionScript 3.0
    Copyright (c) 2009, Aaron Clinger & Contributors of CASA Lib
    All rights reserved.
    
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:
    
    - Redistributions of source code must retain the above copyright notice,
      this list of conditions and the following disclaimer.
    
    - Redistributions in binary form must reproduce the above copyright notice,
      this list of conditions and the following disclaimer in the documentation
      and/or other materials provided with the distribution.
    
    - Neither the name of the CASA Lib nor the names of its contributors
      may be used to endorse or promote products derived from this software
      without specific prior written permission.
    
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
    POSSIBILITY OF SUCH DAMAGE.
*/
package org.casalib.load {
    import flash.utils.Dictionary;
    import org.casalib.events.LoadEvent;
    import org.casalib.events.ProcessEvent;
    import org.casalib.math.Percent;
    import org.casalib.process.Process;
    import org.casalib.process.ProcessGroup;
    import org.casalib.util.ArrayUtil;
    import org.casalib.load.LoadItem;
    
    [Event(name="complete", type="org.casalib.events.LoadEvent")]
    [Event(name="progress", type="org.casalib.events.LoadEvent")]
    
    /**
        Allows multiple loads to be grouped and treated as one larger load.
        
        @author Aaron Clinger
        @version 09/06/09
        @example
            <code>
                package {
                    import org.casalib.display.CasaMovieClip;
                    import org.casalib.events.LoadEvent;
                    import org.casalib.load.GroupLoad;
                    import org.casalib.load.ImageLoad;
                    
                    
                    public class MyExample extends CasaMovieClip {
                        protected var _groupLoad:GroupLoad;
                        protected var _imageOne:ImageLoad;
                        protected var _imageTwo:ImageLoad;
                        protected var _imageThree:ImageLoad;
                        protected var _imageFour:ImageLoad;
                        
                        
                        public function MyExample() {
                            super();
                            
                            this._imageOne   = new ImageLoad("test1.jpg");
                            this._imageTwo   = new ImageLoad("test2.jpg");
                            this._imageThree = new ImageLoad("test3.jpg");
                            this._imageFour  = new ImageLoad("test4.jpg");
                            
                            this._imageTwo.loader.x   = 10;
                            this._imageThree.loader.x = 20;
                            this._imageFour.loader.x  = 30;
                            
                            this.addChild(this._imageOne.loader);
                            this.addChild(this._imageTwo.loader);
                            this.addChild(this._imageThree.loader);
                            this.addChild(this._imageFour.loader);
                            
                            this._groupLoad = new GroupLoad();
                            this._groupLoad.addLoad(this._imageOne);
                            this._groupLoad.addLoad(this._imageTwo);
                            this._groupLoad.addLoad(this._imageThree);
                            this._groupLoad.addLoad(this._imageFour);
                            this._groupLoad.addEventListener(LoadEvent.PROGRESS, this._onProgress);
                            this._groupLoad.addEventListener(LoadEvent.COMPLETE, this._onComplete);
                            this._groupLoad.start();
                        }
                        
                        protected function _onProgress(e:LoadEvent):void {
                            trace("Group is " + e.progress.percentage + "% loaded at " + e.Bps + "Bps.");
                        }
                        
                        protected function _onComplete(e:LoadEvent):void {
                            trace("Group has loaded.");
                        }
                    }
                }
            </code>
    */
    public class GroupLoad extends ProcessGroup {
        protected var _preventCacheSet:Boolean;
        protected var _preventCache:Boolean;
        protected var _progress:Percent;
        protected var _Bps:int;
        protected var _percentMap:Dictionary;
        
        
        /**
            Creates a new GroupLoad.
        */
        public function GroupLoad() {
            super();
            
            this._percentMap = new Dictionary();
            this._progress   = new Percent();
        }
        
        /**
            Add a load to the group.
            
            @param load: Load to be added to the group. Can be any class that extends from {@link LoadItem}.
            @param percentOfGroup: Defines the percentage of the total group the size of the load item represents; defaults to equal increments.
        */
        public function addLoad(load:LoadItem, percentOfGroup:Percent = null):void {
            super.addProcess(load);
            
            if (this._preventCacheSet)
                load.preventCache = this.preventCache;
            
            this._percentMap[load] = (percentOfGroup == null) ? new Percent(0.01) : percentOfGroup.clone();
            
            if (this.autoStart && !this.completed && this.running)
                this._checkTotalPercentValidity();
        }
        
        /**
            Removes a load item from the group.
            
            @param load: Load to be removed from the group.
        */
        public function removeLoad(load:LoadItem):void {
            this._percentMap[load] = null;
            delete this._percentMap[load];
            
            super.removeProcess(load);
        }
        
        /**
            Determines if this GroupLoad contains a specific load item.
            
            @param load: The load item to search for.
            @return Returns <code>true</code> if the GroupLoad contains the load item; otherwise <code>false</code>.
        */
        public function hasLoad(load:LoadItem):Boolean {
            return this.hasProcess(load);
        }
        
        /**
            The loads that compose the group.
        */
        public function get loads():Array {
            return this.processes;
        }
        
        /**
            The loads that are neither complete nor loading.
        */
        public function get queuedLoads():Array {
            return this.queuedProcesses;
        }
        
        /**
            The loads that are currently loading.
        */
        public function get loadingLoads():Array {
            return this.runningProcesses;
        }
        
        /**
            The loads that have not completed.
        */
        public function get incompletedLoads():Array {
            return this.incompletedProcesses;
        }
        
        /**
            The loads that have completed.
        */
        public function get completedLoads():Array {
            return this.completedProcesses;
        }
        
        /**
            Specifies if a random value name/value pair should be appended to every load in GroupLoad <code>true</code>, or not append <code>false</code>; defaults to <code>false</code>.
            
            @see LoadItem#preventCache
        */
        public function get preventCache():Boolean {
            return this._preventCache;
        }
        
        public function set preventCache(cache:Boolean):void {
            this._preventCacheSet = true;
            this._preventCache    = cache;
            
            var items:Array = this.loads;
            var l:Number    = items.length;
            
            while (l--)
                items[l].preventCache = this.preventCache;
        }
        
        /**
            The percent that the group is loaded.
        */
        public function get progress():Percent {
            return this._progress.clone();
        }
        
        /**
            Determines if the group is loading <code>true</code>, or if it isn't currently loading <code>false</code>.
        */
        public function get loading():Boolean {
            return this.running;
        }
        
        /**
            Determines if all loads in the group are loaded <code>true</code>, or if the group hasn't finished loading <code>false</code>.
        */
        public function get loaded():Boolean {
            return this.completed;
        }
        
        /**
            The current download speed of the group in bytes per second.
        */
        public function get Bps():int {
            return this._Bps;
        }
        
        /**
            @exclude
        */
        override public function start():void {
            this._checkTotalPercentValidity();
            
            super.start();
        }
        
        /**
            @exclude
        */
        override public function addProcess(process:Process):void {
            if (process is LoadItem)
                this.addLoad(process as LoadItem);
        }
        
        /**
            @exclude
        */
        override public function removeProcess(process:Process):void {
            if (process is LoadItem)
                this.removeLoad(process as LoadItem);
        }
        
        /**
            @exclude
        */
        override public function destroyProcesses():void {
            var l:uint = this._processes.length;
            var load:LoadItem;
            
            while (l--) {
                load = this._processes[l];
                
                this._percentMap[load] = null;
                delete this._percentMap[load];
                
                load.destroy();
            }
            
            this._processes = new Array();
        }
        
        /**
            Calls {@link LoadItem#destroy destroy} on all loads in the group and removes them from the GroupLoad.
        */
        public function destroyLoads():void {
            this.destroyProcesses();
        }
        
        override public function destroy():void {
            this._percentMap = new Dictionary();
            this._progress   = new Percent();
            this._Bps        = -1;
            
            super.destroy();
        }
        
        protected function _checkTotalPercentValidity():void {
            var perTotal:Number = 0;
            
            for (var i:Object in this._percentMap)
                perTotal += this._percentMap[i].decimalPercentage;
            
            if (perTotal != 1)
                for (i in this._percentMap)
                    this._percentMap[i] = new Percent(this._percentMap[i].decimalPercentage / perTotal);
        }
        
        override protected function _addProcessListeners(process:Process):void {
            process.addEventListener(LoadEvent.PROGRESS, this._onProgress, false, 0, true);
            process.addEventListener(ProcessEvent.STOP, this._onProcessStopped, false, 0, true);
            process.addEventListener(LoadEvent.COMPLETE, this._onLoadCompleted, false, 0, true);
        }
        
        override protected function _removeProcessListeners(process:Process):void {
            process.removeEventListener(LoadEvent.PROGRESS, this._onProgress);
            process.removeEventListener(ProcessEvent.STOP, this._onProcessStopped);
            process.removeEventListener(LoadEvent.COMPLETE, this._onLoadCompleted);
        }
        
        /**
            @sends LoadEvent#PROGRESS - Dispatched as the loads in the group are downloading.
        */
        protected function _onProgress(e:LoadEvent):void {
            var speed:Array     = new Array();
            var perTotal:Number = 0;
            var p:Array         = this.processes;
            var l:uint          = p.length;
            var load:LoadItem;
            
            while (l--) {
                load = p[l];
                
                if (load.loading) {
                    speed.push(load.Bps);
                    perTotal += this._percentMap[load].decimalPercentage * load.progress.decimalPercentage;
                } else if (load.loaded) {
                    speed.push(load.Bps);
                    perTotal += this._percentMap[load].decimalPercentage;
                }
            }
            
            this._Bps      = int(ArrayUtil.average(speed));
            this._progress = new Percent(perTotal);
            
            this.dispatchEvent(this._createDefinedLoadEvent(LoadEvent.PROGRESS));
        }
        
        protected function _onLoadCompleted(e:LoadEvent):void {
            this._checkThreads();
        }
        
        /**
            @sends LoadEvent#COMPLETE - When GroupLoad has completed loading all the loads in the group.
        */
        override protected function _complete():void {
            super._complete();
            
            this._progress.decimalPercentage = 1;
            
            this.dispatchEvent(this._createDefinedLoadEvent(LoadEvent.COMPLETE));
        }
        
        protected function _createDefinedLoadEvent(type:String):LoadEvent {
            var loadEvent:LoadEvent = new LoadEvent(type);
            loadEvent.bytesLoaded   = 0;
            loadEvent.bytesTotal    = 0;
            loadEvent.progress      = this.progress;
            loadEvent.Bps           = this.Bps;
            
            return loadEvent;
        }
    }
}

Allows multiple loads to be grouped and treated as one larger load.

Example:

package {
    import org.casalib.display.CasaMovieClip;
    import org.casalib.events.LoadEvent;
    import org.casalib.load.GroupLoad;
    import org.casalib.load.ImageLoad;


    public class MyExample extends CasaMovieClip {
        protected var _groupLoad:GroupLoad;
        protected var _imageOne:ImageLoad;
        protected var _imageTwo:ImageLoad;
        protected var _imageThree:ImageLoad;
        protected var _imageFour:ImageLoad;


        public function MyExample() {
            super();

            this._imageOne   = new ImageLoad("test1.jpg");
            this._imageTwo   = new ImageLoad("test2.jpg");
            this._imageThree = new ImageLoad("test3.jpg");
            this._imageFour  = new ImageLoad("test4.jpg");

            this._imageTwo.loader.x   = 10;
            this._imageThree.loader.x = 20;
            this._imageFour.loader.x  = 30;

            this.addChild(this._imageOne.loader);
            this.addChild(this._imageTwo.loader);
            this.addChild(this._imageThree.loader);
            this.addChild(this._imageFour.loader);

            this._groupLoad = new GroupLoad();
            this._groupLoad.addLoad(this._imageOne);
            this._groupLoad.addLoad(this._imageTwo);
            this._groupLoad.addLoad(this._imageThree);
            this._groupLoad.addLoad(this._imageFour);
            this._groupLoad.addEventListener(LoadEvent.PROGRESS, this._onProgress);
            this._groupLoad.addEventListener(LoadEvent.COMPLETE, this._onComplete);
            this._groupLoad.start();
        }

        protected function _onProgress(e:LoadEvent):void {
            trace("Group is " + e.progress.percentage + "% loaded at " + e.Bps + "Bps.");
        }

        protected function _onComplete(e:LoadEvent):void {
            trace("Group has loaded.");
        }
    }
}

Events broadcasted to listeners:

LoadEvent with type: PROGRESS - Dispatched as the loads in the group are downloading.
LoadEvent with type: COMPLETE - When GroupLoad has completed loading all the loads in the group.

Summary

Constructor

GroupLoad

Constants

Constants inherited from ProcessGroup

MAX_THREADS

Class properties

Class properties inherited from ProcessGroup

NORM_THREADS

Class properties inherited from Process

NORM_PRIORITY

Instance properties

loads : Array
- The loads that compose the group.
queuedLoads : Array
- The loads that are neither complete nor loading.
loadingLoads : Array
- The loads that are currently loading.
incompletedLoads : Array
- The loads that have not completed.
completedLoads : Array
- The loads that have completed.
preventCache : Boolean
- Specifies if a random value name/value pair should be appended to every load in GroupLoad true, or not append false; defaults to false.
progress : Percent
- The percent that the group is loaded.
loading : Boolean
- Determines if the group is loading true, or if it isn't currently loading false.
loaded : Boolean
- Determines if all loads in the group are loaded true, or if the group hasn't finished loading false.
Bps : int
- The current download speed of the group in bytes per second.

Instance properties inherited from ProcessGroup

_autoStart _processes _threads autoStart completedProcesses incompletedProcesses processes queuedProcesses runningProcesses threads

Instance properties inherited from Process

_hasCompleted _isRunning _priority completed priority running

Instance properties inherited from RemovableEventDispatcher

_isDestroyed _listenerManager destroyed

Instance methods

addLoad (load:LoadItem = null) : void
- Add a load to the group.
removeLoad (load:LoadItem) : void
- Removes a load item from the group.
hasLoad (load:LoadItem) : Boolean
- Determines if this GroupLoad contains a specific load item.
destroyLoads : void
- Calls destroy on all loads in the group and removes them from the GroupLoad.
destroy : void

Instance methods inherited from ProcessGroup

_addProcessListeners _checkThreads _onProcessCompleted _onProcessStopped _removeProcessListeners addProcess destroy destroyProcesses hasProcess removeProcess start stop

Instance methods inherited from Process

_complete destroy start stop

Instance methods inherited from RemovableEventDispatcher

addEventListener destroy dispatchEvent removeEventListener removeEventListeners removeEventsForListener removeEventsForType

Constructor

GroupLoad

public function GroupLoad (

)

Creates a new GroupLoad.

Instance properties

Bps

public Bps:int

(read)

The current download speed of the group in bytes per second.

completedLoads

public completedLoads:Array

(read)

The loads that have completed.

incompletedLoads

public incompletedLoads:Array

(read)

The loads that have not completed.

loaded

public loaded:Boolean

(read)

Determines if all loads in the group are loaded true, or if the group hasn't finished loading false.

loading

public loading:Boolean

(read)

Determines if the group is loading true, or if it isn't currently loading false.

loadingLoads

public loadingLoads:Array

(read)

The loads that are currently loading.

loads

public loads:Array

(read)

The loads that compose the group.

preventCache

public preventCache:Boolean

(read,write)

Specifies if a random value name/value pair should be appended to every load in GroupLoad true, or not append false; defaults to false.

progress

public progress:Percent

(read)

The percent that the group is loaded.

queuedLoads

public queuedLoads:Array

(read)

The loads that are neither complete nor loading.

Instance methods

addLoad

public function addLoad (

load:LoadItem, percentOfGroup:Percent = null) : void

Add a load to the group.

Parameters:

load :

Load to be added to the group. Can be any class that extends from LoadItem.

percentOfGroup:

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

destroy

override public function destroy (

) : void

Overrides:

ProcessGroup.destroy

destroyLoads

public function destroyLoads (

) : void

Calls destroy on all loads in the group and removes them from the GroupLoad.

hasLoad

public function hasLoad (

load:LoadItem) : Boolean

Determines if this GroupLoad contains a specific load item.

Parameters:

load:

The load item to search for.

Returns:

Returns true if the GroupLoad contains the load item; otherwise false.

removeLoad

public function removeLoad (

load:LoadItem) : void

Removes a load item from the group.

Parameters:

load:

Load to be removed from the group.