Using Components, the GUI Building Blocks

Writing a Focus Listener

Focus events are generated whenever a component gains or loses the keyboard focus -- the ability to receive keyboard events. From the user's point of view, the component with the keyboard focus is usually prominent -- with a thicker border than usual, for example -- and the window containing the component is also more prominent than other windows on-screen. This lets the user know which component any typing will go to. At most one component in the window system can have 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. You can request that a component get the focus by invoking the Component requestFocus method.

Focus Event Methods

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

void focusGained(FocusEvent)

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

void focusLost(FocusEvent)

Called by the AWT 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 Frame subclass called FocusWindow).

---

Note: The above applet requires JDK 1.1. If you are using an older browser that does not support 1.1, you won't be able to run the applet. Instead, you need to view this page in a 1.1 browser, such as HotJava, the JDK Applet Viewer (appletviewer), or certain versions of Netscape Navigator and Internet Explorer. For more information about running applets, refer to About Our Examples.

---

---

Try this:

1. Bring up the window called Focus Demo Window by clicking the top button in the applet. It should look like this:

   

2. If necessary, click the Focus Demo Window so that its contents can gain the keyboard focus.
   You'll see a "Focus gained" message in the applet's display area. How its window gets the focus and which of its components gets the focus by default [CHECK] are system dependent. You can detect when the window gets or loses the focus by implementing a window listener and listening for window activation or deactivation events.
3. Click the button at the right of the Focus Demo 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.
4. Try changing the focus by pressing Tab or Shift-Tab.
   Most systems let you use the Tab key to cycle through components that can get the focus.
5. Miniaturize the Focus Demo Window into an icon.
   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.getSource() //XXX
		       + "\n"); 
    }
    ...
}

class FocusWindow extends Frame {
    ...
    public FocusWindow(FocusListener listener) {
	super("Focus Demo Window");
	this.addFocusListener(listener);
	...
	Label label = new Label("A Label");
	label.addFocusListener(listener);
	...
	Choice choice = new Choice();
	...
	choice.addFocusListener(listener);
	...
	Button button = new Button("A Button");
	button.addFocusListener(listener);
	...
	List list = new List();
	...
	list.addFocusListener(listener);
    }
}

The FocusEvent Class

Each focus event method has a single parameter: a FocusEvent object. The FocusEvent class defines a method, isTemporary, which returns true if a focus lost event is temporary. It's essential knowledge when you wish to indicate that a particular component will get the focus if its window regains the focus.

The most common message you'll send to a FocusEvent object is getComponent (defined in ComponentEvent), which returns the component that just gained or lost the focus, causing the focus event.

Using Components, the GUI Building Blocks