Event handling and GUI programs

The registration form in the last lesson came alive through one call, submitButton.setOnAction(...), and the block of code inside it that ran whenever Submit was pressed. This lesson is about that call. You will see what JavaFX hands your code when the user clicks, the ways to write and attach a handler, and the route an event takes through the window before your code runs. Then you will build four event-driven programs, from an area calculator to an Armstrong number checker, each of which turns text typed into a field into a number, checks it, and shows a result.

What an event is#

A console program decides its own order. It runs main from top to bottom, and when it needs input it stops at scanner.nextInt() and waits. A GUI program hands that control to the user. start builds the window and returns, and from then on the program waits for the user to act: press a button, type a key, close the window. Each action is an event, and which of your code runs next depends on which event arrives. This style is called event-driven programming.

You do not write the waiting. Glass, the windowing layer from the JavaFX overview, receives each mouse and keyboard action from the operating system. JavaFX turns it into an object, works out which node it is meant for, and calls the code you attached to that node for that kind of event. All of this happens on one thread, the JavaFX Application Thread. Your part is to attach the code.

Event handling has three parts. For a click on the area calculator's Calculate Circle Area button they are:

• The event. An object describing what happened, of class javafx.event.Event or a subclass, here ActionEvent. It records its type (getEventType(), here ActionEvent.ACTION), its source (getSource(), the object whose handler is running) and its target (getTarget(), the node the event is aimed at). Mouse and key events also carry details: the pointer's coordinates, which mouse button, which key.
• The event source. The node the user acted on, here circleButton. Handlers are registered on it, and it passes each event to them.
• The event handler. The code that runs in response, registered on the source before any event happens: circleButton.setOnAction(e -> calculateCircleArea(circleInput.getText())). It is an object implementing EventHandler, and JavaFX calls its handle method once for every event.

One click produces more than one event. Pressing the mouse button over circleButton fires a MouseEvent of type MOUSE_PRESSED; letting go fires MOUSE_RELEASED and then MOUSE_CLICKED. The button's built-in behaviour watches the press and the release and, when both happen over it, fires one more event of its own: an ActionEvent aimed at itself. That is the event setOnAction listens for. An ActionEventmeans “the button was used”, by whatever means, so the same handler also runs when the user presses Space while the button has focus, or Enter when it is the default button, as Submit is in the registration form.

Key idea

You never ask whether the button was clicked. You give JavaFX a handler in advance, and JavaFX calls it, with an event object describing the click, at the moment the click happens.

EventHandler: one interface, one method#

Every handler, however it is written, ends up as an object of a class that implements this interface from javafx.event:

<T extends Event> is a type parameter. A handler declares which kind of event it accepts, and T must be Event or one of its subclasses: an EventHandler<ActionEvent> takes action events, an EventHandler<MouseEvent> takes mouse events, and the compiler will not let you register one where the other is expected. handle is the method JavaFX calls, passing the event in. Because it is the only abstract method, EventHandler is a functional interface, so wherever one is expected you can write a lambda instead of a whole class. (EventListener is an empty marker interface from java.util; it adds no methods.)

Registering a handler#

A handler does nothing until it is registered on a node. For each common event type, nodes have a convenience method named setOnfollowed by the event. These four lines could go into the area calculator's start method, one for each event class in the table:

Enter in the Radius field now calculates the area, like the button.
A click on the Radius: label puts the cursor in the Radius field.
Typing 7 into the Height field prints Key pressed: DIGIT7 in the console.
Closing the window prints Calculator closed in the console.

The parameter e has a different type in each line, taken from the method it is passed to. In setOnKeyPressed it is a KeyEvent, which is why e.getCode() compiles there and would not compile in the setOnAction line.

setOnAction replaces, addEventHandler adds#

A setOn method stores exactly one handler. Call it a second time and the first handler is gone. When two separate pieces of code must both react to the same event, use addEventHandler, the general method underneath, which keeps a list.

Clicking Calculate Circle Area prints:
second

Clicking Calculate Rectangle Area prints:
one
two

Writing a handler: three forms#

Handlers are usually written in one of two ways. The registration form from the last lesson uses an anonymous inner class; every program in this lesson uses lambdas, sometimes one line long and sometimes a whole block. A third form, the method reference, turns up in other code. Each one produces the same thing: an object with a handle method that JavaFX can call.

An anonymous inner class (the registration form)#

Submit pressed (or Enter, since Submit is the default button) with the name empty:
an error alert titled "Form Error!" saying "Please enter your name".
With all three fields filled: a confirmation alert, "Registration Successful!",
saying "Welcome " followed by the name.

