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.
__/ REQUIREMENTS \__
ActionScript 3.0 (or later)
__/ IMPORTS \__
com.bnm.api.CoreData flash.utils.* flash.events.TimerEvent
__/ EXTENDS \__
com.bnm.api.CoreData
__/ IMPLEMENTS \__
nothing
__/ NOTICE \__
©opyright 2008 Bay New Media. All rights, as stipulated in the The MIT License, are reserved.
This ActionScript library is licensed and released under the MIT License (http://www.opensource.org
Please visit http://www.baynewmedia.com/ or email contact@baynewmedia.com for information, questions, concerns, or bug reports.
__/ NOTES \__
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/
The BNMAPI is officially available (primary sources) on Source Forge (http://sourceforge.net/projects/bnmapi/), on the Bay New Media site (http;//www.baynewmedia.com/), on the PeaBee project site (http://www.peabee.com/), and through the Bay New Media SVM repository server (visit http://www.baynewmedia.com/ for more information). Downloads from other sources may not be complete or up-to-date.
If you’re interested in joining the BNMAPI project in any capacity (development, testing, distribution, etc.), please visit us on Source Forge or the Bay New Media web site.
| TimeObject | Stores and automatically calculates time values for hours, minutes, seconds, and milliseconds. |
| Variables | |
| _hours | (uint): Stores the total calculated and adjusted hours for the time object. |
| _minutes | (uint): Stores the total calculated and adjusted minutes for the time object. |
| _seconds | (uint): Stores the total calculated and adjusted seconds for the time object. |
| _milliSeconds | (uint): Stores the total calculated and adjusted milliseconds for the time object. |
| _totalMilliSeconds | (uint): Stores the total calculated and adjusted total, agregated milliseconds for the time object. |
| _intervalTimer | (Timer) Timer instance used for broadcasting countdown timer updates at a regular interval. |
| _countDownTimer | (Timer) Timer instance used for counting down to a time of 00:00:00.00. |
| _countUpTimer | (Timer) Timer instance used for counting up indefinitely. |
| _lastTimerMilliseconds | (int) Stores the number of milliseconds in the internal Flash timer at the last time it was checked. |
| _elapsedMilliseconds | |
| _timerInitData | (Object) Stores the initial _hours, _minutes, _seconds, and _milliSeconds values set at the time when the countdown timer started. |
| Functions and Properties | |
| TimeObject | Creates a new TimeObject instance. |
| getTimeString | Returns a formatted time string based on the time value of the time object and the specified format string supplied as a parameter. |
| startCountDown | Starts a countdown timer based on the current time settings of the time object (e.g. |
| startCountUp | Starts a countup timer. |
| stopCountDown | Stops the count down timer. |
| stopCountUp | Stops the count up timer. |
| resetCountDown | Resets the count down timer. |
| resetCountUp | Resets the countup timer. |
| onCountDownTick | Invoked on every countdown interval tick. |
| onCountUpTick | Invoked on every countup interval tick. |
| onCountDownComplete | Invoked when the countdown timer completes. |
| calculateTotalMilliseconds | Calculates the total milliseconds from the appropriate class member variables. |
| set milliseconds | Sets the number of milliseconds in the time object. |
| milliseconds | |
| set seconds | Sets the number of seconds in the time object. |
| seconds | |
| set minutes | Sets the number of minutes in the time object. |
| minutes | |
| set hours | Sets the number of hours in the time object. |
| hours | |
| get milliseconds | Returns the milliseconds component of the object. |
| milliseconds | |
| get seconds | Returns the seconds component of the object. |
| seconds | |
| get minutes | Returns the minutes component of the object. |
| minutes | |
| get hours | Returns the hours component of the object. |
| hours | |
| set totalHours | Sets the total hours value for the whole time object. |
| totalHours | |
| set totalMinutes | Sets the total minutes value for the whole time object. |
| totalMinutes | |
| set totalSeconds | Sets the total seconds value for the whole time object. |
| totalSeconds | |
| set totalMilliseconds | Sets the total milliseconds value for the whole time object. |
| totalMilliseconds | |
| get totalHours | Returns the total calculated hours for the time object. |
| totalHours | |
| get totalMinutes | Returns the total calculated minutes for the time object. |
| totalMinutes | |
| get totalSeconds | Returns the total calculated seconds for the time object. |
| totalSeconds | |
| get totalMilliseconds | Returns the total calculated milliseconds for the time object. |
| totalMilliseconds | |
| get elapsedHours | Returns the total number of elapsed hours for the current count down timer. |
| elapsedHours | |
| get elapsedMinutes | Returns the total number of elapsed minutes for the current count down timer. |
| elapsedMinutes | |
| get elapsedSeconds | Returns the total number of elapsed seconds for the current count down timer. |
| elapsedSeconds | |
| get elapsedMilliseconds | Returns the total number of elapsed milliseconds for the current count down timer. |
| elapsedMilliseconds |
public function TimeObject( ... args )
Creates a new TimeObject instance. This instance can be used for a variety of time and relative time related tasks.
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.
TimeObject: A newly created class instance.
nothing
nothing
no
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.
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”.
String: The time string representation of the time object, as specified by the format string.
nothing
nothing
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.
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.
nothing
”TimeObject.ONSTARTCOUNTDOWN”
nothing
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.
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.
nothing
”TimeObject.ONSTARTCOUNTUP”
nothing
public function stopCountDown():void
Stops the count down timer. This does not reset the time object so the last elapsed time remains until resetCountDown is invoked.
none
nothing
”TimeObject.ONSTOPCOUNTDOWN”
nothing
public function stopCountUp():void
Stops the count up timer. This does not reset the time object so the last elapsed time remains until resetCountUp is invoked.
none
nothing
”TimeObject.ONSTOPCOUNTUP”
nothing
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.
none
nothing
”TimeObject.ONRESETCOUNTDOWN”
nothing
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.
none
nothing
”TimeObject.ONRESETCOUNTDOWN”
nothing
public function onCountDownTick ( eventObj: TimerEvent ):void
Invoked on every countdown interval tick. This method broadcasts regular updates to all listeners with updated elapsed time and the new remaining time in the time object.
eventObj (TimerEvent, required): A standard <TimerEvent> object instance.
nothing
”TimeObject.ONCOUNTDOWNTICK”
nothing
public function onCountUpTick ( eventObj: TimerEvent ):void
Invoked on every countup interval tick. This method broadcasts regular updates to all listeners with updated elapsed time.
eventObj (TimerEvent, required): A standard <TimerEvent> object instance.
nothing
”TimeObject.ONCOUNTUPTICK”
nothing
public function onCountDownComplete( eventObj: TimerEvent ):void
Invoked when the countdown timer completes. This may either happen as the result of the countdown <Timer> instance elapsing, or the calculated internal timer elapsing to 0.
eventObj (TimerEvent, required): A standard <TimerEvent> object instance.
nothing
”TimeObject.ONCOUNTDOWNEND”
nothing
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.
none
nothing
nothing
no
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.
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.
nothing
nothing
no
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.
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.
nothing
nothing
no
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.
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.
nothing
nothing
no
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.
hourVal (uint, required): The number of hours to apply to the time object.
nothing
nothing
no
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.
uint: The number of milliseconds in the time object, from 0 to 999.
nothing
nothing
no
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.
uint: The number of seconds in the time object, from 0 to 59.
nothing
nothing
no
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.
uint: The number of minutes in the time object, from 0 to 59.
nothing
nothing
no
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.
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.
”TimeObject.ERROR”
nothing
no
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.
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.
”TimeObject.ERROR”
nothing
no
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.
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.
”TimeObject.ERROR”
nothing
no
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.
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.
”TimeObject.ERROR”
nothing
no
Returns the total calculated hours for the time object. This is an aggregate value of hours, minutes, seconds, and milliseconds.
Number: The total aggregated hours for the time object. This value may be fractional to include smaller values like minutes, seconds, and milliseconds.
nothing
nothing
no
Returns the total calculated minutes for the time object. This is an aggregate value of hours, minutes, seconds, and milliseconds.
Number: The total aggregated minutes for the time object. This value may be fractional to include smaller values like seconds and milliseconds.
nothing
nothing
no
Returns the total calculated seconds for the time object. This is an aggregate value of hours, minutes, seconds, and milliseconds.
Number: The total aggregated seconds for the time object. This value may be fractional to include smaller values like milliseconds.
nothing
nothing
no
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.
uint: The number of elapsed hours for the count down timer.
nothing
nothing
no
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.
uint: The number of elapsed minutes for the count down timer.
nothing
nothing
no
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.
uint: The number of elapsed seconds for the count down timer.
nothing
nothing
no
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.
uint: The number of elapsed milliseconds for the count down timer.
nothing
nothing
no
(uint): Stores the total calculated and adjusted hours for the time object.
private var _hours: uint
(uint): Stores the total calculated and adjusted minutes for the time object.
private var _minutes: uint
(uint): Stores the total calculated and adjusted seconds for the time object.
private var _seconds: uint
(uint): Stores the total calculated and adjusted milliseconds for the time object.
private var _milliSeconds: uint
(uint): Stores the total calculated and adjusted total, agregated milliseconds for the time object.
private var _totalMilliSeconds: uint
(Timer) Timer instance used for broadcasting countdown timer updates at a regular interval.
private var _intervalTimer: Timer
(Timer) Timer instance used for counting down to a time of 00:00:00.00.
private var _countDownTimer: Timer
(Timer) Timer instance used for counting up indefinitely.
private var _countUpTimer: Timer
(int) Stores the number of milliseconds in the internal Flash timer at the last time it was checked.
private var _lastTimerMilliseconds: int
private var _elapsedMilliseconds: uint
(Object) Stores the initial _hours, _minutes, _seconds, and _milliSeconds values set at the time when the countdown timer started.
private var _timerInitData: Object
Creates a new TimeObject instance.
public function TimeObject( ... args )
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 getTimeString( ... args ):String
Starts a countdown timer based on the current time settings of the time object (e.g.
public function startCountDown( ... args ):void
Starts a countup timer.
public function startCountUp( ... args ):void
Stops the count down timer.
public function stopCountDown():void
Stops the count up timer.
public function stopCountUp():void
Resets the count down timer.
public function resetCountDown( ... args ):void
Resets the countup timer.
public function resetCountUp( ... args ):void
Invoked on every countdown interval tick.
public function onCountDownTick ( eventObj: TimerEvent ):void
Invoked on every countup interval tick.
public function onCountUpTick ( eventObj: TimerEvent ):void
Invoked when the countdown timer completes.
public function onCountDownComplete( eventObj: TimerEvent ):void
Calculates the total milliseconds from the appropriate class member variables.
private function calculateTotalMilliseconds():void
public function set milliseconds ( msVal: uint )
public function set seconds( secondVal: uint )
public function set minutes ( minuteVal: uint )
public function set hours( hourVal: uint )
public function set totalHours( thVal: Number )
public function set totalMinutes( tmVal: Number )
public function set totalSeconds( tsVal: Number )
public function set totalMilliseconds( tmsVal: uint )
public function get elapsedHours():uint
public function get elapsedMinutes():uint
public function get elapsedSeconds():uint
public function get elapsedMilliseconds():uint