/*
* Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*/
package javafx.event;
// PENDING_DOC_REVIEW
/**
* Represents a chain of {@code EventDispatcher} objects, which can dispatch
* an {@code Event}. The event is dispatched by passing it from one
* {@code EventDispatcher} to the next in the chain until the end of chain is
* reached. Each {@code 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 {@code EventDispatcher} objects encountered to the chain.
* @since JavaFX 2.0
*/
public interface
EventDispatchChain {
/**
* Appends the specified {@code EventDispatcher} to this chain. Returns a
* reference to the chain with the appended element.
* <p>
* The caller shouldn't assume that this {@code EventDispatchChain} remains
* unchanged nor that the returned value will reference a different chain
* after the call. All this depends on the {@code EventDispatchChain}
* implementation.
* <p>
* So the call should be always done in the following form:
* {@code chain = chain.append(eventDispatcher);}
*
* @param eventDispatcher the {@code EventDispatcher} to append to the
* chain
* @return the chain with the appended event dispatcher
*/
EventDispatchChain append(
EventDispatcher eventDispatcher);
/**
* Prepends the specified {@code EventDispatcher} to this chain. Returns a
* reference to the chain with the prepended element.
* <p>
* The caller shouldn't assume that this {@code EventDispatchChain} remains
* unchanged nor that the returned value will reference a different chain
* after the call. All this depends on the {@code EventDispatchChain}
* implementation.
* <p>
* So the call should be always done in the following form:
* {@code chain = chain.prepend(eventDispatcher);}
*
* @param eventDispatcher the {@code EventDispatcher} to prepend to the
* chain
* @return the chain with the prepended event dispatcher
*/
EventDispatchChain prepend(
EventDispatcher eventDispatcher);
/**
* Dispatches the specified event through this {@code 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 {@code null} and no further processing should be done with that
* event.
*
* @param event the event to dispatch
* @return the processed event or {@code null} if the event had been fully
* handled / consumed
*/
Event dispatchEvent(
Event event);
}