Writing Event Listeners

Handling Common Events

This section tells you how to write a listener for events that can be generated from a Swing component that are commonly handled by programs. First, it gives an overview of the listeners. After that, each listener type is discussed in its own subsection.

In the table that follows, each row describes a particular group of events corresponding to one listener interface. The first column gives the name of the listener interface, with a link to the tutorial page that discusses that listener. The second column names the corresponding adapter class, if any. (For a discussion of using adapters, see Using Adapters and Inner Classes to Handle Events.) The third column indicates the package in which the listener interface, the event class, and the adapter class are defined. The fourth column lists the methods that the listener interface contains.

To see which Swing components can generate which kinds of events, see Events Generated by Swing Components.

Listener Interface	Adapter Class	Package	Methods
ActionListener	none	java.awt.event	actionPerformed
CaretListener	none	javax.swing.event	caretUpdate
ChangeListener	none	javax.swing.event	stateChanged
ComponentListener	ComponentAdapter	java.awt.event	componentHidden componentMoved componentResized componentShown
ContainerListener	ContainerAdapter	java.awt.event	componentAdded componentRemoved
DocumentListener	none	javax.swing.event	changedUpdate insertUpdate removeUpdate
FocusListener	FocusAdapter	java.awt.event	focusGained focusLost
InternalFrameListener	InternalFrameAdapter	javax.swing.event	internalFrameActivated internalFrameClosed internalFrameClosing internalFrameDeactivated internalFrameDeiconified internalFrameIconified internalFrameOpened
ItemListener	none	java.awt.event	itemStateChanged
KeyListener	KeyAdapter	java.awt.event	keyPressed keyReleased keyTyped
ListSelectionListener	none	javax.swing.event	valueChanged
MouseListener	MouseAdapter MouseInputAdapter *	java.awt.event javax.swing.event	mouseClicked mouseEntered mouseExited mousePressed mouseReleased
MouseMotionListener	MouseMotionAdapter MouseInputAdapter *	java.awt.event javax.swing.event	mouseDragged mouseMoved
UndoableEditListener	none	javax.swing.event	undoableEditHappened
WindowListener	WindowAdapter	java.awt.event	windowActivated windowClosed windowClosing windowDeactivated windowDeiconified windowIconified windowOpened

* Swing provides the MouseInputAdapter class as a convenience. It implements both the MouseListener and the MouseMotionListener interfaces making it easier for you to handle both types of mouse events.

The events described in the preceding table can be divided into two groups: low-level events and semantic events. Low-level events represent window-system occurrences or low-level input. Clearly, mouse and key events -- both of which result directly from user input -- are low-level events.

Component, container, focus, and window events are also low-level events. Component events let you track changes to a component's position, size, and visibility. Container events let you know when any component is added to or removed from a particular container. Focus events tell you when a component gains or loses the keyboard focus -- the ability to receive characters typed at the keyboard. Window events keep you informed of the basic status of any kind of Window, such as a Dialog or a Frame.

Mouse events are broken into two groups -- mouse motion events and all other mouse events -- so that an object can listen for mouse events such as clicks without requiring the system overhead necessary for generating and forwarding mouse motion events, which tend to occur frequently.

Semantic events include action, change, document, and item events. These events are the result of component-specific user interaction. For example, a button generates an action event when the user clicks it, and a list generates an action event when the user doubleclicks an item in it. When a user selects an item in a group of items (such as a list), an item event is generated.

The next several sections have details on each type of event.

Writing Event Listeners