com.threerings.media
Class TimerView

java.lang.Object
  com.threerings.media.TimerView

All Implemented Interfaces:

FrameParticipant, HierarchyListener, EventListener

Direct Known Subclasses:

HourglassView

public class TimerView
extends Object
implements FrameParticipant, HierarchyListener

A generic timer class that can be rendered on screen. NOTE: This base class doesn't actually render anything, but it's still useful for triggering user supplied callback functions. Derived classes are more than welcome to setup their own rendering, of course.

Field Summary

protected Rectangle	_bounds The screen coordinates of the timer's bounding box.
protected float	_changeThreshold The timer will not invalidate itself until the completion level to render changes by at least this much from the previous time it was invalidated.
protected float	_complete The percent of the duration time completed.
protected boolean	_completed True if the completion has already been processed.
protected long	_duration The total amount of time in the timer when it was 0% done.
protected boolean	_enabled Whether to render the timer.
protected ResultListener<TimerView>	_finisher A listener to be notified when the timer finishes.
protected FrameManager	_fmgr The frame manager that manages our animated view.
protected JComponent	_host The media panel containing the view.
protected boolean	_invalidated True if the timer has been invalidated since its last repaint.
protected long	_lastUpdate The last time the timer updated while running.
protected float	_paintComplete The completion percent last time the timer was repainted.
protected boolean	_participating Whether the timer is participating in media tick updates.
protected boolean	_processUnpause True if the code should process everything required for an unpause on the next tick().
protected float	_renderComplete The completion percent at which to render the timer.
protected float	_renderOffset The difference between the old rendered completion percent and the new completion percent the last time the completion percent had an unexpected change.
protected long	_renderOffsetTime The timestamp of _renderOffset.
protected boolean	_running Whether the timer is running.
protected long	_start The timestamp when the timer effectively started.
protected long	_transitionTime The amount of time it takes to fully interpolation a render transition from completion 0.0 to 1.0.
protected boolean	_warned True if the warning has already been processed.
protected ResultListener<TimerView>	_warner A listener to be notified when the warning time occurs.
protected float	_warnPercent Trigger the warning when at least this much time has elapsed, or -1 for no warning.
protected static long	DEFAULT_RATE The default update date.

Constructor Summary

TimerView(FrameManager fmgr, JComponent host, Rectangle bounds)
Constructs a timer view that fires at the default rate.

Method Summary

void	changeComplete(float complete) Generate an unexpected change in the timer's completion and set up the necessary details to render interpolation from the old to new states
void	checkFrameParticipation() Check that the frame knows about the timer.
Component	getComponent() If a frame participant wishes also to be actively rendered every frame rather than use passive rendering (which for Swing, at least, is hijacked when using the frame manager such that we take care of repainting dirty Swing components every frame into our off-screen buffer), it can return a component here which will have Component.paint(java.awt.Graphics) called on it once per frame with a translated but unclipped graphics object.
long	getTransitionTime() Get the amount of time it takes to render digital changes in the completion state.
protected void	handleCompleted() Handle the trigger of the timer's completion.
protected void	handleWarning() Handle the trigger of the warning.
void	hierarchyChanged(HierarchyEvent e)
protected void	invalidate() Invalidates this view's bounds via the host component.
boolean	needsPaint() Called immediately prior to FrameParticipant.getComponent() and then Component.paint(java.awt.Graphics) on said component, to determine whether or not this frame participant needs to be painted.
void	paint(Graphics2D gfx, float complete) Paint the timer into the given graphics context at the inputted percent complete (0f means just started, 1f means just finished).
void	pause() Pause the timer from processing.
void	removeWarning() Remove any warning this timer might have had.
void	render(Graphics2D gfx) Renders the timer to the given graphics context if enabled.
void	reset() Reset the timer.
boolean	running() Test if the timer is running right now.
void	setEnabled(boolean enabled) Sets whether this timer should be rendered.
void	setTransitionTime(long time) Set the amount of time it takes to render digital changes in the completion state (probably due to a timer reset).
void	setWarning(float warnPercent, ResultListener<TimerView> warner) Setup a warning to trigger after the timer is "warnPercent" or more completed.
void	start(float startPercent, long duration, ResultListener<TimerView> finisher) Start the timer running from the specified percentage complete, to expire at the specified time.
void	stop() Stop the timer.
void	tick(long now) This is called on all registered frame participants, one for every frame.
protected boolean	triggeredCompleted() Test if the completion was triggered and needs to be processed.
protected boolean	triggeredWarning() Test if the warning was triggered and needs to be processed.
void	unpause() Unpause the timer.
protected void	update(long now) Updates the timer for the current inputted time.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_fmgr

protected FrameManager _fmgr

The frame manager that manages our animated view.

_host

protected JComponent _host

The media panel containing the view.

_bounds

protected Rectangle _bounds

The screen coordinates of the timer's bounding box.

_enabled

protected boolean _enabled

Whether to render the timer.

_running

protected boolean _running

Whether the timer is running.

_participating

protected boolean _participating

Whether the timer is participating in media tick updates.

_lastUpdate

protected long _lastUpdate

The last time the timer updated while running.

_duration

protected long _duration

The total amount of time in the timer when it was 0% done.

_start

protected long _start

The timestamp when the timer effectively started.

_complete

protected float _complete

The percent of the duration time completed.

_renderOffset

