Introduction to Mouse Events

A GUI program has no main() routine that runs step by step from beginning to end. It must respond to events that happen at unpredictable times and in an order the program does not control.

Programming

Why a Script-Style Program Is Not Enough

Most programs you have written so far run from top to bottom. The program starts at the first instruction, follows a fixed sequence, and finishes at the last one. A GUI program is different. Its behavior depends on what the user does with the mouse and keyboard, and those actions happen at unpredictable times. This article introduces events, the objects that describe user actions, and the event loop that waits for those events and passes them along for handling.

What do you think happens?

The user clicks the mouse, presses the letter a, and then moves the mouse. Which line do you expect the program to print first?

Handling: key press 'a'
Handling: mouse click at (10, 20)
Handling: mouse move to (5, 5)
Program finished

Reveal answer

Answer:

Handling: mouse click at (10, 20)

The events are handled in the order they occur, so the mouse click at (10, 20) is handled first. The verified output lists that line before the key press and the mouse move, and Program finished appears last.

Why There Is No Fixed main() Sequence

A GUI program does not have a main() routine that outlines what will happen when the program is run, step by step from beginning to end. Instead, the program must be prepared to respond to various kinds of events. These events can happen at unpredictable times and in an order that the program does not control.

The most basic kinds of events are generated by the mouse and keyboard. The user can press any key, move the mouse, or press a button on the mouse. The user can do any of these things at any time, and the computer has to respond appropriately. This is why the program is written as a set of responses to events rather than as one fixed sequence of instructions.

Events as Objects

When an event occurs, the system collects all the information relevant to the event and constructs an object to contain that information. In Java, this object is an event object. For example, when the user presses one of the buttons on a mouse, an object belonging to a class called MouseEvent is constructed.

A MouseEvent object contains four pieces of information: the source of the event (the component on which the user clicked), the (x,y) coordinates of the point in the component where the click occurred, the exact time of the click, and which mouse button was pressed. Each of these is a fact about one particular user interaction, and the event object packages them together so they can be passed around as one unit.

What fields does a mouse event object hold, such as the source, the position, the time, and the button, and how does a handler read them?

When the user presses a key on the keyboard, a KeyEvent is created instead. MouseEvent and KeyEvent are both event classes in Java. Once the event object has been constructed, it can be passed as a parameter to a designated method. By writing that method, the programmer says what should happen when the event occurs. The programmer writes the response; the system supplies the event.

The Event Loop

There is a lot of processing between the time a user presses a key or moves the mouse and the time a subroutine in your program is called to respond. As a Java programmer you do not need to know much about that processing, but you should understand the core pattern. Even though you did not write it, a routine is running somewhere that executes a loop of this form: while the program is still running, wait for the next event to occur, then call a subroutine to handle the event.

This loop is called an event loop. Every GUI program has an event loop. In Java, you do not have to write the loop, because it is part of the system. If you write a GUI program in some other language, you might have to provide a main routine that runs the event loop yourself.

In what order do the check, wait, and handle steps repeat, and where does control return to waiting after a handler finishes?

The diagram shows the cycle in the order given by the source's loop. The program checks whether it is still running, waits for the next event, and calls a subroutine to handle that event. After the handler finishes, control returns to the check, so the cycle repeats until the program stops. Notice that the handler is always the part you write, while the waiting and the calling belong to the system.

Tracing the Verified Run

The traced program receives three events in turn: a mouse click at (10, 20), a key press of the letter a, and a mouse move to (5, 5). The verified output of the traced program is exactly the following four lines, in this order.

Output

Handling: mouse click at (10, 20)
Handling: key press 'a'
Handling: mouse move to (5, 5)
Program finished

Worked example

Locating the Origin of Each Printed Line

For each line in the verified output, identify which event and which handler call produced it.

1
Line 1: Handling: mouse click at (10, 20)
The event loop waited, a mouse click event arrived, and a MouseEvent object was constructed holding the click position (10, 20). The loop called the handler for that event, and the handler printed the coordinates.
2
Line 2: Handling: key press 'a'
After the first handler finished, control returned to the check and then to the wait. A key press produced a KeyEvent, and the handler for that event printed the letter a.
3
Line 3: Handling: mouse move to (5, 5)
The loop waited again, a mouse move event arrived, and the handler reported the destination (5, 5). The handler's output reports the destination of the move.
4
Line 4: Program finished
This is the only line not tied to an event. It appears after the last event has been handled, which means the program stopped after the loop's check found it should no longer continue.

Result

The first three lines each come from one handler called by the loop for one event. The final line comes from the program itself, not from any event.

For the mouse click, which part creates the event object, which part passes it along, and which handler produces the printed line?

Mistakes Beginners Make With Event-Driven Programs

The ideas in this article are easy to state but easy to misapply when you start writing GUI code. The following mistakes come directly from the pattern the source describes.

Common mistake
Expecting the program to run its statements in the order they appear in the file
Why it fails
A GUI program has no main() routine that outlines what happens step by step. Its order is set by the events the user produces at unpredictable times.
Do this instead
Think of the program as a set of responses. Ask which event triggers each piece of code, not which line comes next.
Common mistake
Assuming you must write the event loop yourself in Java
Why it fails
In Java the event loop is part of the system. The programmer writes the handling methods.
Do this instead
Focus your code on what happens for each event. Only write your own main routine loop if you are working in a language that does not provide one.
Common mistake
Thinking the event object is the same as the response to the event
Why it fails
The event object only contains information about the user interaction, such as the source, coordinates, time, and button. The response is produced by the handler method that receives the object.
Do this instead
Read the fields of the event object inside the handler, then decide what to do with them.
Common mistake
Treating every printed line as coming from an event
Why it fails
In the verified run, Program finished is not tied to any event.
Do this instead
When tracing output, check each line. Some lines come from handlers and some come from the program's own flow.

Practice Tracing an Event Run

EASY

Suppose a program receives these events in order: a key press of the letter b, then a mouse click at (3, 7), then a mouse move to (9, 2). Without running any code, write the four lines you would expect the verified-style output to show, and for each line name the event that produced it. Then state which line, if any, is not tied to an event.

Hints

Each event triggers one call to its handler, in the order the events occur.
A key press produces a KeyEvent, while a click or move produces a MouseEvent.
The last line of the output in the traced run is the only line not tied to an event.

Your attempt (not saved)

Key Takeaways

A GUI program has no main() routine that runs step by step from beginning to end, because it must respond to events that happen at unpredictable times and in an order the program does not control.
In Java, each event is an object. A MouseEvent records the source component, the (x,y) coordinates, the time, and the mouse button, while a KeyEvent is created for key presses.
Every GUI program has an event loop that waits for the next event and calls a subroutine to handle it. In Java the system provides this loop, so the programmer writes the handling methods.
The verified output of the traced program can be checked line by line: three lines come from handlers for specific events, and Program finished is the only line not tied to an event.