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}