Spec-Zone .ru
спецификации, руководства, описания, API
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
028import java.util.EventObject;
029
030import com.sun.javafx.event.EventUtil;
031import java.io.IOException;
032
033// PENDING_DOC_REVIEW
034/**
035 * Base class for FX events. Each FX event has associated an event source,
036 * event target and an event type. The event source specifies for an event
037 * handler the object on which that handler has been registered and which sent
038 * the event to it. The event target defines the path through which the event
039 * will travel when posted. The event type provides additional classification
040 * to events of the same {@code Event} class.
041 */
042public class Event extends EventObject implements Cloneable {
043
044    private static final long serialVersionUID = 20121107L;
045    /**
046     * The constant which represents an unknown event source / target.
047     */
048    public static final EventTarget NULL_SOURCE_TARGET = new EventTarget() {
049        @Override
050        public EventDispatchChain buildEventDispatchChain(
051                final EventDispatchChain tail) {
052            return tail;
053        }
054    };
055
056    /**
057     * Common supertype for all event types.
058     */
059    public static final EventType<Event> ANY = EventType.ROOT;
060
061    /**
062     * Type of the event.
063     */
064    protected EventType<? extends Event> eventType;
065
066    /**
067     * Event target that defines the path through which the event
068     * will travel when posted.
069     */
070    protected transient EventTarget target;
071
072    /**
073     * Whether this event has been consumed by any filter or handler.
074     */
075    protected boolean consumed;
076
077    /**
078     * Construct a new {@code Event} with the specified event type. The source
079     * and target of the event is set to {@code NULL_SOURCE_TARGET}.
080     *
081     * @param eventType the event type
082     */
083    public Event(final EventType<? extends Event> eventType) {
084        this(null, null, eventType);
085    }
086
087    /**
088     * Construct a new {@code Event} with the specified event source, target
089     * and type. If the source or target is set to {@code null}, it is replaced
090     * by the {@code NULL_SOURCE_TARGET} value.
091     *
092     * @param source the event source which sent the event
093     * @param target the event target to associate with the event
094     * @param eventType the event type
095     */
096    public Event(final Object source,
097                 final EventTarget target,
098                 final EventType<? extends Event> eventType) {
099        super((source != null) ? source : NULL_SOURCE_TARGET);
100        this.target = (target != null) ? target : NULL_SOURCE_TARGET;
101        this.eventType = eventType;
102    }
103
104    /**
105     * Returns the event target of this event. The event target specifies
106     * the path through which the event will travel when posted.
107     *
108     * @return the event target
109     */
110    public EventTarget getTarget() {
111        return target;
112    }
113
114    /**
115     * Gets the event type of this event. Objects of the same {@code Event}
116     * class can have different event types. These event types further specify
117     * what kind of event occurred.
118     *
119     * @return the event type
120     */
121    public EventType<? extends Event> getEventType() {
122        return eventType;
123    }
124
125    /**
126     * Creates and returns a copy of this event with the specified event source
127     * and target. If the source or target is set to {@code null}, it is
128     * replaced by the {@code NULL_SOURCE_TARGET} value.
129     *
130     * @param newSource the new source of the copied event
131     * @param newTarget the new target of the copied event
132     * @return the event copy with the new source and target
133     */
134    public Event copyFor(final Object newSource, final EventTarget newTarget) {
135        final Event newEvent = (Event) clone();
136
137        newEvent.source = (newSource != null) ? newSource : NULL_SOURCE_TARGET;
138        newEvent.target = (newTarget != null) ? newTarget : NULL_SOURCE_TARGET;
139        newEvent.consumed = false;
140
141        return newEvent;
142    }
143
144    /**
145     * Indicates whether this {@code Event} has been consumed by any filter or
146     * handler.
147     *
148     * @return {@code true} if this {@code Event} has been consumed,
149     *     {@code false} otherwise
150     */
151    public boolean isConsumed() {
152        return consumed;
153    }
154
155    /**
156     * Marks this {@code Event} as consumed. This stops its further propagation.
157     */
158    public void consume() {
159        consumed = true;
160    }
161
162    /**
163     * Creates and returns a copy of this {@code Event}.
164     * @return a new instance of {@code Event} with all values copied from 
165     * this {@code Event}.
166     */
167    @Override
168    public Object clone() {
169        try {
170            return super.clone();
171        } catch (final CloneNotSupportedException e) {
172            // we implement Cloneable, this shouldn't happen
173            throw new RuntimeException("Can't clone Event");
174        }
175    }
176
177    private void readObject(java.io.ObjectInputStream in) throws IOException, ClassNotFoundException {
178        in.defaultReadObject();
179        source = NULL_SOURCE_TARGET;
180        target = NULL_SOURCE_TARGET;
181    }
182
183
184    // PENDING_DOC_REVIEW
185    /**
186     * Fires the specified event. The given event target specifies the path
187     * through which the event will travel.
188     *
189     * @param eventTarget the target for the event
190     * @param event the event to fire
191     * @throws NullPointerException if eventTarget or event is null
192     */
193    public static void fireEvent(EventTarget eventTarget, Event event) {
194        if (eventTarget == null) {
195            throw new NullPointerException("Event target must not be null!");
196        }
197
198        if (event == null) {
199            throw new NullPointerException("Event must not be null!");
200        }
201
202        EventUtil.fireEvent(eventTarget, event);
203    }
204}