Writing Event-Handling Methods

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. In this article we follow the three questions a handler usually asks about such an object, and we trace what the object reveals at each step.

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. The 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. The diagram below shows the layout of these values inside one component.

Because the origin belongs to the component, the position is a property of the click inside that component. The event object carries the position, and the two getter methods read the two numbers out. The origin is tied to the component, which is why the same numbers would mean something different if the component were moved or resized inside another layout.

The practical benefit is that the drawing code can place a dot using the numbers directly. A point at (40, 25) inside the panel is always 40 pixels from the panel's left edge and 25 pixels from its top edge, regardless of where the window is on the desktop.

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 with four separate methods: evt.isShiftDown(), evt.isControlDown(), evt.isAltDown(), and evt.isMetaDown().

Each of these methods returns a boolean value, which 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 it 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.

Not every mouse event comes from a button. The pointer simply entering or leaving a component is a mouse event, and events such as mouseEntered and mouseExited involve no button at all. For these, evt.getButton() returns MouseEvent.NOBUTTON instead of one of the three button constants. Your code can therefore check the constant directly without first worrying about which kind of event it is.

Not every computer has three physical buttons. A trackpad or a single-button mouse may emulate the other buttons, for example through a two-finger tap on a trackpad. The event your handler receives then carries the emulated button's constant, so the same code works without special cases for different hardware.