Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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

- 10 scale, 1 period => the tickle method is invoked 10 times a second at a rate of 1
- 1 scale, 1 period => the tickle method is invoked 1 time a second at a rate of 1
- 1 scale, 2 period => the tickle method is invoked every 2 seconds at a rate of 1
- 3 scale, 2 period => the tickle method is invoked 3 times every 2 seconds at a rate of 1

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.

- Active and tickling - in which case it issues both timeChanged and tickle calls
- Active and not tickling - in which case it issues timeChanged calls but not tickle calls
- Inactive - neither timeChanged or tickle calls are issued.

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`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD