< prev index next >
src/java.desktop/share/classes/javax/swing/Timer.java
Print this page
*** 44,65 ****
/**
* Fires one or more {@code ActionEvent}s at specified
* intervals. An example use is an animation object that uses a
! * <code>Timer</code> as the trigger for drawing its frames.
*<p>
* Setting up a timer
! * involves creating a <code>Timer</code> object,
* registering one or more action listeners on it,
* and starting the timer using
! * the <code>start</code> method.
* For example,
* the following code creates and starts a timer
* that fires an action event once per second
! * (as specified by the first argument to the <code>Timer</code> constructor).
! * The second argument to the <code>Timer</code> constructor
* specifies a listener to receive the timer's action events.
*
*<pre>
* int delay = 1000; //milliseconds
* ActionListener taskPerformer = new ActionListener() {
--- 44,65 ----
/**
* Fires one or more {@code ActionEvent}s at specified
* intervals. An example use is an animation object that uses a
! * {@code Timer} as the trigger for drawing its frames.
*<p>
* Setting up a timer
! * involves creating a {@code Timer} object,
* registering one or more action listeners on it,
* and starting the timer using
! * the {@code start} method.
* For example,
* the following code creates and starts a timer
* that fires an action event once per second
! * (as specified by the first argument to the {@code Timer} constructor).
! * The second argument to the {@code Timer} constructor
* specifies a listener to receive the timer's action events.
*
*<pre>
* int delay = 1000; //milliseconds
* ActionListener taskPerformer = new ActionListener() {
*** 73,112 ****
* {@code Timers} are constructed by specifying both a delay parameter
* and an {@code ActionListener}. The delay parameter is used
* to set both the initial delay and the delay between event
* firing, in milliseconds. Once the timer has been started,
* it waits for the initial delay before firing its
! * first <code>ActionEvent</code> to registered listeners.
* After this first event, it continues to fire events
* every time the between-event delay has elapsed, until it
* is stopped.
* <p>
* After construction, the initial delay and the between-event
* delay can be changed independently, and additional
! * <code>ActionListeners</code> may be added.
* <p>
* If you want the timer to fire only the first time and then stop,
! * invoke <code>setRepeats(false)</code> on the timer.
* <p>
! * Although all <code>Timer</code>s perform their waiting
* using a single, shared thread
! * (created by the first <code>Timer</code> object that executes),
! * the action event handlers for <code>Timer</code>s
* execute on another thread -- the event-dispatching thread.
! * This means that the action handlers for <code>Timer</code>s
* can safely perform operations on Swing components.
* However, it also means that the handlers must execute quickly
* to keep the GUI responsive.
*
* <p>
! * In v 1.3, another <code>Timer</code> class was added
! * to the Java platform: <code>java.util.Timer</code>.
! * Both it and <code>javax.swing.Timer</code>
* provide the same basic functionality,
! * but <code>java.util.Timer</code>
* is more general and has more features.
! * The <code>javax.swing.Timer</code> has two features
* that can make it a little easier to use with GUIs.
* First, its event handling metaphor is familiar to GUI programmers
* and can make dealing with the event-dispatching thread
* a bit simpler.
* Second, its
--- 73,112 ----
* {@code Timers} are constructed by specifying both a delay parameter
* and an {@code ActionListener}. The delay parameter is used
* to set both the initial delay and the delay between event
* firing, in milliseconds. Once the timer has been started,
* it waits for the initial delay before firing its
! * first {@code ActionEvent} to registered listeners.
* After this first event, it continues to fire events
* every time the between-event delay has elapsed, until it
* is stopped.
* <p>
* After construction, the initial delay and the between-event
* delay can be changed independently, and additional
! * {@code ActionListeners} may be added.
* <p>
* If you want the timer to fire only the first time and then stop,
! * invoke {@code setRepeats(false)} on the timer.
* <p>
! * Although all {@code Timer}s perform their waiting
* using a single, shared thread
! * (created by the first {@code Timer} object that executes),
! * the action event handlers for {@code Timer}s
* execute on another thread -- the event-dispatching thread.
! * This means that the action handlers for {@code Timer}s
* can safely perform operations on Swing components.
* However, it also means that the handlers must execute quickly
* to keep the GUI responsive.
*
* <p>
! * In v 1.3, another {@code Timer} class was added
! * to the Java platform: {@code java.util.Timer}.
! * Both it and {@code javax.swing.Timer}
* provide the same basic functionality,
! * but {@code java.util.Timer}
* is more general and has more features.
! * The {@code javax.swing.Timer} has two features
* that can make it a little easier to use with GUIs.
* First, its event handling metaphor is familiar to GUI programmers
* and can make dealing with the event-dispatching thread
* a bit simpler.
* Second, its
*** 123,134 ****
* and several examples of using timers by visiting
* <a href="http://docs.oracle.com/javase/tutorial/uiswing/misc/timer.html"
* target = "_top">How to Use Timers</a>,
* a section in <em>The Java Tutorial.</em>
* For more examples and help in choosing between
! * this <code>Timer</code> class and
! * <code>java.util.Timer</code>,
* see
* <a href="http://java.sun.com/products/jfc/tsc/articles/timer/"
* target="_top">Using Timers in Swing Applications</a>,
* an article in <em>The Swing Connection.</em>
* <p>
--- 123,134 ----
* and several examples of using timers by visiting
* <a href="http://docs.oracle.com/javase/tutorial/uiswing/misc/timer.html"
* target = "_top">How to Use Timers</a>,
* a section in <em>The Java Tutorial.</em>
* For more examples and help in choosing between
! * this {@code Timer} class and
! * {@code java.util.Timer},
* see
* <a href="http://java.sun.com/products/jfc/tsc/articles/timer/"
* target="_top">Using Timers in Swing Applications</a>,
* an article in <em>The Swing Connection.</em>
* <p>
*** 136,146 ****
* Serialized objects of this class will not be compatible with
* future Swing releases. The current serialization support is
* appropriate for short term storage or RMI between applications running
* the same version of Swing. As of 1.4, support for long term storage
* of all JavaBeans™
! * has been added to the <code>java.beans</code> package.
* Please see {@link java.beans.XMLEncoder}.
*
* @see java.util.Timer
*
*
--- 136,146 ----
* Serialized objects of this class will not be compatible with
* future Swing releases. The current serialization support is
* appropriate for short term storage or RMI between applications running
* the same version of Swing. As of 1.4, support for long term storage
* of all JavaBeans™
! * has been added to the {@code java.beans} package.
* Please see {@link java.beans.XMLEncoder}.
*
* @see java.util.Timer
*
*
*** 193,207 ****
/**
* Creates a {@code Timer} and initializes both the initial delay and
* between-event delay to {@code delay} milliseconds. If {@code delay}
* is less than or equal to zero, the timer fires as soon as it
! * is started. If <code>listener</code> is not <code>null</code>,
* it's registered as an action listener on the timer.
*
* @param delay milliseconds for the initial and between-event delay
! * @param listener an initial listener; can be <code>null</code>
*
* @see #addActionListener
* @see #setInitialDelay
* @see #setRepeats
*/
--- 193,207 ----
/**
* Creates a {@code Timer} and initializes both the initial delay and
* between-event delay to {@code delay} milliseconds. If {@code delay}
* is less than or equal to zero, the timer fires as soon as it
! * is started. If {@code listener} is not {@code null},
* it's registered as an action listener on the timer.
*
* @param delay milliseconds for the initial and between-event delay
! * @param listener an initial listener; can be {@code null}
*
* @see #addActionListener
* @see #setInitialDelay
* @see #setRepeats
*/
*** 259,269 ****
return Timer.this;
}
}
/**
! * Adds an action listener to the <code>Timer</code>.
*
* @param listener the listener to add
*
* @see #Timer
*/
--- 259,269 ----
return Timer.this;
}
}
/**
! * Adds an action listener to the {@code Timer}.
*
* @param listener the listener to add
*
* @see #Timer
*/
*** 271,281 ****
listenerList.add(ActionListener.class, listener);
}
/**
! * Removes the specified action listener from the <code>Timer</code>.
*
* @param listener the listener to remove
*/
public void removeActionListener(ActionListener listener) {
listenerList.remove(ActionListener.class, listener);
--- 271,281 ----
listenerList.add(ActionListener.class, listener);
}
/**
! * Removes the specified action listener from the {@code Timer}.
*
* @param listener the listener to remove
*/
public void removeActionListener(ActionListener listener) {
listenerList.remove(ActionListener.class, listener);
*** 284,294 ****
/**
* Returns an array of all the action listeners registered
* on this timer.
*
! * @return all of the timer's <code>ActionListener</code>s or an empty
* array if no action listeners are currently registered
*
* @see #addActionListener
* @see #removeActionListener
*
--- 284,294 ----
/**
* Returns an array of all the action listeners registered
* on this timer.
*
! * @return all of the timer's {@code ActionListener}s or an empty
* array if no action listeners are currently registered
*
* @see #addActionListener
* @see #removeActionListener
*
*** 320,337 ****
}
/**
* Returns an array of all the objects currently registered as
* <code><em>Foo</em>Listener</code>s
! * upon this <code>Timer</code>.
* <code><em>Foo</em>Listener</code>s
* are registered using the <code>add<em>Foo</em>Listener</code> method.
* <p>
! * You can specify the <code>listenerType</code> argument
* with a class literal, such as <code><em>Foo</em>Listener.class</code>.
! * For example, you can query a <code>Timer</code>
! * instance <code>t</code>
* for its action listeners
* with the following code:
*
* <pre>ActionListener[] als = (ActionListener[])(t.getListeners(ActionListener.class));</pre>
*
--- 320,337 ----
}
/**
* Returns an array of all the objects currently registered as
* <code><em>Foo</em>Listener</code>s
! * upon this {@code Timer}.
* <code><em>Foo</em>Listener</code>s
* are registered using the <code>add<em>Foo</em>Listener</code> method.
* <p>
! * You can specify the {@code listenerType} argument
* with a class literal, such as <code><em>Foo</em>Listener.class</code>.
! * For example, you can query a {@code Timer}
! * instance {@code t}
* for its action listeners
* with the following code:
*
* <pre>ActionListener[] als = (ActionListener[])(t.getListeners(ActionListener.class));</pre>
*
*** 339,357 ****
* this method returns an empty array.
*
* @param <T> the type of {@code EventListener} class being requested
* @param listenerType the type of listeners requested;
* this parameter should specify an interface
! * that descends from <code>java.util.EventListener</code>
* @return an array of all objects registered as
* <code><em>Foo</em>Listener</code>s
* on this timer,
* or an empty array if no such
* listeners have been added
! * @exception ClassCastException if <code>listenerType</code> doesn't
* specify a class or interface that implements
! * <code>java.util.EventListener</code>
*
* @see #getActionListeners
* @see #addActionListener
* @see #removeActionListener
*
--- 339,357 ----
* this method returns an empty array.
*
* @param <T> the type of {@code EventListener} class being requested
* @param listenerType the type of listeners requested;
* this parameter should specify an interface
! * that descends from {@code java.util.EventListener}
* @return an array of all objects registered as
* <code><em>Foo</em>Listener</code>s
* on this timer,
* or an empty array if no such
* listeners have been added
! * @exception ClassCastException if {@code listenerType} doesn't
* specify a class or interface that implements
! * {@code java.util.EventListener}
*
* @see #getActionListeners
* @see #addActionListener
* @see #removeActionListener
*
*** 369,401 ****
}
/**
* Enables or disables the timer log. When enabled, a message
! * is posted to <code>System.out</code> whenever the timer goes off.
*
! * @param flag <code>true</code> to enable logging
* @see #getLogTimers
*/
public static void setLogTimers(boolean flag) {
logTimers = flag;
}
/**
! * Returns <code>true</code> if logging is enabled.
*
! * @return <code>true</code> if logging is enabled; otherwise, false
* @see #setLogTimers
*/
public static boolean getLogTimers() {
return logTimers;
}
/**
! * Sets the <code>Timer</code>'s between-event delay, the number of milliseconds
* between successive action events. This does not affect the initial delay
* property, which can be set by the {@code setInitialDelay} method.
*
* @param delay the delay in milliseconds
* @see #setInitialDelay
--- 369,401 ----
}
/**
* Enables or disables the timer log. When enabled, a message
! * is posted to {@code System.out} whenever the timer goes off.
*
! * @param flag {@code true} to enable logging
* @see #getLogTimers
*/
public static void setLogTimers(boolean flag) {
logTimers = flag;
}
/**
! * Returns {@code true} if logging is enabled.
*
! * @return {@code true} if logging is enabled; otherwise, false
* @see #setLogTimers
*/
public static boolean getLogTimers() {
return logTimers;
}
/**
! * Sets the {@code Timer}'s between-event delay, the number of milliseconds
* between successive action events. This does not affect the initial delay
* property, which can be set by the {@code setInitialDelay} method.
*
* @param delay the delay in milliseconds
* @see #setInitialDelay
*** 423,433 ****
return delay;
}
/**
! * Sets the <code>Timer</code>'s initial delay, the time
* in milliseconds to wait after the timer is started
* before firing the first event. Upon construction, this
* is set to be the same as the between-event delay,
* but then its value is independent and remains unaffected
* by changes to the between-event delay.
--- 423,433 ----
return delay;
}
/**
! * Sets the {@code Timer}'s initial delay, the time
* in milliseconds to wait after the timer is started
* before firing the first event. Upon construction, this
* is set to be the same as the between-event delay,
* but then its value is independent and remains unaffected
* by changes to the between-event delay.
*** 452,476 ****
return initialDelay;
}
/**
! * If <code>flag</code> is <code>false</code>,
! * instructs the <code>Timer</code> to send only one
* action event to its listeners.
*
! * @param flag specify <code>false</code> to make the timer
* stop after sending its first action event
*/
public void setRepeats(boolean flag) {
repeats = flag;
}
/**
! * Returns <code>true</code> (the default)
! * if the <code>Timer</code> will send
* an action event
* to its listeners multiple times.
*
* @return true if the {@code Timer} will send an action event to its
* listeners multiple times
--- 452,476 ----
return initialDelay;
}
/**
! * If {@code flag} is {@code false},
! * instructs the {@code Timer} to send only one
* action event to its listeners.
*
! * @param flag specify {@code false} to make the timer
* stop after sending its first action event
*/
public void setRepeats(boolean flag) {
repeats = flag;
}
/**
! * Returns {@code true} (the default)
! * if the {@code Timer} will send
* an action event
* to its listeners multiple times.
*
* @return true if the {@code Timer} will send an action event to its
* listeners multiple times
*** 480,503 ****
return repeats;
}
/**
! * Sets whether the <code>Timer</code> coalesces multiple pending
! * <code>ActionEvent</code> firings.
* A busy application may not be able
! * to keep up with a <code>Timer</code>'s event generation,
* causing multiple
* action events to be queued. When processed,
* the application sends these events one after the other, causing the
! * <code>Timer</code>'s listeners to receive a sequence of
* events with no delay between them. Coalescing avoids this situation
* by reducing multiple pending events to a single event.
! * <code>Timer</code>s
* coalesce events by default.
*
! * @param flag specify <code>false</code> to turn off coalescing
*/
public void setCoalesce(boolean flag) {
boolean old = coalesce;
coalesce = flag;
if (!old && coalesce) {
--- 480,503 ----
return repeats;
}
/**
! * Sets whether the {@code Timer} coalesces multiple pending
! * {@code ActionEvent} firings.
* A busy application may not be able
! * to keep up with a {@code Timer}'s event generation,
* causing multiple
* action events to be queued. When processed,
* the application sends these events one after the other, causing the
! * {@code Timer}'s listeners to receive a sequence of
* events with no delay between them. Coalescing avoids this situation
* by reducing multiple pending events to a single event.
! * {@code Timer}s
* coalesce events by default.
*
! * @param flag specify {@code false} to turn off coalescing
*/
public void setCoalesce(boolean flag) {
boolean old = coalesce;
coalesce = flag;
if (!old && coalesce) {
*** 522,533 ****
}
/**
* Sets the string that will be delivered as the action command
! * in <code>ActionEvent</code>s fired by this timer.
! * <code>null</code> is an acceptable value.
*
* @param command the action command
* @since 1.6
*/
public void setActionCommand(String command) {
--- 522,533 ----
}
/**
* Sets the string that will be delivered as the action command
! * in {@code ActionEvent}s fired by this timer.
! * {@code null} is an acceptable value.
*
* @param command the action command
* @since 1.6
*/
public void setActionCommand(String command) {
*** 535,557 ****
}
/**
* Returns the string that will be delivered as the action command
! * in <code>ActionEvent</code>s fired by this timer. May be
! * <code>null</code>, which is also the default.
*
* @return the action command used in firing events
* @since 1.6
*/
public String getActionCommand() {
return actionCommand;
}
/**
! * Starts the <code>Timer</code>,
* causing it to start sending action events
* to its listeners.
*
* @see #stop
*/
--- 535,557 ----
}
/**
* Returns the string that will be delivered as the action command
! * in {@code ActionEvent}s fired by this timer. May be
! * {@code null}, which is also the default.
*
* @return the action command used in firing events
* @since 1.6
*/
public String getActionCommand() {
return actionCommand;
}
/**
! * Starts the {@code Timer},
* causing it to start sending action events
* to its listeners.
*
* @see #stop
*/
*** 570,580 ****
return timerQueue().containsTimer(this);
}
/**
! * Stops the <code>Timer</code>,
* causing it to stop sending action events
* to its listeners.
*
* @see #start
*/
--- 570,580 ----
return timerQueue().containsTimer(this);
}
/**
! * Stops the {@code Timer},
* causing it to stop sending action events
* to its listeners.
*
* @see #start
*/
*** 588,598 ****
}
}
/**
! * Restarts the <code>Timer</code>,
* canceling any pending firings and causing
* it to fire with its initial delay.
*/
public void restart() {
getLock().lock();
--- 588,598 ----
}
}
/**
! * Restarts the {@code Timer},
* canceling any pending firings and causing
* it to fire with its initial delay.
*/
public void restart() {
getLock().lock();
*** 606,616 ****
/**
* Resets the internal state to indicate this Timer shouldn't notify
* any of its listeners. This does not stop a repeatable Timer from
! * firing again, use <code>stop</code> for that.
*/
void cancelEvent() {
notify.set(false);
}
--- 606,616 ----
/**
* Resets the internal state to indicate this Timer shouldn't notify
* any of its listeners. This does not stop a repeatable Timer from
! * firing again, use {@code stop} for that.
*/
void cancelEvent() {
notify.set(false);
}
< prev index next >