A Definitive Guide To JavaFX Events

JavaFX’s user interfaces are almost completely event-driven. Most people are familiar with action events, key events and mouse events, but almost every complex update to a user interface is accomplished using events of one sort or another. And yet, Events are one of the most under-played parts of JavaFX.

As a general rule, if you need to accomplish a simple value-based change, this can be done with Property binding. For everything else, I use events.

What is an Event?

If you’ve ever sorted a column in a TableView, changed a TreeView, or edited a cell, you’ve already used events to update the interface in the background. Events are a versatile, stable way to drive changes on the JavaFX Application thread by setting executable code ahead of time.

An Event is any change of state in an input device (such as mouse or touch screen), a user action (ActionEvent), or a background task. Events can also be fired as a result of scroll or edit events on complex nodes such as TableView and ListView.

At a very basic level, the Event object is a class with a surprisingly small number of parameters. It doesn’t hold any executable code, nor does it run any code. It’s a flag to the system that something has changed.

JavaFX then provides significant support to run executable code, defined separately through the EventHandler class, on any changes of state. There are 90 separate types of event supported by JavaFX, with the capability to extend the Event class and define additional custom functionality.

How to use this resource

Events are such a fundamental part of JavaFX, I thought they deserved an attempt to summarise everything in one place. I’ll attempt to do that justice by going through:

I’ve tried to make this article as readable as possible, whilst also including as much of the useful information that usually gets left out. To that end, low-level detail and code examples are inside drop-downs to make scrolling a little less painful.

1. How Events Work

I wasn’t lying when I said an Event is surprisingly simple. What is complicated is the background processes that implement the event handling system. In this section, we’ll go through what defines an Event, and how to set up your code to execute whenever a certain event is detected.

The Event Class

In JavaFX, an Event has four properties:

The boolean parameter consumed is usually missed, but it’s really important to application behaviour. Let’s go through each one in turn.

a. Source

JavaFX assigns a node as the source of an event at creation, which is defined according to the cause of the event (mouse, key, action etc).

b. Target

JavaFX assigns a node as the target of an event at creation. This is the node that has been acted upon by the event. All events throughout the lifecycle of the Event are delivered to the same Target node.

Target – detail

JavaFX extends the EventObject included in java.util to add additional parameters. The first of these is the target, which defines the node on which the event acted. For example, as I type in a TextField, every keystroke is registered as a KeyEvent and the target for each of these events will be the TextField.

Extending the EventObject gives JavaFX the flexibility to store and specify the event target in a JavaFX-specific way. In this case, the target of any event in JavaFX must implement the EventType interface. This interface includes a single method that takes an EventDispatchChain as a parameter, and returns an EventDispatchChain.

EventDispatchChain buildEventDispatchChain(EventDispatchChain tail);

That’s at the centre of how JavaFX handles firing events. A huge number of JavaFX objects extend the EventTarget interface:

• Nodes, Panes and Controls
• Transforms
• Charts
• Lights and Cameras
• Mesh data
• Shapes
• Skins

This allows JavaFX to fire events on any element of the user interface, but it also allows us as developers to fire these events too.

Because of how events are managed by JavaFX, it also ensures that the executable code we provide is dispatched on the Application thread. This is an incredibly stable way to update complex elements like charts, and visually-complicated controls.

c. Type

JavaFX assigns the event type based on the origin of the event (mouse, key, action etc.) and the nature of the state change (key released, mouse clicked, task started and so on).

d. consumed

At any point in this process, including before an event has reached its target, the event can be consumed and the process immediately stops.

I can’t understate how useful this is in controlling events throughout a scene and how often you’ll use it in event-driven development.

Event Firing – Phases

Whenever an event fires in JavaFX, it travels from the scene to the node and then from the node back up to the scene. This requires three things:

1. Knowing which node the event should travel to
2. Identifying which Window, in multi-window applications, and
3. Knowing the route to take between the scene and the node

These are the first steps in firing an event. Step 1 is called Target Selection. Steps 2 and 3 are taken together in a process called Route Construction.

We’ll go through each of these and then finish by going through how events are fired.

a. Target Selection

JavaFX selects the target of an event based on the type of event that has occurred and the input device that has created the event.

Because target selection is type-dependent, I’ve taken a more detailed look at target selection for each event type in the drop downs below.

b. Route Construction

In the case of foreground events – events where the target is a node within the scene – the target node creates a route between itself and the Window.

The logic goes something like this:

Get all the nodes between here and the Scene:

1. Add target node to the route as the end (tail).
2. If I target has a parent, append the parent node to the route
3. Continue adding parents until I find a node that doesn’t have a parent
4. This is the root node.
5. Use the root node to get the Scene.

Then, get the extra dispatch chain for the scene and window:

1. For the Scene just identified, add itself to the event dispatch chain (route)
2. Use the Scene to get the Window
3. Add the wind;es EventDispatcher as the very last link in the event dispatch chain.

