Updater – classes para lidar com o tempo no flash

/**
 * @author Pedro Paulo Almeida
 * For usage details please visit http://www.pedropauloalmeida.com.br
 * This software is free and you can use or modify it as you need to.
 */
package br.com.pedropauloalmeida.timeflow {
 
	import flash.events.Event;
	import flash.events.EventDispatcher;
	import flash.utils.Timer;
	import flash.events.TimerEvent;
 
	public class Updater extends EventDispatcher {
 
		private var _interCall			:Number;
		private var _timer				:Timer;
		private var _loops				:int;
		private var _step				:int;
 
		static public const ON_UPDATE_TIMER:String 		= 'ON_UPDATE_TIMER';
		static public const ON_UPDATE_FINISHED:String 	= 'ON_UPDATE_FINISHED';
 
		/**
		 * Constrói um novo objeto Updater.
		 * Este objeto será usado para as transações de intervalo de tempo.
		 * Ao construir ele tem um tempo default de intervalo de 10s.
		 * 
		 */
		public function Updater() {
			super();
			this._interCall = 10000;
		}
 
 
//=========================================================================== Métodos de criação de timers:
		/**
		 * Cria um novo timer.
		 * @param	loops 	-> número de vezes que o timer vai se repetir antes de se encerrar
		 * @param	sec 	-> intervalo, em segundos, para o timer
		 */
		public function createFiniteTimer(loops:int = 1, sec:Number = 10):void {
			this.resetTimerSettings();
			try {
				if (loops < 1) throw new UpdaterError("Criando um timer finito com loops = 0");				
				this._interCall 	= sec * 1000;
				this._loops 		= loops;
				this.doTimer();
			} catch (e:UpdaterError) {
				//trace("catch: " + e);				
			}			
		}
 
		/**
		 * Cria um timer 'infinito'
		 * @param	sec -> intervalo, em segundos, para o timer
		 */
		public function createInfiniteTimer(sec:Number = 10):void {
			this.resetTimerSettings();
			this._interCall = sec * 1000;
			this.doTimer();
		}
 
		/**
		 * Cria um novo timer, infinito, com intervalos de minuto.
		 * @param	min -> de quantos em quantos minutos é o ciclo do timer
		 */
		public function createInfiniteMinuteTimer(min:int = 1):void {
			this.resetTimerSettings();
			this._interCall = min * 60000;
			this.doTimer();
		}
 
		/**
		 * Cria um timer regressivo que roda de um step até "zero".
		 * @param	loops -> número de vezes que o timer vai se repetir
		 * @param	sec -> intervalo do ciclo do timer em segundos
		 */
		public function createRegressiveTimerUpTo(loops:int = 10, sec:Number = 1):void {
			this.resetTimerSettings();
			this._step		 	= loops;
			this._loops 		= loops;
			this._interCall		= sec * 1000;
			this.doTimer(false);
		}	
 
//=========================================================================== Manipulação de timers:		
		/**
		 * Pára o timer deste Updater.
		 */
		public function stopTimer():void {
			if (this._timer == null) return;
			if (this._timer.running) this.endTimer();
		}
 
		public function pauseTimer():Boolean {
			if (this._timer != null && this._timer.running) {
				this._timer.stop();
				return true;
			}
			return false
		}
 
		public function restartPausedTimer(pro:Boolean = true):Boolean {
			var success:Boolean = false;
			try {
				if (this._timer == null || this._timer.running || this._step <= 0 || this._interCall <= 0) {
					throw new UpdaterError("Tentando restartar timer com step 0 ou interCall 0");
				}
				this.doTimer(pro);
				success = true;
			} catch (e:UpdaterError) {
				success = false;
			}
			return success;
		}
 
		/**
		 * Se o timer estiver rodando, manter o step e o target, mas com um novo
		 * tempo de intervalo de delay.
		 * @param	sec -> novo intervalo do timer em andamento
		 * @param 	pro -> se o timer tem contagem regressiva ou progressiva. Default = progressivo
		 */
		public function modifyTimerIntervalTo(sec:Number, pro:Boolean = true):void {
			try {
				if (!this.isRunning()) {
					throw new UpdaterError("Tentando modificar o intervalo de um timer que está parado");
				}
				this._interCall = sec * 1000;
				this._timer.stop();
				this.doTimer(pro);
			} catch (e:UpdaterError) {
				// erro de reinicialização do timer:
				//trace(e);
			}
		}
 
		public function isRunning():Boolean {
			if (this._timer == null) return false;
			return this._timer.running;
		}
 
//=========================================================================== Private build timers:		
 
		private function resetTimerSettings():void {
			this._step 				= 0;
			this._interCall 		= 0;
			this._loops 			= 0;
			if (this._timer != null) {
				this._timer.stop();
				if (this._timer.hasEventListener(TimerEvent.TIMER)) {
					this._timer.removeEventListener(TimerEvent.TIMER, timerStep);
					this._timer.removeEventListener(TimerEvent.TIMER, regressiveStep);
				}
				this._timer = null;
			}
		}
 
		private function doTimer(pro:Boolean = true):void {
			this._timer = new Timer(this._interCall, this._loops);
			(pro) ? this._timer.addEventListener(TimerEvent.TIMER, timerStep) : this._timer.addEventListener(TimerEvent.TIMER, regressiveStep);
			this._timer.addEventListener(TimerEvent.TIMER_COMPLETE, endTimer);
			this._timer.start();
		}
 
		private function endTimer(e:TimerEvent = null):void {
			if (this.hasEventListener(ON_UPDATE_FINISHED)) {
				this.dispatchEvent(new Event(ON_UPDATE_FINISHED));
			}
			this.resetTimerSettings();		
		}	
 
//=========================================================================== Event flow:		
 
		/**
		 * Este método é chamado a cada ciclo do objeto timer
		 * @param	e -> evento TimerEvent
		 */
		private function timerStep(e:TimerEvent):void {
			this._step++;
			super.dispatchEvent(new Event(ON_UPDATE_TIMER));
			if (this._loops > 0 && this._step == this._loops) {
				this._timer.stop();
				this.endTimer();
			}
		}
 
		/**
		 * Este método é chamado a cada ciclo de um regressive timer
		 * @param	e -> evento TimerEvent
		 */
		private function regressiveStep(e:TimerEvent):void {
			this._step--;
			super.dispatchEvent(new Event(ON_UPDATE_TIMER));
			if (this._step == 0) this.resetTimerSettings();
		}
 
 
//=========================================================================== Get Step:	
		public function get step():int { return this._step; }
 
 
 
//=========================================================================== ToString:						
		override public function toString():String {
			var s:String = "Updater.as:\n";
			s += "_interCall: " + _interCall.toString() + "\n";
			s += "_timer: " + _timer.toString() + "\n";
			s += "\n\n";
			return s;
		}
 
	}
 
}

