27.2 The Timer Class

The Timer class provides a mechanism to generate timed events. It has properties and events, and thus can be used in application builders that understand JavaBeans. It fires an ActionEvent at a given time. The timer can be set to repeat, and an optional initial delay can be set before the repeating event starts.

27.2.1 Properties

The Timer class properties give you access to the timer delays and nature of the event firing loops. They are listed in Table 27-2. The delay property dictates the length between repeated timer events (if repeats is true) and initialDelay determines how long to wait before starting the regular, repeating events. Both properties expect values in milliseconds. If your timer is not repeating, then the value of initialDelay determines when the timer fires its event. You can check to see if the timer is running with the running property. The coalesce property dictates whether or not the timer combines pending events into one single event (to help listeners keep up). For example, if the timer fires a tick every 10 milliseconds, but the application is busy and has not handled events for 100 milliseconds, 10 action events are queued up for delivery. If coalesce is false, all 10 of these are delivered in rapid succession. If coalesce is true (the default), only one event is fired. The logTimers property can be turned on to generate simple debugging information to the standard output stream each time an event is processed.

Table 27-2. Timer properties

Property	Data type	get	is	set	Default value
actionListeners1.4	ActionListener[]	·		·	Empty array
delay	int	·		·	From constructor
coalesce	boolean		·	·	true
initialDelay	int	·		·	this.delay
logTimers	boolean	·		·	false
repeats	boolean		·	·	true
running	boolean		·		false
1.4since 1.4

27.2.2 Events

A Timer generates an ActionEvent whenever it "goes off." You can listen for ActionEvents if you want to react to a timer tick.

public void addActionListener(ActionListener l)

public void removeActionListener(ActionListener l)

Add or remove listeners interested in receiving action events from the timer.

public EventListener[] getListeners(Class listenerType)

Retrieve all listeners of type listenerType. Used by getActionListeners( ) to return, well, action listeners.

The Timer class also contains its own fireActionPerformed( ) method to facilitate reporting events to listeners.

protected void fireActionPerformed(ActionEvent e)

Send ActionEvent objects to any registered listeners.

27.2.3 Constructor

public Timer(int delay, ActionListener listener)

Create a Timer object that notifies its listener every delay milliseconds. The listener argument can be null. The timer is not started right away; you must manually call the start( ) method.

27.2.4 Timer Control Methods

You also have a few methods to control the timer at runtime:

public void start( )

Start the timer. The first event comes after initialDelay milliseconds, and if it's a repeating timer, every delay milliseconds after that.

public void restart( )

Restart the timer. This method calls stop( ) and then start( ).

public void stop( )

Stop the timer. Any timer events not yet fired are deleted.

Figure 27-2 shows a ClockLabel that updates itself every second, using events from a Timer. The code to produce our ticking label is remarkably short when we use a Timer.

// ClockLabel.java
// An extension of the JLabel class that listens to events from a Timer object to
// update itself with the current date & time.
//
import java.util.Date;
import java.awt.event.*;
import javax.swing.*;

public class ClockLabel extends JLabel implements ActionListener {

  public ClockLabel( ) {
    super("" + new Date( ));
    Timer t = new Timer(1000, this);
    t.start( );
  }

  public void actionPerformed(ActionEvent ae) {
    setText((new Date( )).toString( ));
  }
}

Figure 27-2. The Timer class in action with a ClockLabel

And here's the application that displays the ClockLabel object:

// ClockTest.java
// A demonstration framework for the Timer driven ClockLabel class
//
import javax.swing.*;
import java.awt.*;

public class ClockTest extends JFrame {

  public ClockTest( ) {
    super("Timer Demo");
    setSize(300, 100);
    setDefaultCloseOperation(EXIT_ON_CLOSE);

    ClockLabel clock = new ClockLabel( );
    getContentPane( ).add(clock, BorderLayout.NORTH);
  }

  public static void main(String args[]) {
    ClockTest ct = new ClockTest( );
    ct.setVisible(true);
  }
}