Source code

001/*
002 * Copyright (c) 2000, 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.scene.input;
027
028import javafx.event.EventTarget;
029import javafx.event.EventType;
030
031/**
032 * Mouse drag events are delivered to potential gesture targets during
033 * full press-drag-release gestures. The difference among different
034 * gesture types is described at {@link javafx.scene.input.MouseEvent MouseEvent}.
035 * <p>
036 * Full press-drag-release gesture can be started by calling
037 * {@code startFullDrag()} (on a node or scene) inside of a DRAG_DETECTED
038 * event handler. This call activates delivering of {@code MouseDragEvent}s
039 * to the nodes that are under cursor during the dragging gesture.
040 * <p>
041 * When you drag a node, it's still under cursor, so it is considered
042 * being a potential gesture target during the whole gesture. If you need to
043 * drag a node to a different node and let the other node know about it,
044 * you need to ensure that the nodes under the dragged node are picked
045 * as the potential gesture targets. You can achieve this by calling
046 * {@code setMouseTransparent(true)} on the dragged node in a
047 * {@code MOUSE_PRESSED} handler and returning it back to false in a
048 * {@code MOUSE_RELEASED} handler. This way the nodes under the dragged
049 * node will receive the {@code MouseDragEvent}s, while all the
050 * {@code MouseEvent}s will still be delivered to the (currently mouse
051 * transparent) gesture source.
052 * <p>
053 * The entered/exited events behave similarly to mouse entered/exited
054 * events, please see {@link MouseEvent} overview.
055 */
056public final class MouseDragEvent extends MouseEvent{
057
058    private static final long serialVersionUID = 20121107L;
059
060    /**
061     * Common supertype for all mouse event types.
062     */
063    public static final EventType<MouseDragEvent> ANY =
064            new EventType<MouseDragEvent>(MouseEvent.ANY, "MOUSE-DRAG");
065
066    /**
067     * This event occurs when the gesture progresses within this node.
068     */
069    public static final EventType<MouseDragEvent> MOUSE_DRAG_OVER =
070            new EventType<MouseDragEvent>(MouseDragEvent.ANY, "MOUSE-DRAG_OVER");
071
072    /**
073     * This event occurs when the gesture ends (by releasing mouse button)
074     * on this node.
075     */
076    public static final EventType<MouseDragEvent> MOUSE_DRAG_RELEASED =
077            new EventType<MouseDragEvent>(MouseDragEvent.ANY, "MOUSE-DRAG_RELEASED");
078
079    /**
080     * This event occurs when the gesture enters a node. It's the bubbling variant,
081     * which is delivered also to all parents of the entered node (unless it
082     * was consumed). When notifications about mouse entering some of node's
083     * children are not desired, {@code MOUSE_DRAG_ENTERED} event handler should
084     * be used.
085     *
086     * @see MouseEvent MouseEvent for more information about mouse entered/exited handling
087     * which is similar
088     */
089    public static final EventType<MouseDragEvent> MOUSE_DRAG_ENTERED_TARGET =
090            new EventType<MouseDragEvent>(MouseDragEvent.ANY, "MOUSE-DRAG_ENTERED_TARGET");
091
092    /**
093     * This event occurs when the gesture enters a node. This event type is
094     * delivered only to the entered node, if parents want to filter it or get
095     * the bubbling event, they need to use {@code MOUSE_DRAG_ENTERED_TARGET}.
096     *
097     * @see MouseEvent MouseEvent for more information about mouse entered/exited handling
098     * which is similar
099     */
100    public static final EventType<MouseDragEvent> MOUSE_DRAG_ENTERED =
101            new EventType<MouseDragEvent>(MouseDragEvent.MOUSE_DRAG_ENTERED_TARGET,
102                    "MOUSE-DRAG_ENTERED");
103
104    /**
105     * This event occurs when the gesture exits a node. It's the bubbling variant,
106     * which is delivered also to all parents of the exited node (unless it
107     * was consumed). When notifications about mouse exiting some of node's
108     * children are not desired, {@code MOUSE_DRAG_EXITED} event handler should
109     * be used.
110     *
111     * @see MouseEvent MouseEvent for more information about mouse entered/exited handling
112     * which is similar
113     */
114    public static final EventType<MouseDragEvent> MOUSE_DRAG_EXITED_TARGET =
115            new EventType<MouseDragEvent>(MouseDragEvent.ANY, "MOUSE-DRAG_EXITED_TARGET");
116
117    /**
118     * This event occurs when the gesture exits a node. This event type is
119     * delivered only to the exited node, if parents want to filter it or get
120     * the bubbling event, they need to use {@code MOUSE_DRAG_EXITED_TARGET}.
121     *
122     * @see MouseEvent MouseEvent for more information about mouse entered/exited handling
123     * which is similar
124     */
125    public static final EventType<MouseDragEvent> MOUSE_DRAG_EXITED =
126            new EventType<MouseDragEvent>(MouseDragEvent.MOUSE_DRAG_EXITED_TARGET,
127                    "MOUSE-DRAG_EXITED");
128
129    /**
130     * Constructs new MouseDragEvent event.
131     * @param source the source of the event. Can be null.
132     * @param target the target of the event. Can be null.
133     * @param eventType The type of the event.
134     * @param x The x with respect to the scene.
135     * @param y The y with respect to the scene.
136     * @param screenX The x coordinate relative to screen.
137     * @param screenY The y coordinate relative to screen.
138     * @param button the mouse button used
139     * @param clickCount number of click counts
140     * @param shiftDown true if shift modifier was pressed.
141     * @param controlDown true if control modifier was pressed.
142     * @param altDown true if alt modifier was pressed.
143     * @param metaDown true if meta modifier was pressed.
144     * @param primaryButtonDown true if primary button was pressed.
145     * @param middleButtonDown true if middle button was pressed.
146     * @param secondaryButtonDown true if secondary button was pressed.
147     * @param synthesized if this event was synthesized
148     * @param popupTrigger whether this event denotes a popup trigger for current platform
149     * @param pickResult pick result. Can be null, in this case a 2D pick result
150     *                   without any further values is constructed
151     *                   based on the scene coordinates and target
152     * @param gestureSource source object of the ongoing gesture.
153     */
154    public MouseDragEvent(Object source, EventTarget target, EventType<MouseDragEvent> eventType,
155            double x, double y, double screenX, double screenY,
156            MouseButton button, int clickCount,
157            boolean shiftDown, boolean controlDown, boolean altDown, boolean metaDown,
158            boolean primaryButtonDown, boolean middleButtonDown, boolean secondaryButtonDown,
159            boolean synthesized, boolean popupTrigger, PickResult pickResult,
160            Object gestureSource) {
161        super(source, target, eventType, x, y, screenX, screenY, button,
162                clickCount, shiftDown, controlDown, altDown, metaDown,
163                primaryButtonDown, middleButtonDown, secondaryButtonDown,
164                synthesized, popupTrigger, false, pickResult);
165        this.gestureSource = gestureSource;
166    }
167
168    /**
169     * Constructs new MouseDragEvent event with null source and target.
170     *
171     * @param eventType The type of the event.
172     * @param x The x with respect to the scene.
173     * @param y The y with respect to the scene.
174     * @param screenX The x coordinate relative to screen.
175     * @param screenY The y coordinate relative to screen.
176     * @param button the mouse button used
177     * @param clickCount number of click counts
178     * @param shiftDown true if shift modifier was pressed.
179     * @param controlDown true if control modifier was pressed.
180     * @param altDown true if alt modifier was pressed.
181     * @param metaDown true if meta modifier was pressed.
182     * @param primaryButtonDown true if primary button was pressed.
183     * @param middleButtonDown true if middle button was pressed.
184     * @param secondaryButtonDown true if secondary button was pressed.
185     * @param synthesized if this event was synthesized
186     * @param popupTrigger whether this event denotes a popup trigger for current platform
187     * @param pickResult pick result. Can be null, in this case a 2D pick result
188     *                   without any further values is constructed
189     *                   based on the scene coordinates
190     * @param gestureSource source object of the ongoing gesture.
191     */
192    public MouseDragEvent(EventType<MouseDragEvent> eventType,
193            double x, double y, double screenX, double screenY,
194            MouseButton button, int clickCount,
195            boolean shiftDown, boolean controlDown, boolean altDown, boolean metaDown,
196            boolean primaryButtonDown, boolean middleButtonDown, boolean secondaryButtonDown,
197            boolean synthesized, boolean popupTrigger, PickResult pickResult,
198            Object gestureSource) {
199        this(null, null, eventType, x, y, screenX, screenY, button, clickCount,
200                shiftDown, controlDown, altDown, metaDown, primaryButtonDown,
201                middleButtonDown, secondaryButtonDown, synthesized, popupTrigger, 
202                pickResult, gestureSource);
203     }
204
205   
206    private final transient Object gestureSource;
207
208    /**
209     * Returns the source object of the ongoing gesture.
210     * Gesture source is the object that started the full press-drag-release
211     * gesture (by {@code startFullDrag} method being called on it).
212     * @return The source object of the gesture.
213     */
214    public Object getGestureSource() {
215        return gestureSource;
216    }
217
218    /**
219     * Returns a string representation of this {@code MouseDragEvent} object.
220     * @return a string representation of this {@code MouseDragEvent} object.
221     */
222    @Override public String toString() {
223        final StringBuilder sb = new StringBuilder("MouseDragEvent [");
224
225        sb.append("source = ").append(getSource());
226        sb.append(", target = ").append(getTarget());
227        sb.append(", gestureSource = ").append(getGestureSource());
228        sb.append(", eventType = ").append(getEventType());
229        sb.append(", consumed = ").append(isConsumed());
230
231        sb.append(", x = ").append(getX()).append(", y = ").append(getY())
232                .append(", z = ").append(getZ());
233
234        if (getButton() != null) {
235            sb.append(", button = ").append(getButton());
236        }
237        if (getClickCount() > 1) {
238            sb.append(", clickCount = ").append(getClickCount());
239        }
240        if (isPrimaryButtonDown()) {
241            sb.append(", primaryButtonDown");
242        }
243        if (isMiddleButtonDown()) {
244            sb.append(", middleButtonDown");
245        }
246        if (isSecondaryButtonDown()) {
247            sb.append(", secondaryButtonDown");
248        }
249        if (isShiftDown()) {
250            sb.append(", shiftDown");
251        }
252        if (isControlDown()) {
253            sb.append(", controlDown");
254        }
255        if (isAltDown()) {
256            sb.append(", altDown");
257        }
258        if (isMetaDown()) {
259            sb.append(", metaDown");
260        }
261        if (isShortcutDown()) {
262            sb.append(", shortcutDown");
263        }
264        if (isSynthesized()) {
265            sb.append(", synthesized");
266        }
267        sb.append(", pickResult = ").append(getPickResult());
268
269        return sb.append("]").toString();
270    }
271
272    @Override
273    public MouseDragEvent copyFor(Object newSource, EventTarget newTarget) {
274        return (MouseDragEvent) super.copyFor(newSource, newTarget);
275    }
276
277    @Override
278    public MouseDragEvent copyFor(Object newSource, EventTarget newTarget, EventType<? extends MouseEvent> type) {
279        return (MouseDragEvent) super.copyFor(newSource, newTarget, type);
280    }
281
282    @Override
283    public EventType<MouseDragEvent> getEventType() {
284        return (EventType<MouseDragEvent>) super.getEventType();
285    }
286}