The JavaTM Tutorial
Previous Page Lesson Contents Next Page Start of Tutorial > Start of Trail > Start of Lesson Search

Trail: Creating a GUI with JFC/Swing
Lesson: 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. 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 fired 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.

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).

Click this figure to run the applet.
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.

    The Focus Event Window, which demonstrates the events that are fired when the keyboard focus changes.

    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 fires a focus-lost event before the second component fires a focus-gained event.
  3. Select an item from the combo box.
    The combo box does not a fire focus-gained event even though it appears to have the focus. Now select another component in the Focus Event Window. The combo box does not fire a focus-lost event either.
  4. 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.
  5. 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 Focus Event API

The FocusListener(in the API reference documentation) interface and its corresponding adapter class, FocusAdapter(in the API reference documentation), 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.
Each focus event method has a single parameter: a FocusEvent(in the API reference documentation) 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(in the API reference documentation), returns the component that fired the focus event.

Examples that Use Focus Listeners

The following table lists the examples that use focus listeners.

Example Where Described Notes
FocusEventDemo This section Reports all focus events that occur on several components to demonstrate the circumstances under which focus events are fired.


Previous Page Lesson Contents Next Page Start of Tutorial > Start of Trail > Start of Lesson Search