Read new EventHandler<ActionEvent>() { ... } as two things at once. It declares a class with no name that implements EventHandler<ActionEvent>, and it creates one object of that class. The class body overrides handle, and setOnAction stores the object on the button: that is what registering a handler means. None of the code inside handle runs at this point. It runs later, each time the button fires: whenever the user clicks Submit, or presses Enter. Enter works because the same method called submitButton.setDefaultButton(true) a few lines earlier.

Each return ends this one call of handle straight after its error alert, so the confirmation alert at the bottom is reached only when all three fields have text.

A one-line lambda (the area calculator)#

From the area calculator on, every handler in this lesson is a lambda. These are the calculator's three registrations:

Take the first line apart. e is the parameter of handle, the ActionEvent. Its type is not written because setOnAction expects an EventHandler<ActionEvent>, so the compiler already knows it. After the arrow comes the body, a single expression with no braces: a call to a private method, passing whatever text is in the radius field. The handler never looks at e. That is normal for buttons: the event only says the button was pressed, and each handler already belongs to one button.

circleInput.getText() sits inside the lambda, so it runs at click time and reads what the user has typed by then. Had the code copied the text into a variable before calling setOnAction and used that variable instead, every click would see the empty string the field held while start was running.

Forwarding to a named method keeps start short and gives each calculation a name. The perfect number checker does the same with checkButton.setOnAction(e -> checkPerfectNumber()).

A block lambda (the interest calculator)#

When a handler needs several statements, the body goes in braces. The interest calculator's Simple Interest handler parses three fields, checks them, computes and displays, all inside the lambda:

Inside the braces you write an ordinary method body: local variables, if, try and catch. Nothing is returned, because handle is void. A few lines read well inline; a long body is easier to follow as a named method called from a one-line lambda, as in the area calculator.

A method reference#

When a method already has the shape of handle, taking one ActionEvent and returning nothing, you can pass the method itself with ::. The programs here never do this, but you will see it in other code:

this::onCheck means “when handle(event) is called, call onCheck(event) on this object”. The shapes must match. this::checkPerfectNumber does not compile, because checkPerfectNumber takes no parameter and handle passes one; javac reports an invalid method reference.

Anonymous class or lambda#

Both forms build an object that implements EventHandler. They differ in four ways.

For your own code, write the lambda unless you need something only a class can have, such as a field of its own that keeps a count from one click to the next.

Why captured variables must be effectively final#

Look at what the registration form's handler uses: nameField, emailField, passwordField and gridPane. All four are local variables or parameters of addUIControls, and addUIControls has long finished by the time anyone presses Submit. Its local variables are gone. The handler can still use them because Java copied their values into the handler object when it was created. A copy is only safe if the original never changes afterwards, so Java has a rule: a local variable used inside a lambda or an anonymous class must be final or effectively final, meaning it is assigned once and never again.

error: local variables referenced from a lambda expression must be final or effectively final

Two things remain allowed. Calling a method on a captured object is fine, because the variable still points at the same object: resultField.setText(...) changes the text field, not the variable, and the interest and Armstrong handlers do exactly that with a local resultField. And a field of the class is not captured at all; the lambda reaches it through the object, so it may change a field freely. That is the fix for the counter: declare private int clicks = 0; as a field instead, and clicks++ compiles.

How an event reaches its handler#

Between the click and your handler, JavaFX takes four steps. They complete the picture, and they explain behaviour that otherwise looks odd, such as a pane reacting to a click on a button inside it.

1. 1Target selection. JavaFX decides which node the event is for. A mouse event goes to the topmost node under the pointer, a key event to the node with keyboard focus, and an ActionEvent to the control that fired it.
2. 2Route construction. It builds the event dispatch chain: the path from the stage, through the scene and each parent, down to the target. For circleButton that is Stage, Scene, GridPane, Button.
3. 3Capturing phase. The event travels down the route from the stage to the target. Event filters, registered with addEventFilter, run on the way down.
4. 4Bubbling phase. The event travels back up from the target to the stage, and event handlersrun on the way: the target's first, then its parent's, and so on. Every handler registered with a setOn method or addEventHandler runs in this phase.

A filter or handler anywhere on the route can call event.consume(). The event stops where it is, and nodes further along the route never see it.

Key idea

Filters run on the way down, handlers on the way back up, and consume() ends the trip wherever it is called.

The route in code#

