Using Components, the GUI Building Blocks

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 interface and its corresponding adapter class, MouseAdapter, 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.

void mouseExited(MouseEvent)

Called by the AWT just after the cursor leaves the bounds of the listened-to component.

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 after a mouse press over the listened-to component.

One complication affects mouse-entered, mouse-exited, and mouse-released events. When the user drags (presses and holds the mouse button and then moves the mouse), then the component that the cursor was over when the drag started is the one that receives all subsequent mouse and mouse-motion events up to and including the mouse button release. That means that no other component will receive a single mouse event -- not even a mouse-released event -- while the drag is occurring.

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

---

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. Move the cursor into the rectangle at the top of the applet.
   You'll see one or more mouse enter events.
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 MouseEventDemo.java and BlankArea.java. Here is the applet's mouse event handling code:

public class MouseEventDemo ... 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 source files:

• SimpleClick.java
• CoordinatesDemo.java
• RectangleDemo.java
• AnimatorApplet.java
• AnimatorApplication.java

The MouseEvent Class

Each mouse event method has a single parameter: a MouseEvent 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).

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, which extends ComponentEvent. 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.

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 modifiers when the event was generated. Besides the modifier keys, this flag indicates which mouse button was pressed. For example, the following expression is true if the right button was pressed:

(mouseEvent.getModifiers() & InputEvent.BUTTON3_MASK)
== InputEvent.BUTTON3_MASK

The SwingUtilities class contains convenience methods for determining whether a particular mouse button has been pressed:

static boolean isLeftMouseButton(MouseEvent)
static boolean isMiddleMouseButton(MouseEvent)
static boolean isRightMouseButton(MouseEvent)

Using Components, the GUI Building Blocks