java.awt.dnd
Class DragGestureRecognizer

java.lang.Object
  extended byjava.awt.dnd.DragGestureRecognizer
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
MouseDragGestureRecognizer, TransferHandler.SwingDragGestureRecognizer

public abstract class DragGestureRecognizer
extends Object
implements Serializable

The DragGestureRecognizer is an abstract base class for the specification of a platform-dependent listener that can be associated with a particular Component in order to identify platform-dependent drag initiating gestures.

The appropriate DragGestureRecognizer subclass is obtained from the DragSource asssociated with a particular Component, or from the Toolkit object via its createDragGestureRecognizer() method.

Once the DragGestureRecognizer is associated with a particular Component it will register the appropriate listener interfaces on that Component in order to track the input events delivered to the Component.

Once the DragGestureRecognizer identifies a sequence of events on the Component as a drag initiating gesture, it will notify its unicast DragGestureListener by invoking its gestureRecognized() method.

When a concrete DragGestureRecognizer instance detects a drag initiating gesture on the Component it is associated with, it will fire a DragGestureEvent to the DragGestureListener registered on its unicast event source for DragGestureListener events. This DragGestureListener is responsible for causing the associated DragSource to start the Drag and Drop operation (if appropriate).

Author:
Laurence P. G. Cable
See Also:
DragGestureListener, DragGestureEvent, DragSource, Serialized Form

Field Summary
protected  Component component
          The Component associated with this DragGestureRecognizer.
protected  DragGestureListener dragGestureListener
          The DragGestureListener associated with this DragGestureRecognizer.
protected  DragSource dragSource
          The DragSource associated with this DragGestureRecognizer.
protected  ArrayList events
          The list of events (in order) that the DragGestureRecognizer "recognized" as a "gesture" that triggers a drag.
private static long serialVersionUID
           
protected  int sourceActions
          An int representing the type(s) of action(s) used in this Drag and Drop operation.
 
Constructor Summary
protected DragGestureRecognizer(DragSource ds)
          Construct a new DragGestureRecognizer given the DragSource to be used in this Drag and Drop operation.
protected DragGestureRecognizer(DragSource ds, Component c)
          Construct a new DragGestureRecognizer given the DragSource to be used in this Drag and Drop operation, and the Component this DragGestureRecognizer should "observe" for drag initiating gestures.
protected DragGestureRecognizer(DragSource ds, Component c, int sa)
          Construct a new DragGestureRecognizer given the DragSource to be used in this Drag and Drop operation, the Component this DragGestureRecognizer should "observe" for drag initiating gestures, and the action(s) supported for this Drag and Drop operation.
protected DragGestureRecognizer(DragSource ds, Component c, int sa, DragGestureListener dgl)
          Construct a new DragGestureRecognizer given the DragSource to be used in this Drag and Drop operation, the Component this DragGestureRecognizer should "observe" for drag initiating gestures, the action(s) supported for this Drag and Drop operation, and the DragGestureListener to notify once a drag initiating gesture has been detected.
 
Method Summary
 void addDragGestureListener(DragGestureListener dgl)
          Register a new DragGestureListener.
protected  void appendEvent(InputEvent awtie)
          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.
protected  void fireDragGestureRecognized(int dragAction, Point p)
          Notify the DragGestureListener that a Drag and Drop initiating gesture has occurred.
 Component getComponent()
          This method returns the Component that is to be "observed" by the DragGestureRecognizer for drag initiating gestures.
 DragSource getDragSource()
          This method returns the DragSource this DragGestureRecognizer will use in order to process the Drag and Drop operation.
 int getSourceActions()
          This method returns an int representing the type of action(s) this Drag and Drop operation will support.
 InputEvent getTriggerEvent()
          This method returns the first event in the series of events that initiated the Drag and Drop operation.
private  void readObject(ObjectInputStream s)
          Deserializes this DragGestureRecognizer.
protected abstract  void registerListeners()
          register this DragGestureRecognizer's Listeners with the Component subclasses must override this method
 void removeDragGestureListener(DragGestureListener dgl)
          unregister the current DragGestureListener
 void resetRecognizer()
          Reset the Recognizer, if its currently recognizing a gesture, ignore it.
 void setComponent(Component c)
          set the Component that the DragGestureRecognizer is associated with registerListeners() and unregisterListeners() are called as a side effect as appropriate.
 void setSourceActions(int actions)
          This method sets the permitted source drag action(s) for this Drag and Drop operation.
protected abstract  void unregisterListeners()
          unregister this DragGestureRecognizer's Listeners with the Component subclasses must override this method
private  void writeObject(ObjectOutputStream s)
          Serializes this DragGestureRecognizer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

serialVersionUID

private static final long serialVersionUID
See Also:
Constant Field Values

dragSource

protected DragSource dragSource
The DragSource associated with this DragGestureRecognizer.


component

protected Component component
The Component associated with this DragGestureRecognizer.


dragGestureListener

protected transient DragGestureListener dragGestureListener
The DragGestureListener associated with this DragGestureRecognizer.


sourceActions

protected int sourceActions
An int representing the type(s) of action(s) used in this Drag and Drop operation.


events

protected ArrayList events
The list of events (in order) that the DragGestureRecognizer "recognized" as a "gesture" that triggers a drag.

Constructor Detail

DragGestureRecognizer

protected DragGestureRecognizer(DragSource ds,
                                Component c,
                                int sa,
                                DragGestureListener dgl)
Construct a new DragGestureRecognizer given the DragSource to be used in this Drag and Drop operation, the Component this DragGestureRecognizer should "observe" for drag initiating gestures, the action(s) supported for this Drag and Drop operation, and the DragGestureListener to notify once a drag initiating gesture has been detected.

