quicktime.app.time
Class Timer

java.lang.Object
  |
  +--quicktime.app.time.Timer
All Implemented Interfaces:
Timeable

public class Timer
extends java.lang.Object
implements Timeable

This class provides timing services for either a subclass or a target object that implements the Ticklish interface. The Timer invokes the tickle method based on the rate that it is ticking and the scale and period of the timer itself. For instance

The Timer uses a quicktime TimeBase object as its time base. The timer's TimeBase can be slaved to or be a master of any other TimeBase. If this relationship is established the actual or effective rate of the TimeBase is determined by the rate of its own TimeBase and the rates of all of its master TimeBases.

The Timer can be in one of three states.

By default a Timer is inactive and an application using a Timer must make it active. A Timer will once active, tickle if tickling is enabled (which is the default setting). If an application wants to use a Timer without its tickle services, it can disable the tickle capability and reenable it later if appropriate.

Whenever the condition of the time base's time line changes the Timer notifies its subclass or Ticklish target through invoking the timeChanged method with the new time. The conditions under which this method is invoked are when the time value jumps or the effective rate changes from positive to negative or vice versa.

Whenever the tickle method is invoked the effective rate of the Timer's TimeBase is passes on, as is the time of the tickle method. In both cases this time value is specified in terms of the Ticklish.kScale value. If the timer is ticking (ie. its effective rate is not equal to zero) then the time when a timeChanged notification was sent will also be the time value that the next tickle method will receive.

If the tickle method returns true then the Timer will tickle again when the specified scale and period has elapsed. If the tickle method returns false then the Timer will not tickle again until the Timer's tickling has been reenabled.

It does not guarantee that the tickle method will be called by the specified interval. This is affected by two factors - latencies in Java threads or other activity in the runtime that does not allow the invocation of the timer's tickle, and the amount of time that the the tickle method itself takes to execute. In these cases (ie. the next tickle is late) it will be called at the earliest possible time. For example if you have a tickle interval of 100 msecs and the previous tickle took 150msecs to execute, then the next tickle will be given at the earlies possible return. A consequent tickle to that will be in the interval specified or ASAP if this consequent tickle takes longer than the specified time.

See Also:
TimeBase, Ticklish, Timeable

Constructor Summary
Timer(int scale, int period)
          Create a Timer.
Timer(int scale, int period, Ticklish target)
          Create a Timer.
Timer(int scale, int period, Ticklish target, Movie mov)
          Create a Timer.
 
Method Summary
protected  void finalize()
          The finalize method deactivates the timer.
 int getPeriod()
          Returns the current period (number of scale ticks) of the Timer's tickle notification.
 float getRate()
          Returns the current rate of this Timer - this is the Timer's TimeBase rate.
 int getScale()
          Returns the current scale of the Timer's tickle notification.
 Ticklish getTicklish()
          Returns the current target of the Targetable object - this is the object that the Targetable will act upon.
 TimeBase getTimeBase()
          Returns the current time base that provides the time foundation of this object.
 boolean isActive()
          Returns the current active state of the Timer.
 boolean isTicking()
          Returns true if the Timer's effective rate is currently non-zero
 boolean isTickling()
          Returns true if the Timer, when active, will tickle or false if the Timer, when active, will not tickle.
 void rescheduleTickle(int scale, int period)
          This method will reschedule the Timer's callback mechanism to the new scale and period values.
 void setActive(boolean flag)
          Sets the active state of the Timer; only an active Timer will tickle.
 void setRate(float rate)
          Sets the Timeable's playback rate.
 void setTickling(boolean flag)
          Sets the tickle state of the Timer.
protected  boolean tickle(float er, int time)
          When the time from zero (or a timeChanged time value, or the previous tickle time) that is specified by the scale and period of the Timer has elapsed the timer calls the tickle method.
protected  void timeChanged(int newTime)
          This is called by the Timer itself when the time base of the Timer has changed, through being reset to a new time or through the effective rate of the Timer changing from positive to negative or vice versa
 java.lang.String toString()
          Return a string representation of this class.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Timer

public Timer(int scale,
             int period)
      throws QTException
Create a Timer.
Parameters:
scale - the scale of the timer's tickle invocation period
period - the number of scale size ticks that elapse between each invocation of the tickle method

Timer

public Timer(int scale,
             int period,
             Ticklish target)
      throws QTException
