Module java.desktop
Package java.awt.dnd

# 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 java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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