After this, we return the route created from the initial call of buildEventDispatchChain() on the Target node.

For background events, the dispatch chain building process is much shorter. The EventHelper class contains a dispatch chain intended for Tasks and Services. The event is just added to the Helper event dispatcher and returned.

After route construction, events are ready to be dispatched from every link in the dispatch chain.

c. Event Capturing

Now we have a dispatch chain, the event starts at the first element of the chain and is forwarded, one-by-one, through every node’s EventDispatcher until the target node is reached.

This is where the difference between event filters and event handlers is important. If you haven’t heard of event filters, they can be added to any EventTarget (nodes, scene, charts, tasks and so on) using the addEventFilter() method.

Event filters are great for controlling the behaviour of child nodes, because they are executed by parents before children as the event traverses the scene graph.

Note: A node needs to have an event filter of the correct type for that filter to fire.

Event filters can be added to any EventTarget (nodes, tasks and services) by invoking addEventFilter() with the right EventType and EventHandler.

(check out How to define executable code in an EventHandler below)

Once the EventDispatcher on the target node has fired any relevant filters, it fires any relevant handlers and passes the event back up the chain in a process known as event bubbling.

d. Event Bubbling

Events registered with targets are executed in ascending order from the event target, to the Window.

Note: A node needs to have an event handler of the correct type for that handler to fire.

Event handlers can be added in the same way as event filters, but by using invoking addEventHandler() method on the target.

Let’s see how to define event filters and event handlers.

2. How to define executable code in an EventHandler

Whenever you want to define a response to an event, we need to use an EventHandler object. In spite of its name, we use the same object for both event filters and event handlers.

Creating an EventHandler:

We can do this by defining the EventHandler as an anonymous inner class, or as a lambda expression.

Defining an EventHandler

The EventHandler object is an object with a single method, which we need to override when we instantiate it. As the EventHandler interface is parameterized, we need to specify what event type we’re handling. In this case we’ll use a MouseEvent.

EventHandler<MouseEvent> eventHandler = new EventHandler<>() {
    @Override
    public void handle(MouseEvent event) {
        //executable code
    }
};

Replacing the definition with a lambda

An EventHandler is a functional interface (an interface with a single method). For convenience, the handle() method of the EventHandler interface can be specified with a lambda instead.

EventHandler<MouseEvent> eventHandler = event -> {
    //executable code
};

Adding and removing event filters and handlers

When we define and add an event handler to a node (or task), we define what type of that event we want our code to trigger from. As an example, if we want our code to trigger from any mouse event on the root node of our scene, we can use the event type MouseEvent.ANY.

If you want to remove an event handler at a later point in code, you will need to keep a reference to the EventHandler object you create.

//define the handler
EventHandler<MouseEvent> eventHandler = event -> {
    //executable code
};
//add the handler
rootNode.addEventHandler(
        MouseEvent.ANY, //specify the type of event to listen for
        eventHandler);
//later remove the handler
rootNode.removeEventHandler(
        MouseEvent.ANY, //this should be the same as defined above
        eventHandler
);

It’s equally easy to define and remove event filters using the addEventFilter() and removeEventFilter() methods.

A few simple things to remember though:

Using convenience methods

Sometimes it’s expedient to use convenience methods like setOnMousePressed() to define event handlers. The syntax for event handlers is:

setOn EventType ()

Here are a few examples:

Convenience methods are useful because you can remove the handler without having to remember the reference by invoking the same method and passing a null reference:

setOnMousePressed(null)

They are also guaranteed to execute after any other event handlers of the same type on that node.

3. Event Types

In general, events can be categories into input events, and events specific to JavaFX. ActionEvents require input, but also span input types, and are created internally by JavaFX, so I’ve included these in JavaFX-specific events, rather than input ones.

Operating System-Generated (Input) Events

Input events, such as mouse, keyboard and gesture events, happen above the level of the application, and are passed to our app by the operating system. The JavaFX background processes use this information to identify the right node to enact the event on.

This integration with the operating system is actually really handy. If the user tries to click, and wobbles the mouse a little bit – but inside a system-defined safe-area called the “hysteresis position” – the event doesn’t count as a drag.

For each event, I’ve set out the operating-system parameters your don’t need to worry about (or can’t control) as well the types of event in each case, how to use them, and any quirks of behaviour it’s useful to be aware of.

a. Key Events

Key events are generated by the operating system whenever a key changes state – that is, it’s pressed or released. If a key remains pressed for a long time, the OS will initiate additional key events.

textField.setOnKeyPressed(event -> {
    //executable code inside lambda expression
});

textField.addEventHandler(KeyEvent.KEY_PRESSED, event -> {
    //executable code inside lambda expression
});

a. Mouse Events

The MouseEvent class defines any change in the mouse cursor position or button states. As with key events, they are provided by the operating systemto the application, alongside the default mouse behaviour expectations that have been set by the user.

Mouse Events – details

Operating System Settings

The following operating system settings are already provided, and do not need to be set inside JavaFX:

