553N/A * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 0N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 0N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 553N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 553N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A * or visit www.oracle.com if you need additional information or have any 0N/A * The <code>DragGestureRecognizer</code> is an 0N/A * abstract base class for the specification * of a platform-dependent listener that can be associated with a particular * <code>Component</code> in order to * identify platform-dependent drag initiating gestures. * The appropriate <code>DragGestureRecognizer</code> * subclass instance is obtained from the * {@link DragSource} asssociated with * a particular <code>Component</code>, or from the <code>Toolkit</code> object via its * {@link java.awt.Toolkit#createDragGestureRecognizer createDragGestureRecognizer()} * Once the <code>DragGestureRecognizer</code> * is associated with a particular <code>Component</code> * it will register the appropriate listener interfaces on that * in order to track the input events delivered to the <code>Component</code>. * Once the <code>DragGestureRecognizer</code> identifies a sequence of events * on the <code>Component</code> as a drag initiating gesture, it will notify * its unicast <code>DragGestureListener</code> by * {@link java.awt.dnd.DragGestureListener#dragGestureRecognized gestureRecognized()} * When a concrete <code>DragGestureRecognizer</code> * instance detects a drag initiating * gesture on the <code>Component</code> it is associated with, * it fires a {@link DragGestureEvent} to * the <code>DragGestureListener</code> registered on * its unicast event source for <code>DragGestureListener</code> * events. This <code>DragGestureListener</code> is responsible * for causing the associated * <code>DragSource</code> to start the Drag and Drop operation (if * @author Laurence P. G. Cable * @see java.awt.dnd.DragGestureListener * @see java.awt.dnd.DragGestureEvent * @see java.awt.dnd.DragSource * Construct a new <code>DragGestureRecognizer</code> * given the <code>DragSource</code> to be used * in this Drag and Drop operation, the <code>Component</code> * this <code>DragGestureRecognizer</code> should "observe" * for drag initiating gestures, the action(s) supported * for this Drag and Drop operation, and the * <code>DragGestureListener</code> to notify * once a drag initiating gesture has been detected. * @param ds the <code>DragSource</code> this * <code>DragGestureRecognizer</code> * will use to process the Drag and Drop operation * @param c the <code>Component</code> * this <code>DragGestureRecognizer</code> * should "observe" the event stream to, * in order to detect a drag initiating gesture. * If this value is <code>null</code>, the * <code>DragGestureRecognizer</code> * is not associated with any <code>Component</code>. * @param sa the set (logical OR) of the * <code>DnDConstants</code> * that this Drag and Drop operation will support * @param dgl the <code>DragGestureRecognizer</code> * to notify when a drag gesture is detected * @throws <code>IllegalArgumentException</code> * if ds is <code>null</code>. * Construct a new <code>DragGestureRecognizer</code> * given the <code>DragSource</code> to be used in this * operation, the <code>Component</code> this * <code>DragGestureRecognizer</code> should "observe" * for drag initiating gestures, and the action(s) * supported for this Drag and Drop operation. * @param ds the <code>DragSource</code> this * <code>DragGestureRecognizer</code> will use to * process the Drag and Drop operation * @param c the <code>Component</code> this * <code>DragGestureRecognizer</code> should "observe" the event * stream to, in order to detect a drag initiating gesture. * If this value is <code>null</code>, the * <code>DragGestureRecognizer</code> * is not associated with any <code>Component</code>. * @param sa the set (logical OR) of the <code>DnDConstants</code> * that this Drag and Drop operation will support * @throws <code>IllegalArgumentException</code> * if ds is <code>null</code>. * Construct a new <code>DragGestureRecognizer</code> * given the <code>DragSource</code> to be used * in this Drag and Drop operation, and * the <code>Component</code> this * <code>DragGestureRecognizer</code> * should "observe" for drag initiating gestures. * @param ds the <code>DragSource</code> this * <code>DragGestureRecognizer</code> * will use to process the Drag and Drop operation * @param c the <code>Component</code> * this <code>DragGestureRecognizer</code> * should "observe" the event stream to, * in order to detect a drag initiating gesture. * If this value is <code>null</code>, * the <code>DragGestureRecognizer</code> * is not associated with any <code>Component</code>. * @throws <code>IllegalArgumentException</code> * if ds is <code>null</code>. * Construct a new <code>DragGestureRecognizer</code> * given the <code>DragSource</code> to be used in this * Drag and Drop operation. * @param ds the <code>DragSource</code> this * <code>DragGestureRecognizer</code> will * use to process the Drag and Drop operation * @throws <code>IllegalArgumentException</code> * if ds is <code>null</code>. * register this DragGestureRecognizer's Listeners with the Component * subclasses must override this method * unregister this DragGestureRecognizer's Listeners with the Component * subclasses must override this method * This method returns the <code>DragSource</code> * this <code>DragGestureRecognizer</code> * will use in order to process the Drag and Drop * This method returns the <code>Component</code> * that is to be "observed" by the * <code>DragGestureRecognizer</code> * for drag initiating gestures. * @return The Component this DragGestureRecognizer * set the Component that the DragGestureRecognizer is associated with * registerListeners() and unregisterListeners() are called as a side * @param c The <code>Component</code> or <code>null</code> * This method returns an int representing the * type of action(s) this Drag and Drop * operation will support. * @return the currently permitted source action(s) * This method sets the permitted source drag action(s) * for this Drag and Drop operation. * @param actions the permitted source drag action(s) * This method returns the first event in the * series of events that initiated * the Drag and Drop operation. * @return the initial event that triggered the drag gesture * Reset the Recognizer, if its currently recognizing a gesture, ignore * Register a new <code>DragGestureListener</code>. * @param dgl the <code>DragGestureListener</code> to register * with this <code>DragGestureRecognizer</code>. * @throws java.util.TooManyListenersException if a * <code>DragGestureListener</code> has already been added. * unregister the current DragGestureListener * @param dgl the <code>DragGestureListener</code> to unregister * from this <code>DragGestureRecognizer</code> * @throws <code>IllegalArgumentException</code> if * dgl is not (equal to) the currently registered <code>DragGestureListener</code>. * Notify the DragGestureListener that a Drag and Drop initiating * gesture has occurred. Then reset the state of the Recognizer. * @param dragAction The action initially selected by the users gesture * @param p The point (in Component coords) where the gesture originated * Listeners registered on the Component by this Recognizer shall record * all Events that are recognized as part of the series of Events that go * to comprise a Drag and Drop initiating gesture via this API. * This method is used by a <code>DragGestureRecognizer</code> * implementation to add an <code>InputEvent</code> * subclass (that it believes is one in a series * of events that comprise a Drag and Drop operation) * to the array of events that this * <code>DragGestureRecognizer</code> maintains internally. * @param awtie the <code>InputEvent</code> * to add to this <code>DragGestureRecognizer</code>'s * internal array of events. Note that <code>null</code> * is not a valid value, and will be ignored. * Serializes this <code>DragGestureRecognizer</code>. This method first * performs default serialization. Then, this object's * <code>DragGestureListener</code> is written out if and only if it can be * serialized. If not, <code>null</code> is written instead. * @serialData The default serializable fields, in alphabetical order, * followed by either a <code>DragGestureListener</code>, or * Deserializes this <code>DragGestureRecognizer</code>. This method first * performs default deserialization for all non-<code>transient</code> * fields. This object's <code>DragGestureListener</code> is then * deserialized as well by using the next object in the stream. * The <code>DragSource</code> * <code>DragGestureRecognizer</code>. * The <code>Component</code> * associated with this <code>DragGestureRecognizer</code>. * The <code>DragGestureListener</code> * associated with this <code>DragGestureRecognizer</code>. * An <code>int</code> representing * the type(s) of action(s) used * in this Drag and Drop operation. * The list of events (in order) that * the <code>DragGestureRecognizer</code> * "recognized" as a "gesture" that triggers a drag.