From: mkoch Date: Thu, 28 Apr 2005 20:25:43 +0000 (+0000) Subject: 2005-04-28 Michael Koch X-Git-Url: http://git.sourceforge.jp/view?p=pf3gnuchains%2Fgcc-fork.git;a=commitdiff_plain;h=f8e976477ab53b06a7cb0edbe59fb6ac7957ee65 2005-04-28 Michael Koch * javax/swing/Timer.java: Reordered all fields and methods, Added more javadocs. git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@98936 138bc75d-0d04-0410-961f-82ee72b054a4 --- diff --git a/libjava/ChangeLog b/libjava/ChangeLog index 1bc57197e4d..c9bd0ca3a42 100644 --- a/libjava/ChangeLog +++ b/libjava/ChangeLog @@ -1,5 +1,10 @@ 2005-04-28 Michael Koch + * javax/swing/Timer.java: Reordered all fields and methods, + Added more javadocs. + +2005-04-28 Michael Koch + * javax/swing/Timer.java: Javadocs merged from GNU classpath. diff --git a/libjava/javax/swing/Timer.java b/libjava/javax/swing/Timer.java index c339c8b0544..eac5832a381 100644 --- a/libjava/javax/swing/Timer.java +++ b/libjava/javax/swing/Timer.java @@ -54,29 +54,58 @@ import javax.swing.event.EventListenerList; public class Timer implements Serializable { - /** DOCUMENT ME! */ - private static final long serialVersionUID = -1116180831621385484L; - - /** DOCUMENT ME! */ - protected EventListenerList listenerList = new EventListenerList(); - - // This object manages a "queue" of virtual actionEvents, maintained as a - // simple long counter. When the timer expires, a new event is queued, - // and a dispatcher object is pushed into the system event queue. When - // the system thread runs the dispatcher, it will fire as many - // ActionEvents as have been queued, unless the timer is set to - // coalescing mode, in which case it will fire only one ActionEvent. - - /** DOCUMENT ME! */ - private long queue; - - /** DOCUMENT ME! */ - private Object queueLock = new Object(); + /** + * The timer thread + */ + private class Waker + extends Thread + { + /** + * Fires events, pausing for required intervals. + */ + public void run() + { + running = true; + try + { + sleep(initialDelay); + + while (running) + { + try + { + sleep(delay); + } + catch (InterruptedException e) + { + return; + } + queueEvent(); + + if (logTimers) + System.out.println("javax.swing.Timer -> clocktick"); + + if ( ! repeats) + break; + } + running = false; + } + catch (Exception e) + { + } + } + } - /** DOCUMENT ME! */ - private Waker waker; + /** + * Use serialVersionUID for interoperability. + */ + private static final long serialVersionUID = -1116180831621385484L; - private Runnable drainer = new Runnable() + /** + * The encloding class, used with {@link SwingUtilities#invokeLater} + * to invoke the {@link #drainEvents()}. + */ + private Runnable drainer = new Runnable() { public void run() { @@ -85,45 +114,15 @@ public class Timer }; /** - * DOCUMENT ME! - * Package-private to avoid an accessor method. + * If true, the timer prints a message to + * {@link System#out} when firing each event. */ - private void queueEvent() - { - synchronized (queueLock) - { - queue++; - if (queue == 1) - SwingUtilities.invokeLater(drainer); - } - } + static boolean logTimers; /** - * DOCUMENT ME! - * This is package-private to avoid an accessor method. + * A field to store all listeners who are listening to this timer. */ - void drainEvents() - { - synchronized (queueLock) - { - if (isCoalesce()) - { - if (queue > 0) - fireActionPerformed(); - } - else - { - while (queue > 0) - { - fireActionPerformed(); - queue--; - } - } - queue = 0; - } - } - - static boolean logTimers; + protected EventListenerList listenerList = new EventListenerList(); /** * true if the timer coalesces events. @@ -141,9 +140,6 @@ public class Timer */ boolean running; - /** DOCUMENT ME! */ - int ticks; - /** * The delay between subsequent repetetive events. */ @@ -155,46 +151,33 @@ public class Timer int initialDelay; /** - * DOCUMENT ME! + * The number of events that have been already fired by this timer. + * This is used as a numeric identifier for the next event that would + * be fired. */ - private class Waker extends Thread - { - /** - * DOCUMENT ME! - */ - public void run() - { - running = true; - try - { - sleep(initialDelay); - - while (running) - { - try - { - sleep(delay); - } - catch (InterruptedException e) - { - return; - } - queueEvent(); - - if (logTimers) - System.out.println("javax.swing.Timer -> clocktick"); - - if (! repeats) - break; - } - running = false; - } - catch (Exception e) - { -// System.out.println("swing.Timer::" + e); - } - } - } + int ticks; + + /** + * Stores the thread that posts events to the queue at required time + * intervals. + */ + private Waker waker; + + /** + * This object manages a "queue" of virtual actionEvents, maintained as a + * simple long counter. When the timer expires, a new event is queued, + * and a dispatcher object is pushed into the system event queue. When + * the system thread runs the dispatcher, it will fire as many + * ActionEvents as have been queued, unless the timer is set to + * coalescing mode, in which case it will fire only one ActionEvent. + */ + private long queue; + + /** + * synchronized(queueLock) replaces + * synchronized(queue) that is not supported by this language. + */ + private Object queueLock = new Object(); /** * Creates a new Timer object. @@ -212,43 +195,44 @@ public class Timer } /** - * DOCUMENT ME! + * Get the array of action listeners. * - * @param c DOCUMENT ME! - */ - public void setCoalesce(boolean c) - { - coalesce = c; - } - - /** - * DOCUMENT ME! + * @return the array of action listeners that are listening for the events, + * fired by this timer * - * @return DOCUMENT ME! + * @since 1.4 */ - public boolean isCoalesce() + public ActionListener[] getActionListeners() { - return coalesce; + return (ActionListener[]) listenerList.getListeners(ActionListener.class); } /** - * DOCUMENT ME! + * Sets whether the Timer coalesces multiple pending event firings. + * If the coalescing is enabled, the multiple events that have not been + * fired on time are replaced by the single event. The events may not + * be fired on time if the application is busy. * - * @param listener DOCUMENT ME! + * @param c true (default) to enable the event coalescing, + * false otherwise */ - public void addActionListener(ActionListener listener) + public void setCoalesce(boolean c) { - listenerList.add(ActionListener.class, listener); + coalesce = c; } /** - * DOCUMENT ME! + * Checks if the Timer coalesces multiple pending event firings. + * If the coalescing is enabled, the multiple events that have not been + * fired on time are replaced by the single event. The events may not + * be fired on time if the application is busy. * - * @param listener DOCUMENT ME! + * @return true if the coalescing is enabled, + * false otherwise */ - public void removeActionListener(ActionListener listener) + public boolean isCoalesce() { - listenerList.remove(ActionListener.class, listener); + return coalesce; } /** @@ -267,39 +251,6 @@ public class Timer } /** - * DOCUMENT ME! - * - * @return DOCUMENT ME! - * - * @since 1.4 - */ - public ActionListener[] getActionListeners() - { - return (ActionListener[]) listenerList.getListeners(ActionListener.class); - } - - /** - * DOCUMENT ME! - * - * @param event DOCUMENT ME! - */ - protected void fireActionPerformed(ActionEvent event) - { - ActionListener[] listeners = getActionListeners(); - - for (int i = 0; i < listeners.length; i++) - listeners[i].actionPerformed(event); - } - - /** - * DOCUMENT ME! - */ - void fireActionPerformed() - { - fireActionPerformed(new ActionEvent(this, ticks++, "Timer")); - } - - /** * Set the timer logging state. If it is set to true, the * timer prints a message to {@link System#out} when firing each * action event. @@ -408,18 +359,28 @@ public class Timer } /** - * DOCUMENT ME! + * Add the action listener + * + * @param listener the action listener to add */ - public void start() + public void addActionListener(ActionListener listener) { - if (isRunning()) - return; - waker = new Waker(); - waker.start(); + listenerList.add(ActionListener.class, listener); + } + + /** + * Remove the action listener. + * + * @param listener the action listener to remove + */ + public void removeActionListener(ActionListener listener) + { + listenerList.remove(ActionListener.class, listener); } /** - * DOCUMENT ME! + * Cancel all pending tasks and fire the first event after the initial + * delay. */ public void restart() { @@ -428,7 +389,18 @@ public class Timer } /** - * DOCUMENT ME! + * Start firing the action events. + */ + public void start() + { + if (isRunning()) + return; + waker = new Waker(); + waker.start(); + } + + /** + * Stop firing the action events. */ public void stop() { @@ -440,4 +412,69 @@ public class Timer queue = 0; } } + + /** + * Fire the given action event to the action listeners. + * + * @param event the event to fire + */ + protected void fireActionPerformed(ActionEvent event) + { + ActionListener[] listeners = getActionListeners(); + + for (int i = 0; i < listeners.length; i++) + listeners [ i ].actionPerformed(event); + } + + /** + * Fire the action event, named "Timer" and having the numeric + * identifier, equal to the numer of events that have been + * already fired before. + */ + void fireActionPerformed() + { + fireActionPerformed(new ActionEvent(this, ticks++, "Timer")); + } + + /** + * Fire the queued action events. + * In the coalescing mode, a single event is fired as a replacement + * for all queued events. In non coalescing mode, a series of + * all queued events is fired. + * This is package-private to avoid an accessor method. + */ + void drainEvents() + { + synchronized (queueLock) + { + if (isCoalesce()) + { + if (queue > 0) + fireActionPerformed(); + } + else + { + while (queue > 0) + { + fireActionPerformed(); + queue--; + } + } + queue = 0; + } + } + + /** + * Post a scheduled event to the event queue. + * Package-private to avoid an accessor method. + */ + private void queueEvent() + { + synchronized (queueLock) + { + queue++; + if (queue == 1) + SwingUtilities.invokeLater(drainer); + } + } }