This fragment gives the calculator's GridPane a filter and a handler for ActionEvent, beside the button's own handler, and prints from each:

Clicking Calculate Circle Area prints:
1. filter on the grid
2. handler on the button
3. handler on the grid
   source: GridPane
   target: Calculate Circle Area

With e.consume() added to the filter, only the first line prints:
the event never reaches the button.

The last two lines show the difference between source and target. In the button's own handler both are the button. In the grid's handler the source is the grid, because getSource() always names the node whose handler is running, while the target is still the button that fired. One handler on a parent can therefore serve many buttons, using getTarget() to tell which one was pressed.

Reading numbers from text fields#

Every handler in the four programs follows the same five steps. Once you see the shape, each program is a variation on it.

1. 1Read. getText() returns the field's contents as a String, always. An empty field gives the empty string "".
2. 2Parse. Integer.parseInt or Double.parseDouble turns the text into a number. This is the step that fails when the user types abc.
3. 3Validate. Check what parsing cannot, such as a negative principal. If the value is unusable, throw new IllegalArgumentException(...) with a message for the user.
4. 4Compute. The formula or the loop.
5. 5Show. setText on a result field, usually one made read-only with setEditable(false).

Key idea

Everything in a TextField is a String until you parse it, and parsing is the step that fails.

NumberFormatException: text that is not a number#

Integer.parseInt("42") returns 42. Given text that is not a whole number, it has nothing sensible to return, so it throws NumberFormatException. The two parse methods differ on a few inputs worth knowing:

NumberFormatException is unchecked, so the compiler does not make you catch it. Leave it uncaught and it escapes the handler: JavaFX prints the stack trace in the console, the window carries on, and the user sees nothing change. Catching it is how the user learns what went wrong.

IllegalArgumentException: a number you refuse#

-5 parses perfectly well, but a negative principal makes no sense, and neither does the factorial of a negative number. The interest and Armstrong programs reject such values by throwing an exception themselves:

throw jumps straight to the matching catch and skips the calculation. That catch shows ex.getMessage(), the text given to the constructor, so the user reads Negative values not allowed in the result field. The checks stay a flat list at the top of the handler, and every failure ends up in one place.

Catch order: the subclass first#

NumberFormatException is a subclass of IllegalArgumentException:

Java tries catch blocks from top to bottom and runs the first one whose type matches. A catch (IllegalArgumentException ex) matches a NumberFormatException too, because an object of a subclass is also an instance of its superclass. Put that block first and the NumberFormatException block below it could never run. Java treats an unreachable catch as an error:

error: exception NumberFormatException has already been caught

The programs use the order that compiles: NumberFormatException first, so text that is not a number gets its own message, then IllegalArgumentException for the values the code rejected itself.

Division by zero: doubles do not throw#

Infinity and NaN (“not a number”) are genuine doublevalues, defined by the IEEE 754 standard that Java's double follows. Nothing stops them: they flow into later arithmetic and reach a result field as text. Make the two variables ints holding 5 and 0, and the first division stops the program with java.lang.ArithmeticException: / by zero.

Example: an area calculator#

The task: a JavaFX calculator that works out the area of a circle, a rectangle and a triangle, shows the answer in a text field, and handles bad input with exceptions.

Start from the inputs. A circle needs a radius, a rectangle a length and a width, a triangle a base and a height: five text fields. Each shape gets its own button, and all three buttons write to one shared result field that the user cannot edit. A two-column GridPane holds it all, with labels in column 0 and everything else in column 1, one shape after another down the rows.

The layout#

Every control gets its cell from one GridPane.setConstraints(node, column, row) line. The figure draws each control where its line puts it, filled in with sample values.

Placing a node takes two steps in this program. GridPane.setConstraints(circleLabel, 0, 0) is a static method: it writes “column 0, row 0” onto the label itself and changes nothing on screen. The label appears only when grid.getChildren().addAll(...) puts it in the grid, which then reads the position stored on it. The interest and Armstrong programs use grid.add(node, column, row), which does both steps in one call. The two styles fail in different ways: a node that gets constraints but is left out of addAll never appears, and a node added without constraints lands in column 0, row 0, on top of whatever is already there.

The complete program#

A 400 by 300 window titled "Simple Calculator".
With 5, 3, 4, 4 and 7 in the five fields, the three buttons show:
Circle Area: 78.53981633974483
Rectangle Area: 12.0
Triangle Area: 14.0
With abc in a field, its button shows: Invalid input