Create a Timer.
Parameters:
scale - the scale of the timer's tickle invocation period
period - the number of scale size ticks that elapse between each invocation of the tickle method
target - the Ticklish target of the Timer - if this is not null then the target's tickle and timeChanged method will be invoked by the Timer.

Timer

public Timer(int scale,
             int period,
             Ticklish target,
             Movie mov)
      throws QTException
Create a Timer.
Parameters:
scale - the scale of the timer's tickle invocation period
period - the number of scale size ticks that elapse between each invocation of the tickle method
target - the Ticklish target of the Timer - if this is not null then the target's tickle and timeChanged method will be invoked by the Timer.
mov - the Movie from which the TimeBase of the timer will be derived.
Method Detail

isTicking

public boolean isTicking()
Returns true if the Timer's effective rate is currently non-zero
Returns:
a boolean

isTickling

public boolean isTickling()
Returns true if the Timer, when active, will tickle or false if the Timer, when active, will not tickle. This does not indicate whether the Timer is active.
Returns:
a boolean

setTickling

public void setTickling(boolean flag)
                 throws StdQTException
Sets the tickle state of the Timer. If true then the Timer when active will tickle. If false then the Timer when active will not tickle. This does not activate or deactivate a Timer.
Parameters:
flag - a boolean

getTicklish

public Ticklish getTicklish()
Returns the current target of the Targetable object - this is the object that the Targetable will act upon.
Returns:
the current target

getTimeBase

public final TimeBase getTimeBase()
Returns the current time base that provides the time foundation of this object.
Specified by:
getTimeBase in interface Timeable
Returns:
a TimeBase

rescheduleTickle

public void rescheduleTickle(int scale,
                             int period)
                      throws QTException
This method will reschedule the Timer's callback mechanism to the new scale and period values. Scale cannot be zero. A zero period will disable any tickle. This will have the side-effect of resetting the isTickling state to true, so can be used to both reschedule a tickle call and ensure that a tickle will be sent.
Parameters:
scale - the new scale of the Timer's tickle notification
period - the number of scale ticks that will elapse between notifications.

getScale

public int getScale()
Returns the current scale of the Timer's tickle notification.
Returns:
the scale

getPeriod

public int getPeriod()
Returns the current period (number of scale ticks) of the Timer's tickle notification.
Returns:
the scale

getRate

public float getRate()
Returns the current rate of this Timer - this is the Timer's TimeBase rate. This may not be the actual or effective rate that the timer is ticking at if its TimeBase is slaved to another TimeBase
Specified by:
getRate in interface Timeable
Returns:
the current rate

setRate

public void setRate(float rate)
Sets the Timeable's playback rate. Typically a rate of zero will mean that the player is stopped, a positive value that the player is playing forwards. If the object implements the Playable interface setting a negative value will play the player backwards. However, if the object does not have a time line then a negative value will continue to play the object in a forwards direction.
Specified by:
setRate in interface Timeable
Parameters:
rate - the new playback rate.

setActive

public void setActive(boolean flag)
               throws QTException
Sets the active state of the Timer; only an active Timer will tickle.
Parameters:
flag - fi true the Timer is active, if false it is inactive

isActive

public boolean isActive()
Returns the current active state of the Timer.
Returns:
true if the Timer is active, or false if it is not

toString

public java.lang.String toString()
Return a string representation of this class.
Overrides:
toString in class java.lang.Object

timeChanged

protected void timeChanged(int newTime)
                    throws QTException
This is called by the Timer itself when the time base of the Timer has changed, through being reset to a new time or through the effective rate of the Timer changing from positive to negative or vice versa
Parameters:
newTime - the new time of the Timer's time line expressed in the Ticklish.kScale

tickle

protected boolean tickle(float er,
                         int time)
                  throws QTException
When the time from zero (or a timeChanged time value, or the previous tickle time) that is specified by the scale and period of the Timer has elapsed the timer calls the tickle method. The Timer will only call this method if the Timer has an effective rate that is not zero.
Parameters:
er - the effective or actual rate that the timer is ticking at.
time - the current time of the time base expressed in the Ticklish.kScale
Returns:
true if the Timer should remain active and tickle again or false if it should become inactive.

finalize

protected void finalize()
                 throws java.lang.Throwable
The finalize method deactivates the timer.
Overrides:
finalize in class java.lang.Object