/**
 * @author Pedro Paulo Almeida
 * For usage details please visit http://www.pedropauloalmeida.com.br
 * This software is free and you can use or modify it as you need to.
 */
package br.com.pedropauloalmeida.timeflow {
 
	public class UpdaterError extends Error {
 
		public function UpdaterError(msg:String, id:int = 0) {
			super("UpdaterError: " + msg, id);
		}
 
	}
 
}

import br.com.pedropauloalmeida.timeflow.*;

// crio uma instância do Updater
var updater:Updater = new Updater();
// adiciono um listener para cada ciclo da contagem para o método "stepTimer":
updater.addEventListener(Updater.ON_UPDATE_TIMER, stepTimer);
// adiciono um listener para o fim do ciclo da contagem para o método "endTimer":
updater.addEventListener(Updater.ON_UPDATE_FINISHED, endTimer);
 
/* nesse caso eu crio um timer finito em um total de 10 loops que serão executados a cada
*  1 segundo. Note bem que nesse caso eu passo o tempo em SEGUNDOS e não em
*  milissegundos, como no Timer nativo do Flash. Isso porque normalmente eu geralmente
*  me sinto mais à vontade lendo tempos em segundos. Mas você pode ter valores menores
*  do que 1 segundo. Por exemplo, para meio segundo basta passar 0.5 */
updater.createFiniteTimer(10, 1);
 
private function stepTimer(evt:Event):void {
	trace("o updater está no passo: " + updater.step);
}
 
private function endTimer(evt:Event):void {
	trace("o updater terminou sua contagem");
}

// crio uma instância do Updater
var updater:Updater = new Updater();
// adiciono um listener para cada ciclo da contagem para o método "stepTimer":
updater.addEventListener(Updater.ON_UPDATE_TIMER, stepTimer);
// adiciono um listener para o fim do ciclo da contagem para o método "endTimer":
updater.addEventListener(Updater.ON_UPDATE_FINISHED, endTimer);
 
// Crio uma contagem regressiva de '10' a '0' com intervalos de 1 segundo:
updater.createRegressiveTimerUpTo(10, 1);
 
private function stepTimer(evt:Event):void {
	trace("o updater está no passo: " + updater.step);
}
 
private function endTimer(evt:Event):void {
	trace("o updater terminou sua contagem");
}

// pausa o timer:
var updater = new Updater();
updater.createFiniteTimer(10, 1);
 
// pausando o timer:
updater.pauseTimer();
// caso queira reiniciar, basta chamar
updater.restartPausedTimer();
// se o timer for de contagem regressiva, parâmetro 'false':
updater.restartPausedTimer(false);

/* altero o andamento do updater para meio segundo. Como o timer nesse
exemplo é progressivo, omito o segundo parâmetro do método */
updater.modifyTimerIntervalTo(0.5);