Responding to Mouse Events in a GUI Program

Imagine a small drawing program in which the user clicks on a blank panel to place a dot. The program has to answer a simple question the moment the click happens: where on the panel did the click land? A paint tool may also behave differently when the user is holding a key at the same time, and a menu may need to respond only to the right mouse button. Every one of these decisions depends on information that arrives with the event itself.

In a GUI program, the code that reacts to a mouse action receives a single object describing that action. This object is a MouseEvent, and it carries several pieces of information: the place where the cursor was, the keys the user was holding, and the button involved. As you read this article, follow the three questions a handler usually asks about such an object, and trace what the object reveals at each step: where, with which keys, and with which button.

The MouseEvent exposes the cursor position through two instance methods. The method evt.getX() gives the horizontal position, and evt.getY() gives the vertical position. Both return integers, which means the position is always reported in whole pixels rather than fractions of a pixel. The values describe where the cursor was at the instant the event occurred, not where it is later when your code runs.

The numbers only make sense relative to a reference point. These coordinates are expressed in the coordinate system of the component that generated the event, not the coordinate system of the whole screen. The top left corner of that component is the origin, written (0,0). Moving right increases the x value, and moving down increases the y value. A component placed in the middle of a window still reports (0,0) at its own top left corner, so a handler never has to know where the component sits on screen.

Users often hold a key while they click, and the same click can mean something different when that key is down. A common pattern is that a plain click selects an object while a click with a modifier adds it to the selection. A MouseEvent lets your handler test four such keys, each with its own method: evt.isShiftDown() for the Shift key, evt.isControlDown() for the Control key, evt.isAltDown() for the Alt key, and evt.isMetaDown() for the Meta key.

Each of these methods returns a boolean value. It is true when the key is held at the moment of the event and false otherwise. Because each one answers a yes-or-no question, you can use them directly as the condition of an if statement, and you can combine them when a response depends on more than one key.

Some programs respond differently to the left, middle, and right buttons. For an event caused by a button, evt.getButton() tells you which one. The method returns one of three integer constants: MouseEvent.BUTTON1 for the first button, MouseEvent.BUTTON2 for the second, and MouseEvent.BUTTON3 for the third. On a typical mouse these correspond to the left, middle, and right buttons, although the exact mapping depends on the hardware and its settings.

The mapping in the diagram is the one a learner should expect to see most often, but it is not guaranteed. An event that does not come from a button, such as the pointer simply entering or leaving a component, produces MouseEvent.NOBUTTON instead. Your code can therefore check the constant directly without first worrying about which kind of event it is. A menu that should respond only to the right mouse button can test for MouseEvent.BUTTON3 and ignore everything else.