Writing Event Listeners

How to Write a Focus Listener

Many components--even those primarily operated with the mouse, such as buttons--can be operated with the keyboard. [PENDING: mention accessibility here?] For a keypress to affect a component, the component must have the keyboard focus.

From the user's point of view, the component with the keyboard focus is generally prominent--with a thicker boarder than usual, for example-- and the window containing the component is also more prominent than other windows on-screen. These visual cues let the user know to which component any typing will go. At most one component in the window system can have the keyboard focus.

Focus events are generated whenever a component gains or loses the keyboard focus. Exactly how components gain the focus depends on the window system. Typically, the user sets the focus by clicking a window or component, by tabbing between components, or by otherwise interacting with a component. Once the focus is in a window (the window is activated), a program can use the Component requestFocus method to request that a specific component get the focus.

Focus Event Methods

The FocusListener interface and its corresponding adapter class, FocusAdapter, contain two methods:

void focusGained(FocusEvent)

Called just after the listened-to component gets the focus.

void focusLost(FocusEvent)

Called just after the listened-to component loses the focus.

Examples of Handling Focus Events

The following applet demonstrates focus events. By clicking the top button in the applet, you can bring up a window that contains a variety of components. A focus listener listens for focus events on each component in the window, including the window itself (which is an instance of a JFrame subclass called FocusWindow).

This is a picture of the applet's GUI. To run the applet, click the picture. The applet will appear in a new browser window.

---

Try this:

1. Bring up the Focus Event Window by clicking the top button in the applet.

   

   If necessary, click the Focus Event Window so that its contents can gain the keyboard focus. You'll see a "Focus gained" message in the applet's display area. The way in which its window gets the focus and which components get the focus are system dependent by default. You can detect when the window gets or loses the focus by implementing a window listener and listening for window activation or deactivation events.
2. Click the button at the right of the Focus Event Window, and then click in another component, such as the text field.
   Notice that when the focus changes from one component to another, the first component generates a focus-lost event before the second component generates a focus-gained event.
3. Try changing the focus by pressing Tab or Shift-Tab.
   Most systems let you use the Tab key to cycle through components that are able to get the focus.
4. Iconify the Focus Event Window.
   You should see a "Focus lost" message for the component that last had the focus.

---

You can find the applet's code in FocusEventDemo.java. Here is the applet's focus event handling code:

public class FocusEventDemo ... implements FocusListener ... {
	...//where initialization occurs
	window = new FocusWindow(this);
    ...
    public void focusGained(FocusEvent e) {
	displayMessage("Focus gained", e);
    }

    public void focusLost(FocusEvent e) {
	displayMessage("Focus lost", e);
    }

    void displayMessage(String prefix, FocusEvent e) {
	display.append(prefix
		       + ": "
		       + e.getComponent()
		       + newline); 
    }
    ...
}

class FocusWindow extends JFrame {
    ...
    public FocusWindow(FocusListener listener) {
	super("Focus Demo Window");
	this.addFocusListener(listener);
	...
	JLabel label = new JLabel("A Label");
	label.addFocusListener(listener);
	...
	JComboBox choice = new JComboBox(/* list of items */);
	...
	choice.addFocusListener(listener);
	...
	JButton button = new JButton("A Button");
	button.addFocusListener(listener);
	...
	JList list = new JList(/* list of items */);
	...
	list.addFocusListener(listener);
    }
}

The FocusEvent Class

Each focus event method has a single parameter: a FocusEvent object. The FocusEvent class defines the following method:

boolean isTemporary()

Returns true if a focus-lost event is temporary. You'll need to use this method if you're implementing a component that can indicate that it will get the focus if its window regains the focus.

The getComponent method, which FocusEvent inherits from ComponentEvent, returns the component that generated the focus event.

Writing Event Listeners