TimeObject

Stores and automatically calculates time values for hours, minutes, seconds, and milliseconds. This class povides easy methods for performing time-based calculations and conversions based on these values. It is generic and may be used in a variety of ways.

This ActionScript library is licensed and released under the MIT License (http://www.opensource.org/licenses/mit-license.php). Please refer to the accompanying text file “license.txt”, which should be distributed with every package and version of this library, for information on usage, distribution, copying, and other important information.

This class is commented using the NaturalDocs documentation system. It is intended to be easily read both from the direct source code and from an adaptation that is generated as hyperlinked HTML. The NaturalDocs specification used in this class’ documentation is version 1.35 though older versions may probably be used safely. For more information, please visit: http://www.naturaldocs.org/

Variables

_hours

(uint): Stores the total calculated and adjusted hours for the time object.

_minutes

private var _minutes: uint

(uint): Stores the total calculated and adjusted minutes for the time object.

_seconds

private var _seconds: uint

(uint): Stores the total calculated and adjusted seconds for the time object.

_milliSeconds

private var _milliSeconds: uint

(uint): Stores the total calculated and adjusted milliseconds for the time object.

_totalMilliSeconds

private var _totalMilliSeconds: uint

(uint): Stores the total calculated and adjusted total, agregated milliseconds for the time object. This is the total time represented by hours, minutes, seconds, and milliseconds.

_intervalTimer

private var _intervalTimer: Timer

(Timer) Timer instance used for broadcasting countdown timer updates at a regular interval.

_countDownTimer

private var _countDownTimer: Timer

(Timer) Timer instance used for counting down to a time of 00:00:00.00.

_countUpTimer

private var _countUpTimer: Timer

(Timer) Timer instance used for counting up indefinitely.

_lastTimerMilliseconds

private var _lastTimerMilliseconds: int

(int) Stores the number of milliseconds in the internal Flash timer at the last time it was checked. The delta of the current time against the stored time is used to calculate elapsed time rather than calculating at 1 millisecond ticks.

_elapsedMilliseconds

private var _elapsedMilliseconds: uint

Variable: _elapsedMilliseconds *(uint) The number of elapsed milliseconds while the count down timer is running. This value is to calculate elapsed values such

as hours, minutes, and seconds.

_timerInitData

private var _timerInitData: Object

(Object) Stores the initial _hours, _minutes, _seconds, and _milliSeconds values set at the time when the countdown timer started. These values are used to reset the timer or restore original values.

Functions and Properties

TimeObject

public function TimeObject(

...

args

)

Creates a new TimeObject instance. This instance can be used for a variety of time and relative time related tasks.

Parameters

timeString (String, optional): A time string that can be converted to time values. Most common string formats are accepted including short formats (hh:mm) and longer formats (hh:mm:ss:ms). The parsers will attempt to recognize the time elements you’ve included. Elements are parsed in the order hours, hours:minutes, hours:minutes:seconds, and hours:minutes:seconds:milliseconds.

Returns

TimeObject: A newly created class instance.

Broadcasts

nothing

Throws

nothing

Bubbles

no

getTimeString

public function getTimeString(

...

args

):String

Returns a formatted time string based on the time value of the time object and the specified format string supplied as a parameter.

Parameters

format (String, optional): Specifies the format of the output time string. All characters in the time string that are not one of the special format characters listed below will be included, as specified, in the output string. Format characters include: “h” - Hours with no leading 0 if less than 10. “H” - Hours with leading 0 if less than 10. “m” - Minutes with no leading 0 if less than 10. “M” - Minutes with leading 0 if less than 10. “s” - Seconds with no leading 0 if less than 10. “S” - Seconds with leading 0 if less than 10. “l” - Milliseconds. Leading 0 is not used in this value. For example, the string “H:M:S.l” would produce (if the time object had these time values): “09:12:01.999” Default format string is “H:M”.

Returns

String: The time string representation of the time object, as specified by the format string.

Broadcasts

nothing

Throws

nothing

startCountDown

public function startCountDown(

...

args

):void

Starts a countdown timer based on the current time settings of the time object (e.g. hours, minutes, and seconds). When the countdown timer reaches 00:00:00.00, the timer is stopped. A special set of getters is provided for displaying the count up values which are essentially the invert of the core count down values. A double precision system is used to calculate the elapsed time so that if the internal application timer calculation indicates that the countdown timer should be complete, it stops the timer even if the <Timer> instance is not necessarily complete. The <Timer> instance, however, is taken as authoritative if it completes first since the interval counter is likely slower and therefore not as precise. Setting any of the time object’s values (such as totalHours) will affect the running timer.

Parameters

interval (uint, optional): Specifies a notification interval, in milliseconds, at which the time object will broadcast updates. It is highly recommended to keep this value greater than 100 milliseconds to prevent bombarding the event system with too many events. Setting this value to 0 disables the count down timer tick and causes the countdown to broadcast only when it is complete.

Returns

nothing

Broadcasts

”TimeObject.ONSTARTCOUNTDOWN”

Throws

nothing

See also

startCountUp

public function startCountUp(

...

args

):void

Starts a countup timer. This is an indefinite timer that will continue to count until it is stopped. This does not reset the current time settings of the object since this command may be used to re-start a previous counter. When starting a new counter, be sure to call resetCountUp first in order to clear the current time object and reset all values to 0. Since countup timers don’t have a set end, a TIME_COMPLETE event will never be used and so this timer is never assumed to be complete. Rather, the called must control the completion state of this instance.

Parameters

interval (uint, optional): Specifies a notification interval, in milliseconds, at which the time object will broadcast updates. It is highly recommended to keep this value greater than 100 milliseconds to prevent bombarding the event system with too many events. Setting this value to 0 disables the count down timer tick and causes the countup to broadcast only when it is complete.

Parameters

Returns

Broadcasts

Throws

See also

resetCountDown

public function resetCountDown(

...

args

):void

Resets the count down timer. This resets the time object value to the state it was at just before the count down timer started. The count down timer is not affected so that if it’s running, it will continue to run.

Parameters

none

Returns

nothing

Broadcasts

”TimeObject.ONRESETCOUNTDOWN”

Throws

nothing

See also

resetCountUp

public function resetCountUp(

...

args

):void

Resets the countup timer. This resets the time object value to 0, the initial state of the counter. This should be called whenever the timer is restarted as this is not done automatically by starting the counter.

Parameters

Returns

nothing

Broadcasts

”TimeObject.ONCOUNTDOWNEND”

Throws

nothing

calculateTotalMilliseconds

private function calculateTotalMilliseconds():void

Calculates the total milliseconds from the appropriate class member variables. All private member variables are updated so that all getters and other output methods will have correctly calculated time values.

Parameters

none

Returns

nothing

Throws

nothing

Bubbles

no

set milliseconds

Sets the number of milliseconds in the time object. This value only affects milliseconds absolutely, no other values are affected. In other words, updating milliseconds does not affect seconds, minutes, or hours. Milliseconds are converted to proper values so that 1001 milliseconds becomes 1 milliseconds. This is useful for setting individual components of the time object without affecting the overall time value.

Parameters

msVal (uint, required): The number of milliseconds to apply to the time object. Valid values are 0 to 999. All other values will have a modulo calculation applied to it to create the correct (in range) value.

Broadcasts

nothing

Throws

nothing

Bubbles

no

milliseconds

public function set milliseconds (

msVal:

uint

)

set seconds

Sets the number of seconds in the time object. This value only affects seconds absolutely, no other values are affected. In other words, updating seconds does not affect milliseconds, minutes, or hours. Seconds are converted to proper values so that 61 seconds becomes 1 second. This is useful for setting individual components of the time object without affecting the overall time value.

Parameters

secondVal (uint, required): The number of seconds to apply to the time object. Valid values are 0 to 59. All other values will have a modulo calculation applied to it to create the correct (in range) value.

Broadcasts

nothing

Throws

nothing

Bubbles

no

seconds

public function set seconds(

secondVal:

uint

)

set minutes

Sets the number of minutes in the time object. This value only affects minutes absolutely, no other values are affected. In other words, updating minutes does not affect milliseconds, seconds, or hours. Minutes are converted to proper values so that 61 minutes becomes 1 minute. This is useful for setting individual components of the time object without affecting the overall time value.

Parameters

minuteVal (uint, required): The number of minutes to apply to the time object. Valid values are 0 to 59. All other values will have a modulo calculation applied to it to create the correct (in range) value.

Broadcasts

nothing

Throws

nothing

Bubbles

no

minutes

public function set minutes (

minuteVal:

uint

)

set hours

Sets the number of hours in the time object. Any number of hours may be set for the class, but fractional values will only have their whole part used. That is, minute, second, and millisecond calculations aren’t applied.

Parameters

hourVal (uint, required): The number of hours to apply to the time object.

Broadcasts

nothing

Throws

nothing

Bubbles

no

hours

public function set hours(

hourVal:

uint

)

get milliseconds

Returns the milliseconds component of the object. This is not the total, aggregated milliseconds but rather the portion of the time object representing the left-over milliseconds from total time calculations.

Returns

uint: The number of milliseconds in the time object, from 0 to 999.

Broadcasts

nothing

Throws

nothing

Bubbles

no

milliseconds

public function get milliseconds ():uint

get seconds

Returns the seconds component of the object. This is not the total, aggregated seconds but rather the portion of the time object representing the left-over seconds from total time calculations.

Returns

uint: The number of seconds in the time object, from 0 to 59.

Broadcasts

nothing

Throws

nothing

Bubbles

no

seconds

public function get seconds ():uint

get minutes

Returns the minutes component of the object. This is not the total, aggregated minutes but rather the portion of the time object representing the left-over minutes from total time calculations.

Returns

uint: The number of minutes in the time object, from 0 to 59.

Broadcasts

nothing

Throws

nothing

Bubbles

no

minutes

public function get minutes ():uint

get hours

Returns the hours component of the object. This is not the total, aggregated hours but rather the portion of the time object representing the left-over hours from total time calculations.

Returns

uint: The number of hours in the time object.

Broadcasts

nothing

Throws

nothing

Bubbles

no

hours

public function get hours ():uint

set totalHours

Sets the total hours value for the whole time object. This is translated to the total number of hours, minutes, seconds, and milliseconds (especially when fractional values are used). Because this value is manipulated before being stored, non whole values (fractional values) will result in different values on the getter. For example, setting 36 hours will return simply 36 hours and 0 minutes. However, setting 36.5 hours will result in 36 hours and 30 minutes. Because all values area affected, setting any “total” value will effectively overwrite any other set values.

Parameters

thVal (Number): The total number of hours to assign to the time object. May be fractional, which will be translated to minutes, seconds, and milliseconds where required. Otherwise, minutes, seconds, and milliseconds will be set to 0.

Broadcasts

”TimeObject.ERROR”

Throws

nothing

Bubbles

no

totalHours

public function set totalHours(

thVal:

Number

)

set totalMinutes

Sets the total minutes value for the whole time object. This is translated to the total number of hours, minutes, seconds, and milliseconds (especially when fractional values are used or minutes exceeds 59). For example, setting 59 minutes will return simply 59 minutes and 0 hours. However, setting 60 minutes will cause 1 hour and 0 minutes to be returned. Because all values area affected, setting any “total” value will effectively overwrite any other set values.

Parameters

tmVal (Number): The total number of minutes to assign to the time object. May be fractional, which will be translated to hours, minutes, seconds, and milliseconds where required. Otherwise, hours, minutes, seconds, and milliseconds will be set to 0.

Broadcasts

”TimeObject.ERROR”

Throws

nothing

Bubbles

no

totalMinutes

public function set totalMinutes(

tmVal:

Number

)

set totalSeconds

Sets the total seconds value for the whole time object. This is translated to the total number of hours, minutes, seconds, and milliseconds (especially when fractional values are used or seconds exceeds 59). For example, setting 59 seconds will return simply 59 seconds and 0 minutes. However, setting 60 seconds will cause 1 minute and 0 seconds to be returned. Because all values area affected, setting any “total” value will effectively overwrite any other set values.

Parameters

tsVal (Number): The total number of seconds to assign to the time object. May be fractional, which will be translated to hours, minutes, seconds, and milliseconds where required. Otherwise, hours, minutes, seconds, and milliseconds will be set to 0.

Broadcasts

”TimeObject.ERROR”

Throws

nothing

Bubbles

no

totalSeconds

public function set totalSeconds(

tsVal:

Number

)

set totalMilliseconds

Sets the total milliseconds value for the whole time object. This is translated to the total number of hours, minutes, seconds, and milliseconds (especially when fractional values are used or milliseconds exceeds 999). For example, setting 999 milliseconds will return simply 999 milliseconds and 0 seconds. However, setting 1000 milliseconds will cause 1 second and 0 milliseconds to be returned. Because all values area affected, setting any “total” value will effectively overwrite any other set values.

Parameters

tmsVal (uint): The total number of milliseconds to assign to the time object. May not be fractional since this is the lowest unit of measure in the time object. This value effectively resets the time object’s hours, minutes, seconds, and milliseconds values to the appropriate converted value.

Broadcasts

”TimeObject.ERROR”

Throws

nothing

Bubbles

no

totalMilliseconds

public function set totalMilliseconds(

tmsVal:

uint

)

get totalHours

Returns the total calculated hours for the time object. This is an aggregate value of hours, minutes, seconds, and milliseconds.

Returns

Number: The total aggregated hours for the time object. This value may be fractional to include smaller values like minutes, seconds, and milliseconds.

Broadcasts

nothing

Throws

nothing

Bubbles

no

totalHours

public function get totalHours():Number

get totalMinutes

Returns the total calculated minutes for the time object. This is an aggregate value of hours, minutes, seconds, and milliseconds.

Returns

Number: The total aggregated minutes for the time object. This value may be fractional to include smaller values like seconds and milliseconds.

Broadcasts

nothing

Throws

nothing

Bubbles

no

totalMinutes

public function get totalMinutes():Number

get totalSeconds

Returns the total calculated seconds for the time object. This is an aggregate value of hours, minutes, seconds, and milliseconds.

Returns

Number: The total aggregated seconds for the time object. This value may be fractional to include smaller values like milliseconds.

Broadcasts

nothing

Throws

nothing

Bubbles

no

totalSeconds

public function get totalSeconds():Number

get totalMilliseconds

Returns the total calculated milliseconds for the time object. This is an aggregate value of hours, minutes, seconds, and milliseconds.

Returns

uint: The total aggregated milliseconds for the time object.

Broadcasts

nothing

Throws

nothing

Bubbles

no

totalMilliseconds

public function get totalMilliseconds():uint

get elapsedHours

Returns the total number of elapsed hours for the current count down timer. This value is valid while the count down timer is running, or when it has stopped but before teh resetCountDown method is invoked.

Returns

uint: The number of elapsed hours for the count down timer.

Broadcasts

nothing

Throws

nothing

Bubbles

no

elapsedHours

public function get elapsedHours():uint

get elapsedMinutes

Returns the total number of elapsed minutes for the current count down timer. This value is valid while the count down timer is running, or when it has stopped but before the resetCountDown method is invoked.

Returns

uint: The number of elapsed minutes for the count down timer.

Broadcasts

nothing

Throws

nothing

Bubbles

no

elapsedMinutes

public function get elapsedMinutes():uint

get elapsedSeconds

Returns the total number of elapsed seconds for the current count down timer. This value is valid while the count down timer is running, or when it has stopped but before the resetCountDown method is invoked.

Returns

uint: The number of elapsed seconds for the count down timer.

Broadcasts

nothing

Throws

nothing

Bubbles

no

elapsedSeconds

public function get elapsedSeconds():uint

get elapsedMilliseconds

Returns the total number of elapsed milliseconds for the current count down timer. This value is valid while the count down timer is running, or when it has stopped but before the resetCountDown method is invoked.

Returns

uint: The number of elapsed milliseconds for the count down timer.

Broadcasts

nothing

Throws

nothing

Bubbles

no

elapsedMilliseconds

public function get elapsedMilliseconds():uint

Provides facilities for data checking and conversion for all types of Flash data types.

private var _hours: uint

(uint): Stores the total calculated and adjusted hours for the time object.

private var _minutes: uint

(uint): Stores the total calculated and adjusted minutes for the time object.

private var _seconds: uint

(uint): Stores the total calculated and adjusted seconds for the time object.

private var _milliSeconds: uint

(uint): Stores the total calculated and adjusted milliseconds for the time object.

private var _totalMilliSeconds: uint

(uint): Stores the total calculated and adjusted total, agregated milliseconds for the time object.

private var _intervalTimer: Timer

(Timer) Timer instance used for broadcasting countdown timer updates at a regular interval.

private var _countDownTimer: Timer

(Timer) Timer instance used for counting down to a time of 00:00:00.00.

private var _countUpTimer: Timer

(Timer) Timer instance used for counting up indefinitely.

private var _lastTimerMilliseconds: int

(int) Stores the number of milliseconds in the internal Flash timer at the last time it was checked.

private var _elapsedMilliseconds: uint

private var _timerInitData: Object

(Object) Stores the initial _hours, _minutes, _seconds, and _milliSeconds values set at the time when the countdown timer started.

public function TimeObject(

...

args

)

Creates a new TimeObject instance.

public function getTimeString(

...

args

):String

Returns a formatted time string based on the time value of the time object and the specified format string supplied as a parameter.

public function startCountDown(

...

args

):void

Starts a countdown timer based on the current time settings of the time object (e.g.

public function startCountUp(

...

args

):void

Starts a countup timer.

public function stopCountDown():void

Stops the count down timer.

public function stopCountUp():void

Stops the count up timer.

public function resetCountDown(

...

args

):void

Resets the count down timer.

public function resetCountUp(

...

args

):void

Resets the countup timer.

public function onCountDownTick (

eventObj:

TimerEvent

):void

Invoked on every countdown interval tick.

public function onCountUpTick (

eventObj:

TimerEvent

):void

Invoked on every countup interval tick.

public function onCountDownComplete(

eventObj:

TimerEvent

):void

Invoked when the countdown timer completes.

private function calculateTotalMilliseconds():void

Calculates the total milliseconds from the appropriate class member variables.