+Show TOC
×Hide TOC

GroupLoad

Kind of class:	public class
Package:	org.casalib.load
Inherits from:	ProcessGroup < Process < RemovableEventDispatcher < EventDispatcher
Version:	12/01/08
Author:	Aaron Clinger
Classpath:	org.casalib.load.GroupLoad
File last modified:	Monday, 01 December 2008, 11:16:36

► View source

▼ Hide source

/*
    CASA Lib for ActionScript 3.0
    Copyright (c) 2008, 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.load.BaseLoadItem;
    import org.casalib.math.Percent;
    import org.casalib.process.Process;
    import org.casalib.process.ProcessGroup;
    import org.casalib.util.ArrayUtil;
    
    [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 12/01/08
        @example
            <code>
                package {
                    import flash.display.MovieClip;
                    import org.casalib.load.GraphicLoad;
                    import org.casalib.load.GroupLoad;
                    import org.casalib.events.LoadEvent;
                    
                    
                    public class MyExample extends MovieClip {
                        protected var _groupLoad:GroupLoad;
                        protected var _imageOne:GraphicLoad;
                        protected var _imageTwo:GraphicLoad;
                        protected var _imageThree:GraphicLoad;
                        protected var _imageFour:GraphicLoad;
                        
                        
                        public function MyExample() {
                            super();
                            
                            this._imageOne   = new GraphicLoad("test1.jpg");
                            this._imageTwo   = new GraphicLoad("test2.jpg");
                            this._imageThree = new GraphicLoad("test3.jpg");
                            this._imageFour  = new GraphicLoad("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 _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 BaseLoadItem} (Including another GroupLoad) and dispatches events {@link LoadEvent#COMPLETE}, {@link LoadEvent#PROGRESS} and {@code IOErrorEvent}.
            @param percentOfGroup: Defines the percentage of the total group the size of the load item represents; defaults to equal increments.
        */
        public function addLoad(load:BaseLoadItem, percentOfGroup:Percent = null):void {
            super.addProcess(load);
            
            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:BaseLoadItem):void {
            this._percentMap[load] = null;
            
            delete this._percentMap[load];
            
            super.removeProcess(load);
        }
        
        /**
            The loads that compose the group.
            
            @return Returns an Array containing all loads in the group.
        */
        public function get loads():Array {
            return this.processes;
        }
        
        /**
            Specifies if a random value name/value pair should be appended to every load in GroupLoad {@code true}, or not append {@code false}; defaults to {@code false}.
            
            @see LoadItem#preventCache
        */
        public function get preventCache():Boolean {
            return this._preventCache;
        }
        
        public function set preventCache(cache:Boolean):void {
            this._preventCache = cache;
        }
        
        /**
            The percent that the group is loaded.
        */
        public function get progress():Percent {
            return this._progress.clone();
        }
        
        /**
            Determines if the group is loading {@code true}, or if it isn't currently loading {@code false}.
        */
        public function get loading():Boolean {
            return this.running;
        }
        
        /**
            Determines if all loads in the group are loaded {@code true}, or if the group hasn't finished loading {@code false}.
        */
        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 BaseLoadItem)
                this.addLoad(process as BaseLoadItem);
        }
        
        /**
            @exclude
        */
        override public function removeProcess(process:Process):void {
            if (process is BaseLoadItem)
                this.removeLoad(process as BaseLoadItem);
        }
        
        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 _startProcess(process:Process):void {
            var load:BaseLoadItem = process as BaseLoadItem;
            
            load.addEventListener(LoadEvent.PROGRESS, this._onProgress);
            
            if (this.preventCache)
                load.preventCache = true;
            
            super._startProcess(process);
        }
        
        override protected function _removeProcessListeners(process:Process):void {
            process.removeEventListener(LoadEvent.PROGRESS, this._onProgress);
            
            super._removeProcessListeners(process);
        }
        
        /**
            @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:BaseLoadItem;
            
            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));
        }
        
        /**
            @sends LoadEvent#COMPLETE - When GroupLoad has completed loading all the loads in the group.
        */
        override protected function _complete():void {
            super._complete();
            
            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 flash.display.MovieClip;
    import org.casalib.load.GraphicLoad;
    import org.casalib.load.GroupLoad;
    import org.casalib.events.LoadEvent;


    public class MyExample extends MovieClip {
        protected var _groupLoad:GroupLoad;
        protected var _imageOne:GraphicLoad;
        protected var _imageTwo:GraphicLoad;
        protected var _imageThree:GraphicLoad;
        protected var _imageFour:GraphicLoad;


        public function MyExample() {
            super();

            this._imageOne   = new GraphicLoad("test1.jpg");
            this._imageTwo   = new GraphicLoad("test2.jpg");
            this._imageThree = new GraphicLoad("test3.jpg");
            this._imageFour  = new GraphicLoad("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

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.
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 processes threads

Instance properties inherited from Process

_hasCompleted _isRunning _priority completed priority running

Instance properties inherited from RemovableEventDispatcher

_isDestroyed _listenerManager destroyed

Instance methods

addLoad (load:BaseLoadItem = null) : void
- Add a load to the group.
removeLoad (load:BaseLoadItem) : void
- Removes a load item from the group.
destroy : void

Instance methods inherited from ProcessGroup

_checkThreads _processCompleted _processStopped _removeProcessListeners _startProcess addProcess destroy destroyProcesses removeProcess start stop

Instance methods inherited from Process

_complete destroy start stop

Instance methods inherited from RemovableEventDispatcher

addEventListener destroy 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.

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.

loads

public loads:Array

(read)

The loads that compose the group.

Returns:

Returns an Array containing all loads in 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.

Instance methods

addLoad

public function addLoad (

load:BaseLoadItem, 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 BaseLoadItem (Including another GroupLoad) and dispatches events LoadEvent.COMPLETE, LoadEvent.PROGRESS and IOErrorEvent.

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

removeLoad

public function removeLoad (

load:BaseLoadItem) : void

Removes a load item from the group.

Parameters:

load:

Load to be removed from the group.