Interface EventDispatcher

public interface EventDispatcher

An EventDispatcher represents an event dispatching and processing entity. It is used when an Event needs to be dispatched to the associated EventTarget through the EventDispatchChain specified by the target. Each EventDispatcher in the chain can influence the event path and the event itself. One EventDispatcher can appear in multiple chains.

The system defines two successive phases of event delivery. The first phase is called capturing phase and happens when when an event travels from the first element of the EventDispatchChain associated with the event target to its last element. If the event target is part of some hierarchy, the direction of the event in this phase usually corresponds with the direction from the root element of the hierarchy to the target. The second phase is called bubbling phase and happens in the reverse order to the first phase. So the event is returning back from the last element of the EventDispatchChain to its first element in this phase. Usually that corresponds to the direction from the event target back to the root in the event target's hierarchy.

Each EventDispatcher in an EventDispatchChain is responsible for forwarding the event to the rest of the chain during event dispatching. This forwarding happens in the dispatchEvent method and forms a chain of nested calls which allows one EventDispatcher to see the event during both dispatching phases in a single dispatchEvent call.

Template for dispatchEvent implementation.

public Event dispatchEvent(Event event, EventDispatchChain tail) {
    // capturing phase, can handle / modify / substitute / divert the event

    if (notHandledYet) {
        // forward the event to the rest of the chain
        event = tail.dispatchEvent(event);

        if (event != null) {
            // bubbling phase, can handle / modify / substitute / divert
            // the event
        }
    }

    return notHandledYet ? event : null;

}