Previous | Next | Trail Map | To 1.1 -- And Beyond! | GUI Changes: The AWT Grows Up


Writing a Mouse Listener

Mouse events tell you when the user uses the mouse (or similar input device) to interact with a component. Mouse events occur when the cursor enters or exits a component's on-screen area and when the user presses or releases the mouse button. Because tracking the cursor's motion involves significantly more system overhead than tracking other mouse events, mouse motion events are separated into a separate listener type (see Writing a Mouse Motion Listener).

Mouse Event Methods

The MouseListener(in the API reference documentation) interface and its corresponding adapter class, MouseAdapter(in the API reference documentation), contain three methods:
void mouseClicked(MouseEvent)
Called by the AWT just after the user clicks the listened-to component.
void mouseEntered(MouseEvent)
Called by the AWT just after the cursor enters the bounds of the listened-to component if the mouse button is not down. [CHECK]
void mouseExited(MouseEvent)
Called by the AWT just after the cursor leaves the bounds of the listened-to component if the mouse button is not down. [CHECK]
void mousePressed(MouseEvent)
Called by the AWT just after the user presses a mouse button while the cursor is over the listened-to component.
void mouseReleased(MouseEvent)
Called by the AWT just after the user releases a mouse button. The mouse released event is fired off by the same component that just generated the mouse pressed event, no matter where the cursor is when the button release occurs.

Examples of Handling Mouse Events

The following applet demonstrates mouse events. At the top of the applet is a blank area (implemented, strangely enough, by a class named BlankArea). A mouse listener listens for events both on the BlankArea and on its container, which is an instance of MouseDemo. Each time a mouse event occurs, a descriptive message is displayed under the blank area. By moving the cursor on top of the blank area and clicking mouse buttons occasionally, you can see when mouse events are generated.

Since you can't run the applet, here's a picture of it:


Try this:
  1. Move the cursor into the rectangle [which we should color in] at the top of the applet.
    You'll see one or more mouse enter events [which should be displayed as that instead of "Custor enter"].
  2. Press and hold the mouse button.
    You'll see a mouse press event. You might see some extra mouse events, such as mouse exit and then enter.
  3. Release the mouse button.
    You'll see a mouse release event. If you didn't move the mouse, a mouse click event will follow.
  4. Press and hold the mouse button, and then drag the mouse so that the cursor ends up outside the applet's area. Release the mouse button.
    You'll see a mouse press event, followed by a mouse exit event, followed by a mouse release event. You are not notified of the cursor's motion. To get mouse motion events, you need to implement a mouse motion listener.

You can find the applet's code in MouseDemo.java. Here is the applet's mouse event handling code: [FIXME]
public class MouseDemo ... implements MouseListener {
	...//where initialization occurs:
        //Register for mouse events on blankArea and applet (panel).
        blankArea.addMouseListener(this);
        addMouseListener(this);
    ...

    public void mousePressed(MouseEvent e) {
       saySomething("Mouse button press", e);
    }

    public void mouseReleased(MouseEvent e) {
       saySomething("Mouse button release", e);
    }

    public void mouseEntered(MouseEvent e) {
       saySomething("Cursor enter", e);
    }

    public void mouseExited(MouseEvent e) {
       saySomething("Cursor exit", e);
    }

    public void mouseClicked(MouseEvent e) {
       saySomething("Mouse button click", e);
    }

    void saySomething(String eventDescription, MouseEvent e) {
        textArea.append(eventDescription + " detected on "
                        + e.getComponent().getClass().getName()
                        + ".\n");
        textArea.setCaretPosition(maxInt); //scroll to bottom
    }
}

You can find more examples of mouse listeners in the following sections: [LIST GOES HERE]

The MouseEvent Class

Each mouse event method has a single parameter: a MouseEvent(in the API reference documentation) object. The MouseEvent class defines the following useful methods:

int getClickCount()
Returns the number of quick, consecutive clicks the user has made (including this event)[CHECK].

int getX()
int getY()
Point getPoint()
Return the (x,y) position at which the event occurred, relative to the component over which the event occurred.
boolean isPopupTrigger()
Returns true if the mouse event should cause a popup menu to appear. Because popup triggers are platform dependent, if your program uses popup menus, you should call isPopupTrigger for both mouse down and mouse up events.

The MouseEvent class extends InputEvent(in the API reference documentation), which extends ComponentEvent(in the API reference documentation). ComponentEvent provides the handy getComponent method. InputEvent provides the following useful methods:

int getWhen()
Returns the timestamp of when this event occurred. The higher the timestamp, the more recently the event occurred. [CHECK!]

boolean isAltDown()
boolean isControlDown()
boolean isMetaDown()
boolean isShiftDown()
Convenient methods giving you the state of the modifier keys when the event was generated.

int getModifiers()
Returns a flag indicating the state of all the modifier keys when the event was generated.


Previous | Next | Trail Map | To 1.1 -- And Beyond! | GUI Changes: The AWT Grows Up