protected float _renderOffset

The difference between the old rendered completion percent and the new completion percent the last time the completion percent had an unexpected change. In other words, this is the greatest amount that _renderComplete will differ from _complete during an state interpolation.

_renderOffsetTime

protected long _renderOffsetTime

The timestamp of _renderOffset.

_transitionTime

protected long _transitionTime

The amount of time it takes to fully interpolation a render transition from completion 0.0 to 1.0.

_renderComplete

protected float _renderComplete

The completion percent at which to render the timer.

_paintComplete

protected float _paintComplete

The completion percent last time the timer was repainted.

_changeThreshold

protected float _changeThreshold

The timer will not invalidate itself until the completion level to render changes by at least this much from the previous time it was invalidated.

_invalidated

protected boolean _invalidated

True if the timer has been invalidated since its last repaint.

_warnPercent

protected float _warnPercent

Trigger the warning when at least this much time has elapsed, or -1 for no warning.

_warned

protected boolean _warned

True if the warning has already been processed.

_completed

protected boolean _completed

True if the completion has already been processed.

_processUnpause

protected boolean _processUnpause

True if the code should process everything required for an unpause on the next tick().

_finisher

protected ResultListener<TimerView> _finisher

A listener to be notified when the timer finishes.

_warner

protected ResultListener<TimerView> _warner

A listener to be notified when the warning time occurs.

DEFAULT_RATE

protected static final long DEFAULT_RATE

The default update date.

See Also:

Constant Field Values

Constructor Detail

TimerView

public TimerView(FrameManager fmgr,
                 JComponent host,
                 Rectangle bounds)

Constructs a timer view that fires at the default rate.

Method Detail

setEnabled

public void setEnabled(boolean enabled)

Sets whether this timer should be rendered.

getTransitionTime

public long getTransitionTime()

Get the amount of time it takes to render digital changes in the completion state.

setTransitionTime

public void setTransitionTime(long time)

Set the amount of time it takes to render digital changes in the completion state (probably due to a timer reset).

setWarning

public void setWarning(float warnPercent,
                       ResultListener<TimerView> warner)

Setup a warning to trigger after the timer is "warnPercent" or more completed. If "warner" is non-null, it will be called at that time.

removeWarning

public void removeWarning()

Remove any warning this timer might have had.

running

public boolean running()

Test if the timer is running right now.

start

public void start(float startPercent,
                  long duration,
                  ResultListener<TimerView> finisher)

Start the timer running from the specified percentage complete, to expire at the specified time.

Parameters:

startPercent - a value in [0f, 1f) indicating how much hourglass time has already elapsed when the timer starts.

duration - The time interval over which the timer would run if it started at 0%.

finisher - a listener that will be notified when the timer finishes, or null if nothing should be notified.

reset

public void reset()

Reset the timer.

stop

public void stop()

Stop the timer.

pause

public void pause()

Pause the timer from processing.

unpause

public void unpause()

Unpause the timer.

changeComplete

public void changeComplete(float complete)

Generate an unexpected change in the timer's completion and set up the necessary details to render interpolation from the old to new states

update

protected void update(long now)

Updates the timer for the current inputted time.

triggeredWarning

protected boolean triggeredWarning()

Test if the warning was triggered and needs to be processed.

triggeredCompleted

protected boolean triggeredCompleted()

Test if the completion was triggered and needs to be processed.

handleWarning

protected void handleWarning()

Handle the trigger of the warning.

handleCompleted

protected void handleCompleted()

Handle the trigger of the timer's completion.

invalidate

protected void invalidate()

Invalidates this view's bounds via the host component.

render

public void render(Graphics2D gfx)

Renders the timer to the given graphics context if enabled.

paint

public void paint(Graphics2D gfx,
                  float complete)

Paint the timer into the given graphics context at the inputted percent complete (0f means just started, 1f means just finished).

tick

public void tick(long now)

Description copied from interface: FrameParticipant

This is called on all registered frame participants, one for every frame. Following the tick the interface will be rendered, so participants can prepare themselves for their upcoming render in this method (making use of the timestamp provided for the frame if choreography is desired between different participants).

Specified by:

tick in interface FrameParticipant

needsPaint

public boolean needsPaint()

Description copied from interface: FrameParticipant

Called immediately prior to FrameParticipant.getComponent() and then Component.paint(java.awt.Graphics) on said component, to determine whether or not this frame participant needs to be painted.

Specified by:

needsPaint in interface FrameParticipant

getComponent

public Component getComponent()

Description copied from interface: FrameParticipant

If a frame participant wishes also to be actively rendered every frame rather than use passive rendering (which for Swing, at least, is hijacked when using the frame manager such that we take care of repainting dirty Swing components every frame into our off-screen buffer), it can return a component here which will have Component.paint(java.awt.Graphics) called on it once per frame with a translated but unclipped graphics object.

Because clipping is expensive in terms of rectangle object allocation, frame participants are given the opportunity to do their own clipping because they are likely to want to clip to a more fine grained region than their entire bounds. If a participant does not wish to be actively rendered, it can safely return null.

Specified by:

getComponent in interface FrameParticipant

hierarchyChanged

public void hierarchyChanged(HierarchyEvent e)

Specified by:

hierarchyChanged in interface HierarchyListener

checkFrameParticipation

public void checkFrameParticipation()

Check that the frame knows about the timer.