# Class DragGestureRecognizer

java.lang.Object
java.awt.dnd.DragGestureRecognizer

All Implemented Interfaces:
  `Serializable`

Direct Known Subclasses:
  `MouseDragGestureRecognizer`

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 instance is obtained from the `DragSource` associated 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 fires 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).

See Also:
  - `DragGestureListener`
  - `DragGestureEvent`
  - `DragSource`
  - Serialized Form

## Field Summary

Fields
Modifier and Type
Field
Description
`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<InputEvent>`
`events`
The list of events (in order) that the `DragGestureRecognizer` "recognized" as a "gesture" that triggers a drag.
`protected int`
`sourceActions`
An `int` representing the type(s) of action(s) used in this Drag and Drop operation.

## Constructor Summary

Constructors
Modifier
Constructor
Description
`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

Modifier and Type
Method
Description
`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.
`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

### Methods declared in class Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
Modifier and Type
Method
Description
`protected Object`
`clone()`
Creates and returns a copy of this object.
`boolean`
`equals(Object obj)`
Indicates whether some other object is "equal to" this one.
`protected void`
`finalize()`
Deprecated, for removal: This API element is subject to removal in a future version.
Finalization is deprecated and subject to removal in a future release.
`final Class<?>`
`getClass()`
Returns the runtime class of this `Object`.
`int`
`hashCode()`
Returns a hash code value for this object.
`final void`
`notify()`
Wakes up a single thread that is waiting on this object's monitor.
`final void`
`notifyAll()`
Wakes up all threads that are waiting on this object's monitor.
`String`
`toString()`
Returns a string representation of the object.
`final void`
`wait()`
Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
`final void`
`wait(long timeoutMillis)`
Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`
`wait(long timeoutMillis, int nanos)`
Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

## Field Details

### 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<InputEvent> events
The list of events (in order) that the `DragGestureRecognizer` "recognized" as a "gesture" that triggers a drag.

## Constructor Details

### 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 Details

### 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.