MouseListener and Mouse Click Handling

Every time the mouse moves, the computer produces mouse motion events. The operating system consumes these events to redraw the pointer on the screen, but a program can also observe the same events and react to them. The usual reason to do this is to let the user drag something: pick up an object with the mouse, move it, and let go. This article shows how a program hooks into those motion events, which methods receive them, and how to follow the flow of a drag through the code.

The whole mechanism depends on one fact: whether any mouse button is held down at the moment the pointer moves. That fact is tracked by the system, not by your program. Your code never decides which handler runs; it only receives the call. So the most useful way to reason about a mouse event is to ask two questions in order: what is the button state right now, and therefore which handler is about to be called?

The diagram below shows the button state moving between two conditions. Each pointer movement is answered by whichever handler matches the state at that moment. Pressing the button switches the state to held, and releasing it switches the state back to idle.

Notice that the state, not the movement itself, is what changes the handler. The same physical motion of the pointer produces mouseMoved while the button is up and mouseDragged while it is held. Keep this in mind when tracing: before each call, look up the state the button is in at that moment.

Mouse motion handling is organized around a single interface called MouseMotionListener. It declares two methods, and each covers a different situation. The deciding factor is whether any mouse button is held down while the pointer moves. If one is, the program receives a call to mouseDragged. If no button is down, the program receives a call to mouseMoved instead.

Both methods take one parameter of type MouseEvent. That object carries the x and y coordinates of the mouse's location at the moment the event occurred. A class that implements the interface must supply both methods, even if it only cares about dragging. The declarations have this shape:

The parameter name evt is only a convention in the declaration. Inside a handler, the coordinates are read from that event object, which is how the program learns where the pointer currently is during the drag.

Here is a small listener that reacts to dragging. It implements both methods, as the interface requires. Its mouseDragged handler reads the coordinates from the event, while mouseMoved does nothing because this listener only cares about drags. This example is written for illustration; it is not taken from the source.

Implementing the interface is only half of the job. The listener must also be connected to the component whose mouse motion it should hear. This connection is made by calling the component's addMouseMotionListener() method and passing in the listener object. Until that call happens, the listener receives no motion events from that component at all.

Now consider a sequence of actions on a registered component: the button is pressed, the pointer moves, the button is released, and the pointer moves again. The diagram shows the calls the listener receives, in order. Before reading the diagram, try to predict which handler fires for each movement.

Mouse motion handlers are declared in a separate interface from the other mouse events. The reason is volume. Motion events are generated whenever the pointer moves, which means a very large number of them. A program that only cares about clicks would be inefficient if it were forced to hear every movement. Keeping the motion methods in MouseMotionListener lets a program listen for other mouse events without automatically receiving all motion events too.

The two interfaces are separate in the language, but a single object can implement both when its job requires it. A listener that handles dragging often also implements MouseListener so that it can respond to the other mouse events as well.