ProgressIndicator

/*
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.ui.EventMovieClip;
import org.asapframework.util.actionqueue.*;

import playground.classes.ui.ProgressIndicatorEvent;

/**
Generic progress controller UI class that optionally may be given a 'progress delay' for smoothing.
ProgressIndicator may be used for progress bars and preloaders.
@author Arthur Clemens
@version 12 Feb 2006
@todo Implement indeterminate progress indicator.
*/

class playground.classes.ui.ProgressIndicator extends EventMovieClip {
    
    private var mAmountDone:Number = 0;
    private var mAmountDrawn:Number = 0;
    private var mMinValue:Number = 0;
    private var mMaxValue:Number = 100;
    private var mProgressDelay:Number = 0; // delay duration in seconds
    private var mEffect:Function = null;
    private var mUpdateQueue:ActionQueue;
    
    /**
    Calls {@link #init}.
    */
    function onLoad () : Void {
        super.onLoad();
        init();
    }
    
    /**
    Subclasses will set the indicator property (_x, _y, _xscale, _yscale or _alpha) to its initial value here.
    @example
    <code>
    function init () : Void {
        _yscale = 0;
    }
    </code>
    */
    public function init () : Void {
        // to be implemented by subclasses
    }
    
    /**
    Sets the minimum value. This is related to the amount passed in {@link #incrementToValue}. For instance, if incrementToValue gets values between 0.0 and 1.0, the max amount is 1.0. The default is 100.
    @param inMaxValue : the maximum amount that will be passed to {@link #incrementToValue}
    */
    public function setMinValue (inValue:Number) : Void {
        mMinValue = inValue;
    }
    
    /**
    Sets the maximum value. This is related to the amount passed in {@link #incrementToValue}. For instance, if incrementToValue gets values between 0.0 and 1.0, the max amount is 1.0. The default is 100.
    @param inMaxValue : the maximum amount that will be passed to {@link #incrementToValue}
    */
    public function setMaxValue (inValue:Number) : Void {
        mMaxValue = inValue;
    }
    
    /**
    Sets the delay of the draw animation after each call of {@link #incrementToValue}.    The default is 0 (no delay).
    @param inDelay : the delay in seconds
    */
    public function setProgressDelay (inDelay:Number) : Void {
        mProgressDelay = inDelay;
    }
    
    /**
    Effect function when drawing, for instance one of the mx.transitions.easing methods.
    */
    public function setEffect (inEffect:Function) : Void {
        mEffect = inEffect;
    }
    
    /**
    To be used by indeterminate progress indicator (not implemented).
    */
    public function startAnimation () : Void {
    }
    
    /**
    To be used by indeterminate progress indicator (not implemented).
    */    
    public function stopAnimation () : Void {
    }
    
    /**
    Tells the indicator to update.
    @param inValue : the value to update to
    @implementationNote Calls {@link #update}.
    @sends ProgressIndicatorEvent#FINISHED When the amount drawn is equal to the max amount
    */
    public function incrementToValue (inValue:Number) : Void {
        var delay:Number = (mProgressDelay != 0) ? mProgressDelay : -1;
        mAmountDone = inValue;
        trace("incrementToValue: " + delay);
        mUpdateQueue.quit();
        mUpdateQueue = new ActionQueue();
        mUpdateQueue.addAction( AQReturnValue.returnValue, this, "update", delay, mAmountDrawn, mAmountDone, mEffect );

        if (inValue == mMaxValue) {
            mUpdateQueue.addAction( this, notifyFinished );
        }        
        mUpdateQueue.run();
    }
    
    /**
    Updates with the maximum value.
    */
    public function setDone () : Void {
        update(mMaxValue);
    }
    
    /**
    Forces the progress indicator to finish drawing. Will send a {@link ProgressIndicatorEvent#FINISHED} message.
    */
    public function finish () : Void {
        setDone();
        stop();
    }
    
    /**
    Stops the progress indicator, without sending a {@link ProgressIndicatorEvent#FINISHED} message.
    */
    public function stop () : Void {
        mUpdateQueue.quit();
        notifyFinished();
    }
    
    /**
    
    */
    public function toString () : String {
        return "playground.classes.ui.ProgressIndicator";
    }
    
    // PRIVATE METHODS
    
    /**
    
    */
    private function update (inValue:Number) : Void {
        mAmountDrawn = inValue;
    }
    
    /**
    
    */
    private function notifyFinished () : Void {
        dispatchEvent( new ProgressIndicatorEvent(ProgressIndicatorEvent.FINISHED, this) );
    }
    
}