event dispatch chain

Figure 1-3 Event Dispatch Chain

Description of "Figure 1-3 Event Dispatch Chain"

The route can be modified as event filters and event handlers along the route process the event. Also, if an event filter or event handler consumes the event at any point, some nodes on the initial route might not receive the event.

Event Capturing Phase

In the event capturing phase, the event is dispatched by the root node of your application and passed down the event dispatch chain to the target node. Using the event dispatch chain shown in Figure 1-3, the event travels from the Stage node to the Triangle node during the event capturing phase.

If any node in the chain has an event filter registered for the type of event that occurred, that filter is called. When the filter completes, the event is passed to the next node down the chain. If a filter is not registered for a node, the event is passed to the next node down the chain. If no filter consumes the event, the event target eventually receives and processes the event.

Event Bubbling Phase

After the event target is reached and all registered filters have processed the event, the event returns along the dispatch chain from the target to the root node. Using the event dispatch chain shown in Figure 1-3, the event travels from the Triangle node to the Stage node during the event bubbling phase.

If any node in the chain has a handler registered for the type of event encountered, that handler is called. When the handler completes, the event is returned to the next node up the chain. If a handler is not registered for a node, the event is returned to the next node up the chain. If no handler consumes the event, the root node eventually receives the event and processing is completed.

Event Handling

Event handling is provided by event filters and event handlers, which are implementations of the EventHandler interface. If you want an application to be notified when an event occurs, register a filter or a handler for the event. The primary difference between a filter and a handler is when each one is executed.

Event Filters

An event filter is executed during the event capturing phase. An event filter for a parent node can provide common event processing for multiple child nodes and if desired, consume the event to prevent the child node from receiving the event. Filters that are registered for the type of event that occurred are executed as the event passes through the node that registered the filter.

A node can register more than one filter. The order in which each filter is called is based on the hierarchy of event types. Filters for a specific event type are executed before filters for generic event types. For example, a filter for the MouseEvent.MOUSE_PRESSED event is called before the filter for the InputEvent.ANY event. The order in which two filters at the same level are executed is not specified.

Event Handlers

An event handler is executed during the event bubbling phase. If an event handler for a child node does not consume the event, an event handler for a parent node can act on the event after a child node processes it and can provide common event processing for multiple child nodes. Handlers that are registered for the type of event that occurred are executed as the event returns through the node that registered the handler.

A node can register more than one handler. The order in which each handler is called is based on the hierarchy of event types. Handlers for a specific event type are executed before handlers for generic event types. For example, a handler for the KeyEvent.KEY_TYPED event is called before the handler for the InputEvent.ANY event. The order in which two handlers at the same level are executed is not specified, with the exception that handlers that are registered by the convenience methods described in Working with Convenience Methods are executed last.

Consuming of an Event

An event can be consumed by an event filter or an event handler at any point in the event dispatch chain by calling the consume() method. This method signals that processing of the event is complete and traversal of the event dispatch chain ends.

Consuming the event in an event filter prevents any child node on the event dispatch chain from acting on the event. Consuming the event in an event handler stops any further processing of the event by parent handlers on the event dispatch chain. However, if the node that consumes the event has more than one filter or handler registered for the event, the peer filters or handlers are still executed.

For example, using the event dispatch chain shown in Figure 1-3, assume that the Pane node has an event filter registered for the KeyEvent.KEY_PRESSED event and an event filter registered for the InputEvent.ANY event. If the filter for the key pressed event consumes the event, the filter for the input event is executed and the Triangle node does not receive the event.

Note that the default handlers for the JavaFX UI controls typically consume most of the input events.