• The delay between clicks required to distinguish multi-click events like the double click.
• The amount the mouse (or trackpad) position is allowed to move before it counts as dragging
• Which mouse button (left or right) is set as the primary mouse button.

Unlike with key events, which are automatically assigned to the focused node, the formal ‘target selection’ process for mouse events involves determining which nodes are underneath the mouse cursor.

Target Selection

In the case of mouse events, the uppermost node underneath the pixel the mouse is currently over is selected as the target regardless of where the scene is focused.

Mouse Event Types

There are 10 supported mouse events in JavaFX, alongside the standard ANY type.

• MOUSE_PRESSED
• MOUSE_RELEASED
• MOUSE_CLICKED
• MOUSE_ENTERED_TARGET
• MOUSE_ENTERED
• MOUSE_EXITED_TARGET
• MOUSE_EXITED
• MOUSE_MOVED
• MOUSE_DRAGGED
• DRAG_DETECTED

Behaviour

Every node between the node and the scene will execute the event as if the mouse has clicked every pane beneath the node. However, this isn’t specific to mouse events, it’s just the standard way JavaFX handles events.

If a node is displaying outside the layout bounds of its parent, the mouse events will still traverse the scene graph through the parent rather than the obscured node underneath the mouse cursor.

Mouse events can be generated during touch events. To identify whether a mouse event was generated from a touch event, invoke isSynthesized() on any MouseEvent. For more info, see touch events.

a. Touch Events

JavaFX provides support for touch-sensitive screens on laptops, tablets and mobile devices, and can also generate mouse events in JavaFX.

private boolean countingLongPress = false;
private boolean preventLongPressMechanic = false;
private long touchStarted;
private long touchLength;
private long LONG_PRESS_WAIT_TIME = 500000000; // 1 second = 1e9 nanoseconds
public void addTouchListeners(Scene scene) {
    scene.addEventFilter(TouchEvent.TOUCH_PRESSED, event -> {
        if(event.getTouchCount() != 1) preventLongPressMechanic = true;
        if(!preventLongPressMechanic){
            countingLongPress = true;
            touchStarted = System.nanoTime();
        }
    });
    scene.addEventFilter(TouchEvent.TOUCH_MOVED, event -> {
        touchLength = 0;
        countingLongPress = false;
        preventLongPressMechanic = true; //prevent additional actions until new event
    });
    scene.addEventFilter(TouchEvent.TOUCH_STATIONARY, event -> {
        if(countingLongPress){
            long currentTime = System.nanoTime();
            touchLength = System.nanoTime() - touchStarted;
        }
        if(touchLength > LONG_PRESS_WAIT_TIME){
            //execute long-press code by adding here
            touchLength = 0;
            countingLongPress = false;
            preventLongPressMechanic = true; //prevent additional actions until new event
        }
    });
    scene.addEventFilter(TouchEvent.TOUCH_RELEASED, event -> {
        if(event.getTouchCount() == 1){ //last point being released
            countingLongPress = false;
            preventLongPressMechanic = false;
        }
    });
}

a. Gesture Events

Gestures are part of JavaFX’s in-built support for touch-sensitive devices. There are four types of gesture: rotate, swipe, scroll and zoom.

scene.addEventFilter(RotateEvent.ROTATE, event -> {
    System.out.println("Rotated");
});

switch(event.getTextDeltaYUnits()) {
    case LINES:
        // scroll about event.getTextDeltaY() lines
        break;
    case PAGES:
        // scroll about event.getTextDeltaY() pages
        break;
    case NONE:
        // scroll about event.getDeltaY() pixels
        break;
}

JavaFX-originated Events

JavaFX also has the ability to create and dispatch its own events. There are three types of these events:

Each of these gives JavaFX the ability to layer functionality over the user interface.

a. Action Events

Action events are designed to span multiple input types, defining a single piece of executable code to use int he case of a specific user action. Controls such as the TextField and buttons have action events.

textField.setOnAction(event -> {
    //eevnt action defined with lambda
});

<TextField onAction="#handleTextCommit" fx:id="textField"/>

b. Worker State Events

Long-running tasks can easily be outsourced to workers such as Tasks or Services. It’s can be useful to fire events as these progress.

task.setOnRunning(event -> {
    //executable code
});

c. Edit, Modification and Sorting Events

These events span a number of uses, but they’re all responsible for updating complex UI elements that can’t be achieved through property binding.

Conclusions

Events are one of the most important parts of JavaFX. Almost all of executable code you need to update a user interface can be accomplished with events and property binding.

Events mediate the vast majority of interactions with the user. For anything more complex than binding the text content of a TextField to a FilteredList, events should be used to drive UI updates based on user interaction.

Even when a user’s typing, I use events preferentially over change listeners, because events are more stable, and you’re less likely to get multiple change events triggering for a single key stroke.

Finally, events are also good for mediating between complex background tasks and the user interface. The best way to get around a hanging UI is to use tasks, and to attach an event to the completion of that task.