resultField is declared as a field, above main, while every other control is a local variable inside start. The reason is reach. The three calculate methods are separate methods of the class and must write to the result field, so it has to belong to the object. The input fields never need to leave start: each lambda reads its fields at click time and passes the text in as an argument. setEditable(false) stops the user typing into the answer (it can still be selected and copied), and setPromptText("Result") shows Result in grey until there is an answer.

The three calculate methods share one shape: parse inside try, compute, display, and on NumberFormatException display Invalid input. Parsing comes first, so a bad value stops the method before any arithmetic happens. The circle uses Math.PI * Math.pow(radius, 2); radius * radius gives the same number. Joining a double onto a String prints it in full, so a radius of 5 shows Circle Area: 78.53981633974483. The interest calculator, later, rounds with String.format.

Two things to watch for. The program accepts negative lengths without complaint: a radius of -5 gives the same area as 5, because squaring removes the sign, and a rectangle of -3 by 4 reports Rectangle Area: -12.0. And the scene is 300 pixels tall, a little less than nine rows of controls with 8-pixel gaps need, so the result field is cut off at the bottom edge; new Scene(grid, 400, 340) gives it room. (Divide by zero cannot happen here, as the section on reading numbers explained.)

The formulas as a console program#

The formulas themselves are plain Java, so they can run here. Each shape becomes a static method, and main passes in sample values instead of reading text fields.

The output matches the window. Rectangle Area prints as 12.0, not 12, because the parameters are doubles, and a double always prints with a decimal point.

Example: a perfect number checker#

The task: a window with two text fields and a Check button. The user types a whole number into the first field. When they click Check, the second field says whether it is a perfect number, and if it is not, shows the sum of its digits instead.

A perfect number equals the sum of its proper divisors, the divisors smaller than the number itself. 6 is perfect: its proper divisors are 1, 2 and 3, and 1 + 2 + 3 = 6. The next is 28 (1 + 2 + 4 + 7 + 14), then 496 and 8128. Those four are the only ones below ten thousand.

isPerfectNumber adds up the divisors. It starts sum at 1, because 1 divides every number, and tries each i from 2 up to number / 2. Half is far enough: the smallest divisor above 1 is at least 2, so the largest proper divisor is at most half the number. For 28 the loop tries 2 to 14 and finds 2, 4, 7 and 14. The guard if (number <= 1) return false; deals with 1, 0 and every negative number, none of which is perfect. Without it, 1 would pass, since sum starts at 1 and the loop never runs.

sumOfDigits is the digit-peeling loop from the loops lesson: number % 10 is the last digit, and number /= 10 drops it. For 567:

The complete program#

A 300 by 200 window titled "Perfect Number Checker".
28 and Check:  28 is a perfect number.
567 and Check: Sum of digits: 18
abc and Check: Invalid input. Please enter an integer.

Both inputField and resultField are fields this time, because checkPerfectNumber reads one and writes the other and takes no arguments, which shrinks the handler to e -> checkPerfectNumber(). The area calculator chose the other design, passing the text in as an argument and keeping only the result as a field. Both work. Notice too that isPerfectNumber and sumOfDigits contain no JavaFX at all, which is what lets the snippet below run them in the visualizer.

Watch for negative input. -567 is not perfect, so the program shows its digit sum, and Java's % keeps the sign of the number being divided: -567 % 10 is -7, so the field shows Sum of digits: -18.

Stepping through the two methods#

Here are the two methods with a main that checks 28 and 567, the two cases the window has to tell apart. Step through it with the trace open.

For 28, watch sum pick up 2, 4, 7 and 14 on top of its starting 1 and land on exactly 28. For 567, isPerfectNumber tries every i from 2 to 283, ends with 401, and returns false; then sumOfDigits strips 567 down to 18. That second trace is long, and it is a fair picture of the work one click on Check does.

Example: an interest calculator#

The task: a JavaFX application that calculates simple interest, compound interest and the monthly payment on a loan (EMI), shows the result in a text field, and handles invalid input with exceptions.

The three formulas#

With P the principal (the amount borrowed or invested), R the yearly interest rate in percent and T the time in years:

• Simple interest, paid on the principal only: SI = P * R * T / 100.
• Compound interest, where each year's interest joins the balance and earns interest itself: CI = P * (1 + R / 100)^T - P. Subtracting P leaves only the interest.
• EMI, the equated monthly instalment, the fixed monthly payment that repays a loan with its interest: EMI = P * r * (1 + r)^n / ((1 + r)^n - 1), where r = R / (12 * 100) is the monthly rate and n = T * 12 is the number of months.

