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 Component Listener

One or more component events are fired by a Component object just after the component is hidden, made visible, moved, or resized. An example of a component listener might be in a GUI builder tool that's displaying information about the size of the currently selected component, and that needs to know when the component's size changes. You shouldn't need to use component events to manage basic layout and rendering.

The component-hidden and component-shown events occur only as the result of calls to a Component's setVisible method (or its deprecated equivalents, show and hide). For example, a window might be miniaturized into an icon (iconified) without a component-hidden event being fired.

The following applet demonstrates component events. The applet contains a button that brings up a window (JFrame). The window contains a panel that has a label and a checkbox. The checkbox controls whether the label is visible. When you leave the applet's page, the window disappears; it reappears when you return to the applet's page. A text area displays a message every time the window, panel, label, or checkbox fires a component event.

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. Click the button labeled "Start playing...".
    The window comes up, generating one or more component-shown and component-moved events.
  2. Click the checkbox to hide the label.
    The label fires a component-hidden event.
  3. Click the checkbox again to show the label.
    The label fires a component-shown event.
  4. Iconify and then deiconify the window that contains the label.
    You do not get component-hidden or -shown events. If you want to be notified of iconification events, you should use a window listener.
  5. Resize the window that contains the label.
    You'll see component-resized (and possibly component-moved) events from all four components -- label, checkbox, panel, and window. If the window and panel's layout manager didn't make every component as wide as possible, the panel, label, and checkbox wouldn't have been resized.

You can find the applet's code in ComponentEventDemo.java. Here is just the code related to handling component events:

public class ComponentEventDemo ... implements ComponentListener {
    ...
    //where initialization occurs:
        aFrame = new JFrame("A Frame");
        ComponentPanel p = new ComponentPanel(this);
        aFrame.addComponentListener(this);
        p.addComponentListener(this);
    ...

    public void componentHidden(ComponentEvent e) {
	displayMessage("componentHidden event from "
		       + e.getComponent().getClass().getName());
    }

    public void componentMoved(ComponentEvent e) {
	displayMessage("componentMoved event from "
		       + e.getComponent().getClass().getName());
    }

    public void componentResized(ComponentEvent e) {
	displayMessage("componentResized event from "
		       + e.getComponent().getClass().getName());
    }

    public void componentShown(ComponentEvent e) {
	displayMessage("componentShown event from "
		       + e.getComponent().getClass().getName());
    }
}


class ComponentPanel extends JPanel ... {
    ...
    ComponentPanel(ComponentEventDemo listener) {
        ...//after creating the label and checkbox:
        label.addComponentListener(listener);
        checkbox.addComponentListener(listener);
    }
    ...
}

The Component Event API

The ComponentListener(in the API reference documentation) interface and its corresponding adapter class, ComponentAdapter(in the API reference documentation), contain four methods:
void componentHidden(ComponentEvent)
Called after the listened-to component is hidden as the result of the setVisible method being called.

void componentMoved(ComponentEvent)
Called after the listened-to component moves, relative to its container. For example, if a window is moved, the window fires a component-moved event, but the components it contains do not.

void componentResized(ComponentEvent)
Called after the listened-to component's size (rectangular bounds) changes.

void componentShown(ComponentEvent)
Called after the listened-to component becomes visible as the result of the setVisible method being called.
Each component event method has a single parameter: a ComponentEvent(in the API reference documentation) object. The ComponentEvent class defines the following useful method:
Component getComponent()
Returns the component that fired the event. You can use this instead of the getSource method.

Examples that Use Component Listeners

The following table lists the examples that use component listeners.

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


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