Parameters:
ds - the DragSource this DragGestureRecognizer will use to process the Drag and Drop operation
c - the Component this DragGestureRecognizer should "observe" the event stream to, in order to detect a drag initiating gesture. If this value is null, the DragGestureRecognizer is not associated with any Component.
sa - the set (logical OR) of the DnDConstants that this Drag and Drop operation will support
dgl - the DragGestureRecognizer to notify when a drag gesture is detected

Throws:
IllegalArgumentException - if ds is null.

DragGestureRecognizer

protected DragGestureRecognizer(DragSource ds,
                                Component c,
                                int sa)
Construct a new DragGestureRecognizer given the DragSource to be used in this Drag and Drop operation, the Component this DragGestureRecognizer should "observe" for drag initiating gestures, and the action(s) supported for this Drag and Drop operation.

Parameters:
ds - the DragSource this DragGestureRecognizer will use to process the Drag and Drop operation
c - the Component this DragGestureRecognizer should "observe" the event stream to, in order to detect a drag initiating gesture. If this value is null, the DragGestureRecognizer is not associated with any Component.
sa - the set (logical OR) of the DnDConstants that this Drag and Drop operation will support

Throws:
IllegalArgumentException - if ds is null.

DragGestureRecognizer

protected DragGestureRecognizer(DragSource ds,
                                Component c)
Construct a new DragGestureRecognizer given the DragSource to be used in this Drag and Drop operation, and the Component this DragGestureRecognizer should "observe" for drag initiating gestures.

Parameters:
ds - the DragSource this DragGestureRecognizer will use to process the Drag and Drop operation
c - the Component this DragGestureRecognizer should "observe" the event stream to, in order to detect a drag initiating gesture. If this value is null, the DragGestureRecognizer is not associated with any Component.

Throws:
IllegalArgumentException - if ds is null.

DragGestureRecognizer

protected DragGestureRecognizer(DragSource ds)
Construct a new DragGestureRecognizer given the DragSource to be used in this Drag and Drop operation.

Parameters:
ds - the DragSource this DragGestureRecognizer will use to process the Drag and Drop operation

Throws:
IllegalArgumentException - if ds is null.
Method Detail

registerListeners

protected abstract void registerListeners()
register this DragGestureRecognizer's Listeners with the Component subclasses must override this method


unregisterListeners

protected abstract void unregisterListeners()
unregister this DragGestureRecognizer's Listeners with the Component subclasses must override this method


getDragSource

public DragSource getDragSource()
This method returns the DragSource this DragGestureRecognizer will use in order to process the Drag and Drop operation.

Returns:
the DragSource

getComponent

public Component getComponent()
This method returns the Component that is to be "observed" by the DragGestureRecognizer for drag initiating gestures.

Returns:
The Component this DragGestureRecognizer is associated with

setComponent

public void setComponent(Component c)
set the Component that the DragGestureRecognizer is associated with registerListeners() and unregisterListeners() are called as a side effect as appropriate.

Parameters:
c - The Component or null

getSourceActions

public int getSourceActions()
This method returns an int representing the type of action(s) this Drag and Drop operation will support.

Returns:
the currently permitted source action(s)

setSourceActions

public void setSourceActions(int actions)
This method sets the permitted source drag action(s) for this Drag and Drop operation.

Parameters:
actions - the permitted source drag action(s)

getTriggerEvent

public InputEvent getTriggerEvent()
This method returns the first event in the series of events that initiated the Drag and Drop operation.

Returns:
the initial event that triggered the drag gesture

resetRecognizer

public void resetRecognizer()
Reset the Recognizer, if its currently recognizing a gesture, ignore it.


addDragGestureListener

public void addDragGestureListener(DragGestureListener dgl)
                            throws TooManyListenersException
Register a new DragGestureListener.

Parameters:
dgl - the DragGestureListener to register with this DragGestureRecognizer.

Throws:
TooManyListenersException - if a DragGestureListener has already been added.

removeDragGestureListener

public void removeDragGestureListener(DragGestureListener dgl)
unregister the current DragGestureListener

Parameters:
dgl - the DragGestureListener to unregister from this DragGestureRecognizer

Throws:
IllegalArgumentException - if dgl is not (equal to) the currently registered DragGestureListener.

fireDragGestureRecognized

protected void fireDragGestureRecognized(int dragAction,
                                         Point p)
Notify the DragGestureListener that a Drag and Drop initiating gesture has occurred. Then reset the state of the Recognizer.

Parameters:
dragAction - The action initially selected by the users gesture
p - The point (in Component coords) where the gesture originated

appendEvent

protected void appendEvent(InputEvent awtie)
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 DragGestureRecognizer implementation to add an InputEvent 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 DragGestureRecognizer maintains internally.

Parameters:
awtie - the InputEvent to add to this DragGestureRecognizer's internal array of events. Note that null is not a valid value, and will be ignored.

writeObject

private void writeObject(ObjectOutputStream s)
                  throws IOException
Serializes this DragGestureRecognizer. This method first performs default serialization. Then, this object's DragGestureListener is written out if and only if it can be serialized. If not, null is written instead.

Throws:
IOException
Since:
1.4

readObject

private void readObject(ObjectInputStream s)
                 throws ClassNotFoundException,
                        IOException
Deserializes this DragGestureRecognizer. This method first performs default deserialization for all non-transient fields. This object's DragGestureListener is then deserialized as well by using the next object in the stream.

Throws:
ClassNotFoundException
IOException
Since:
1.4