Here ^ means “to the power of”. In Java that is Math.pow; Java's own ^ operator is bitwise exclusive or, so 2 ^ 3 is 1, not 8.

With P = 10000, R = 10 and T = 2: simple interest is 10000 * 10 * 2 / 100 = 2000.00. Compound interest is 10000 * 1.1 * 1.1 - 10000 = 12100 - 10000 = 2100.00. For the EMI, r is 10 / 1200 = 0.008333... and n is 24, so (1 + r)^24 is about 1.22039, and the EMI is 10000 * 0.008333 * 1.22039 / 0.22039, about 461.45 a month.

The complete program#

A 550 by 250 window titled "Interest Calculator".
With 10000, 10 and 2 in the three fields:
Simple Interest shows    2000.00
Compound Interest shows  2100.00
EMI shows                461.45
A letter in any field shows Invalid input!
A negative value shows Negative values not allowed
EMI with a zero shows Values must be greater than zero

All three handlers are block lambdas with the same skeleton: parse the three fields, validate, compute, format. Every control is a local variable in start; none needs to be a field, because all the work happens inside lambdas, which can use the effectively final locals around them. start has no @Override here. It still overrides Application.start; the annotation is optional and only asks the compiler to check.

String.format("%.2f", si) turns the result into text with exactly two digits after the decimal point, rounding the rest: % starts a format, .2 is the number of decimal places, and f means a decimal number. The rounding matters, because the raw results are not tidy. The compound interest really comes out as 2100.000000000002, since 1.1 has no exact binary form, and the EMI as 461.44926337516654. Formatted, they show as 2100.00 and 461.45.

Simple and compound interest reject only negative values (p < 0 || r < 0 || t < 0), so zero is allowed, and a 0% rate correctly gives 0.00. The EMI check is stricter, p <= 0 || annualRate <= 0 || years <= 0, and its rate test is there for a reason. With a rate of 0, monthlyRate is 0, the top of the formula is P * 0 * 1 = 0 and the bottom is 1 - 1 = 0. 0.0 / 0.0 is NaN, so without the check the field would show NaN. A 0% loan is not impossible, though: its EMI is P / n, 10000 / 24 = 416.67 for the example. One more edge: (int) (years * 12) truncates, so 0.05 years becomes 0 months, the bottom of the formula is 0 again, and the field shows Infinity.

This program places nodes with grid.add. The five-argument form, grid.add(resultField, 1, 4, 2, 1), adds a column span and a row span: start at column 1, row 4, and cover 2 columns and 1 row. That is why the result field is wider than the inputs.

Each column is as wide as its widest node. Column 1 is sized by its text fields, which are wider than the Compound Interest button, so the EMI button sits after a visible gap.

The formulas as a console program#

The visualizer has no String.format, so this version prints the raw doubles. That turns out to be useful: you see exactly what the window rounds.

Match each line to the window: 2000.0 formats as 2000.00, 2100.000000000002 as 2100.00, and 461.44926337516654 as 461.45. The stray 2 at the end of the compound interest comes from 1.1, which a double can only approximate; squaring it carries the error into the twelfth decimal place. Real Java prints these same three lines.

Example: Armstrong number or factorial#

The task: a window with an input field, an output field and a button. When the button is clicked, check whether the number typed in is an Armstrong number. If it is, say so; if not, show its factorial. Invalid input must be handled with exceptions.

An Armstrong number equals the sum of its own digits, each raised to the power of the number of digits. 153 has three digits, and 1³ + 5³ + 3³ = 1 + 125 + 27 = 153. The other three-digit ones are 370, 371 and 407, and the four-digit ones are 1634, 8208 and 9474. Every one-digit number qualifies, since a digit to the power 1 is itself, and there are no two-digit Armstrong numbers at all.

The handler makes two passes over the digits. The first only counts them, dividing by 10 until nothing is left: 153 becomes 15, then 1, then 0, so three digits. Zero needs its own case, digits = 1, because while (temp != 0) would not run even once for it. The second pass peels the digits off again with % 10 and adds each one raised to that power.

One line deserves a closer look: sum += Math.pow(digit, digits);. Math.pow returns a double, and sum is an int. The long form, sum = sum + Math.pow(digit, digits);, does not compile (“possible lossy conversion from double to int”). The compound form does, because Java defines sum += x as sum = (int) (sum + x): the cast is built in. Here it is also safe, because Math.pow is exact for small whole numbers; Math.pow(5, 3) is exactly 125.0.

The complete program#