Module javafx.base
Package javafx.event

# Interface EventDispatchChain

public interface EventDispatchChain
Represents a chain of `EventDispatcher` objects, which can dispatch an `Event`. The event is dispatched by passing it from one `EventDispatcher` to the next in the chain until the end of chain is reached. Each `EventDispatcher` in the chain can influence the event path and the event itself. The chain is usually formed by following some parent - child hierarchy from the root to the event target and appending all `EventDispatcher` objects encountered to the chain.

Since:
  JavaFX 2.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `EventDispatchChain`
  `append(EventDispatcher eventDispatcher)`
  Appends the specified `EventDispatcher` to this chain.
  `Event`
  `dispatchEvent(Event event)`
  Dispatches the specified event through this `EventDispatchChain`.
  `EventDispatchChain`
  `prepend(EventDispatcher eventDispatcher)`
  Prepends the specified `EventDispatcher` to this chain.

- ## Method Details

  - ### append

    EventDispatchChain append(EventDispatcher eventDispatcher)
    Appends the specified `EventDispatcher` to this chain. Returns a reference to the chain with the appended element.

    The caller shouldn't assume that this `EventDispatchChain` remains unchanged nor that the returned value will reference a different chain after the call. All this depends on the `EventDispatchChain` implementation.

    So the call should be always done in the following form: `chain = chain.append(eventDispatcher);`

    Parameters:
      `eventDispatcher` - the `EventDispatcher` to append to the chain
    Returns:
      the chain with the appended event dispatcher

  - ### prepend

    EventDispatchChain prepend(EventDispatcher eventDispatcher)
    Prepends the specified `EventDispatcher` to this chain. Returns a reference to the chain with the prepended element.

    The caller shouldn't assume that this `EventDispatchChain` remains unchanged nor that the returned value will reference a different chain after the call. All this depends on the `EventDispatchChain` implementation.

    So the call should be always done in the following form: `chain = chain.prepend(eventDispatcher);`

    Parameters:
      `eventDispatcher` - the `EventDispatcher` to prepend to the chain
    Returns:
      the chain with the prepended event dispatcher

  - ### dispatchEvent

    Event dispatchEvent(Event event)
    Dispatches the specified event through this `EventDispatchChain`. The return value represents the event after processing done by the chain. If further processing is to be done after the call the event referenced by the return value should be used instead of the original event. In the case the event is fully handled / consumed in the chain the returned value is `null` and no further processing should be done with that event.
    Parameters:
      `event` - the event to dispatch
    Returns:
      the processed event or `null` if the event had been fully handled / consumed