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
`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
`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

All Methods Instance Methods Abstract Methods Concrete Methods
`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 Detail

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