Исходный код

001/*
002 * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation.  Oracle designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Oracle in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
022 * or visit www.oracle.com if you need additional information or have any
023 * questions.
024 */
025
026package javafx.event;
027
028// PENDING_DOC_REVIEW
029/**
030 * Represents a chain of {@code EventDispatcher} objects, which can dispatch
031 * an {@code Event}. The event is dispatched by passing it from one
032 * {@code EventDispatcher} to the next in the chain until the end of chain is
033 * reached. Each {@code EventDispatcher} in the chain can influence the event
034 * path and the event itself. The chain is usually formed by following some
035 * parent - child hierarchy from the root to the event target and appending
036 * all {@code EventDispatcher} objects encountered to the chain.
037 */
038public interface EventDispatchChain {
039    /**
040     * Appends the specified {@code EventDispatcher} to this chain. Returns a
041     * reference to the chain with the appended element. 
042     * <p>
043     * The caller shouldn't assume that this {@code EventDispatchChain} remains
044     * unchanged nor that the returned value will reference a different chain
045     * after the call. All this depends on the {@code EventDispatchChain}
046     * implementation.
047     * <p>
048     * So the call should be always done in the following form:
049     * {@code chain = chain.append(eventDispatcher);}
050     *
051     * @param eventDispatcher the {@code EventDispatcher} to append to the
052     *      chain
053     * @return the chain with the appended event dispatcher
054     */
055    EventDispatchChain append(EventDispatcher eventDispatcher);
056
057    /**
058     * Prepends the specified {@code EventDispatcher} to this chain. Returns a
059     * reference to the chain with the prepended element.
060     * <p>
061     * The caller shouldn't assume that this {@code EventDispatchChain} remains
062     * unchanged nor that the returned value will reference a different chain
063     * after the call. All this depends on the {@code EventDispatchChain}
064     * implementation.
065     * <p>
066     * So the call should be always done in the following form:
067     * {@code chain = chain.prepend(eventDispatcher);}
068     *
069     * @param eventDispatcher the {@code EventDispatcher} to prepend to the
070     *      chain
071     * @return the chain with the prepended event dispatcher
072     */
073    EventDispatchChain prepend(EventDispatcher eventDispatcher);
074
075    /**
076     * Dispatches the specified event through this {@code EventDispatchChain}.
077     * The return value represents the event after processing done by the chain.
078     * If further processing is to be done after the call the event referenced
079     * by the return value should be used instead of the original event. In the
080     * case the event is fully handled / consumed in the chain the returned
081     * value is {@code null} and no further processing should be done with that
082     * event.
083     *
084     * @param event the event to dispatch
085     * @return the processed event or {@code null} if the event had been fully
086     *      handled / consumed
087     */
088    Event dispatchEvent(Event event);
089}