During DnD operations it is possible that a user may wish to drop the
subject of the operation on a region of a scrollable GUI control that is
not currently visible to the user.

In such situations it is desirable that the GUI control detect this
and institute a scroll operation in order to make obscured region(s)
visible to the user. This feature is known as autoscrolling.

If a GUI control is both an active DropTarget
and is also scrollable, it
can receive notifications of autoscrolling gestures by the user from
the DnD system by implementing this interface.

An autoscrolling gesture is initiated by the user by keeping the drag
cursor motionless with a border region of the Component,
referred to as
the "autoscrolling region", for a predefined period of time, this will
result in repeated scroll requests to the Component
until the drag Cursor resumes its motion.

This class contains constant values representing
the type of action(s) to be performed by a Drag and Drop operation.

A DragGestureEvent is passed
to DragGestureListener's
dragGestureRecognized() method
when a particular DragGestureRecognizer detects that a
platform dependent drag initiating gesture has occurred
on the Component that it is tracking.

The action field of any DragGestureEvent instance should take one of the following
values:

 DnDConstants.ACTION_COPY
 DnDConstants.ACTION_MOVE
 DnDConstants.ACTION_LINK

Assigning the value different from listed above will cause an unspecified behavior.

The listener interface for receiving drag gesture events.
This interface is intended for a drag gesture recognition
implementation. See a specification for DragGestureRecognizer
for details on how to register the listener interface.
Upon recognition of a drag gesture the DragGestureRecognizer calls this interface's
dragGestureRecognized()
method and passes a DragGestureEvent.

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

The DragSource is the entity responsible
for the initiation of the Drag
and Drop operation, and may be used in a number of scenarios:

1 default instance per JVM for the lifetime of that JVM.
1 instance per class of potential Drag Initiator object (e.g
TextField). [implementation dependent]
1 per instance of a particular
Component, or application specific
object associated with a Component
instance in the GUI. [implementation dependent]
Some other arbitrary association. [implementation dependent]


Once the DragSource is
obtained, a DragGestureRecognizer should
also be obtained to associate the DragSource
with a particular
Component.

The initial interpretation of the user's gesture,
and the subsequent starting of the drag operation
are the responsibility of the implementing
Component, which is usually
implemented by a DragGestureRecognizer.

When a drag gesture occurs, the
DragSource's
startDrag() method shall be
invoked in order to cause processing
of the user's navigational
gestures and delivery of Drag and Drop
protocol notifications. A
DragSource shall only
permit a single Drag and Drop operation to be
current at any one time, and shall
reject any further startDrag() requests
by throwing an IllegalDnDOperationException
until such time as the extant operation is complete.

The startDrag() method invokes the
createDragSourceContext() method to
instantiate an appropriate
DragSourceContext
and associate the DragSourceContextPeer
with that.

If the Drag and Drop System is
unable to initiate a drag operation for
some reason, the startDrag() method throws
a java.awt.dnd.InvalidDnDOperationException
to signal such a condition. Typically this
exception is thrown when the underlying platform
system is either not in a state to
initiate a drag, or the parameters specified are invalid.

Note that during the drag, the
set of operations exposed by the source
at the start of the drag operation may not change
until the operation is complete.
The operation(s) are constant for the
duration of the operation with respect to the
DragSource.

An abstract adapter class for receiving drag source events. The methods in
this class are empty. This class exists only as a convenience for creating
listener objects.

Extend this class to create a DragSourceEvent listener
and override the methods for the events of interest. (If you implement the
DragSourceListener interface, you have to define all of
the methods in it. This abstract class defines null methods for them
all, so you only have to define methods for events you care about.)

Create a listener object using the extended class and then register it with
a DragSource. When the drag enters, moves over, or exits
a drop site, when the drop action changes, and when the drag ends, the
relevant method in the listener object is invoked, and the
DragSourceEvent is passed to it.

The drop site is associated with the previous dragEnter()
invocation if the latest invocation of dragEnter() on this
adapter corresponds to that drop site and is not followed by a
dragExit() invocation on this adapter.

The DragSourceContext class is responsible for managing the
initiator side of the Drag and Drop protocol. In particular, it is responsible
for managing drag event notifications to the
java.awt.dnd.DragSourceListeners
and java.awt.dnd.DragSourceMotionListeners, and providing the
Transferable representing the source data for the drag operation.

Note that the DragSourceContext itself
implements the DragSourceListener and
DragSourceMotionListener interfaces.
This is to allow the platform peer
(the DragSourceContextPeer instance)
created by the DragSource to notify
the DragSourceContext of
state changes in the ongoing operation. This allows the
DragSourceContext object to interpose
itself between the platform and the
listeners provided by the initiator of the drag operation.


By default, DragSourceContext sets the cursor as appropriate
for the current state of the drag and drop operation. For example, if
the user has chosen the move action,
and the pointer is over a target that accepts
the move action, the default move cursor is shown. When
the pointer is over an area that does not accept the transfer,
the default "no drop" cursor is shown.

This default handling mechanism is disabled when a custom cursor is set
by the setCursor(java.awt.Cursor) method. When the default handling is disabled,
it becomes the responsibility
of the developer to keep the cursor up to date, by listening
to the DragSource events and calling the setCursor() method.
Alternatively, you can provide custom cursor behavior by providing
custom implementations of the DragSource
and the DragSourceContext classes.

The DragSourceDragEvent is
delivered from the DragSourceContextPeer,
via the DragSourceContext, to the DragSourceListener
registered with that DragSourceContext and with its associated
DragSource.

The DragSourceDragEvent reports the target drop action
and the user drop action that reflect the current state of
the drag operation.

Target drop action is one of DnDConstants that represents
the drop action selected by the current drop target if this drop action is
supported by the drag source or DnDConstants.ACTION_NONE if this
drop action is not supported by the drag source.

User drop action depends on the drop actions supported by the drag
source and the drop action selected by the user. The user can select a drop
action by pressing modifier keys during the drag operation:


  Ctrl  Shift -> ACTION_LINK
  Ctrl         -> ACTION_COPY
  Shift        -> ACTION_MOVE
If the user selects a drop action, the user drop action is one of
DnDConstants that represents the selected drop action if this
drop action is supported by the drag source or
DnDConstants.ACTION_NONE if this drop action is not supported
by the drag source.

If the user doesn't select a drop action, the set of
DnDConstants that represents the set of drop actions supported
by the drag source is searched for DnDConstants.ACTION_MOVE,
then for DnDConstants.ACTION_COPY, then for
DnDConstants.ACTION_LINK and the user drop action is the
first constant found. If no constant is found the user drop action
is DnDConstants.ACTION_NONE.

The DragSourceDropEvent is delivered
from the DragSourceContextPeer,
via the DragSourceContext, to the dragDropEnd
method of DragSourceListeners registered with that
DragSourceContext and with its associated
DragSource.
It contains sufficient information for the
originator of the operation
to provide appropriate feedback to the end user
when the operation completes.

This class is the base class for
DragSourceDragEvent and
DragSourceDropEvent.

DragSourceEvents are generated whenever the drag enters, moves
over, or exits a drop site, when the drop action changes, and when the drag
ends. The location for the generated DragSourceEvent specifies
the mouse cursor location in screen coordinates at the moment this event
occurred.

In a multi-screen environment without a virtual device, the cursor location is
specified in the coordinate system of the initiator
GraphicsConfiguration. The initiator
GraphicsConfiguration is the GraphicsConfiguration
of the Component on which the drag gesture for the current drag
operation was recognized. If the cursor location is outside the bounds of
the initiator GraphicsConfiguration, the reported coordinates are
clipped to fit within the bounds of that GraphicsConfiguration.

In a multi-screen environment with a virtual device, the location is specified
in the corresponding virtual coordinate system. If the cursor location is
outside the bounds of the virtual device the reported coordinates are
clipped to fit within the bounds of the virtual device.

The DragSourceListener defines the
event interface for originators of
Drag and Drop operations to track the state of the user's gesture, and to
provide appropriate "drag over"
feedback to the user throughout the
Drag and Drop operation.

The drop site is associated with the previous dragEnter()
invocation if the latest invocation of dragEnter() on this
listener:

corresponds to that drop site and
 is not followed by a dragExit() invocation on this listener.

A listener interface for receiving mouse motion events during a drag
operation.

The class that is interested in processing mouse motion events during
a drag operation either implements this interface or extends the abstract
DragSourceAdapter class (overriding only the methods of
interest).

Create a listener object using that class and then register it with
a DragSource. Whenever the mouse moves during a drag
operation initiated with this DragSource, that object's
dragMouseMoved method is invoked, and the
DragSourceDragEvent is passed to it.

The DropTarget is associated
with a Component when that Component
wishes
to accept drops during Drag and Drop operations.

 Each
DropTarget is associated with a FlavorMap.
The default FlavorMap hereafter designates the
FlavorMap returned by SystemFlavorMap.getDefaultFlavorMap().

this protected nested class implements autoscrolling

An abstract adapter class for receiving drop target events. The methods in
this class are empty. This class exists only as a convenience for creating
listener objects.

Extend this class to create a DropTargetEvent listener
and override the methods for the events of interest. (If you implement the
DropTargetListener interface, you have to define all of
the methods in it. This abstract class defines a null implementation for
every method except drop(DropTargetDropEvent), so you only have
to define methods for events you care about.) You must provide an
implementation for at least drop(DropTargetDropEvent). This
method cannot have a null implementation because its specification requires
that you either accept or reject the drop, and, if accepted, indicate
whether the drop was successful.

Create a listener object using the extended class and then register it with
a DropTarget. When the drag enters, moves over, or exits
the operable part of the drop site for that DropTarget, when
the drop action changes, and when the drop occurs, the relevant method in
the listener object is invoked, and the DropTargetEvent is
passed to it.

The operable part of the drop site for the DropTarget is
the part of the associated Component's geometry that is not
obscured by an overlapping top-level window or by another
Component higher in the Z-order that has an associated active
DropTarget.

During the drag, the data associated with the current drag operation can be
retrieved by calling getTransferable() on
DropTargetDragEvent instances passed to the listener's
methods.

Note that getTransferable() on the
DropTargetDragEvent instance should only be called within the
respective listener's method and all the necessary data should be retrieved
from the returned Transferable before that method returns.

A DropTargetContext is created
whenever the logical cursor associated
with a Drag and Drop operation coincides with the visible geometry of
a Component associated with a DropTarget.
The DropTargetContext provides
the mechanism for a potential receiver
of a drop operation to both provide the end user with the appropriate
drag under feedback, but also to effect the subsequent data transfer
if appropriate.

The DropTargetDragEvent is delivered to a
DropTargetListener via its
dragEnter() and dragOver() methods.

The DropTargetDragEvent reports the source drop actions
and the user drop action that reflect the current state of
the drag operation.

Source drop actions is a bitwise mask of DnDConstants
that represents the set of drop actions supported by the drag source for
this drag operation.

User drop action depends on the drop actions supported by the drag
source and the drop action selected by the user. The user can select a drop
action by pressing modifier keys during the drag operation:


  Ctrl  Shift -> ACTION_LINK
  Ctrl         -> ACTION_COPY
  Shift        -> ACTION_MOVE
If the user selects a drop action, the user drop action is one of
DnDConstants that represents the selected drop action if this
drop action is supported by the drag source or
DnDConstants.ACTION_NONE if this drop action is not supported
by the drag source.

If the user doesn't select a drop action, the set of
DnDConstants that represents the set of drop actions supported
by the drag source is searched for DnDConstants.ACTION_MOVE,
then for DnDConstants.ACTION_COPY, then for
DnDConstants.ACTION_LINK and the user drop action is the
first constant found. If no constant is found the user drop action
is DnDConstants.ACTION_NONE.

The DropTargetDropEvent is delivered
via the DropTargetListener drop() method.

The DropTargetDropEvent reports the source drop actions
and the user drop action that reflect the current state of the
drag-and-drop operation.

Source drop actions is a bitwise mask of DnDConstants
that represents the set of drop actions supported by the drag source for
this drag-and-drop operation.

User drop action depends on the drop actions supported by the drag
source and the drop action selected by the user. The user can select a drop
action by pressing modifier keys during the drag operation:


  Ctrl  Shift -> ACTION_LINK
  Ctrl         -> ACTION_COPY
  Shift        -> ACTION_MOVE
If the user selects a drop action, the user drop action is one of
DnDConstants that represents the selected drop action if this
drop action is supported by the drag source or
DnDConstants.ACTION_NONE if this drop action is not supported
by the drag source.

If the user doesn't select a drop action, the set of
DnDConstants that represents the set of drop actions supported
by the drag source is searched for DnDConstants.ACTION_MOVE,
then for DnDConstants.ACTION_COPY, then for
DnDConstants.ACTION_LINK and the user drop action is the
first constant found. If no constant is found the user drop action
is DnDConstants.ACTION_NONE.

The DropTargetEvent is the base
class for both the DropTargetDragEvent
and the DropTargetDropEvent.
It encapsulates the current state of the Drag and
Drop operations, in particular the current
DropTargetContext.

The DropTargetListener interface
is the callback interface used by the
DropTarget class to provide
notification of DnD operations that involve
the subject DropTarget. Methods of
this interface may be implemented to provide
"drag under" visual feedback to the user throughout
the Drag and Drop operation.

Create a listener object by implementing the interface and then register it
with a DropTarget. When the drag enters, moves over, or exits
the operable part of the drop site for that DropTarget, when
the drop action changes, and when the drop occurs, the relevant method in
the listener object is invoked, and the DropTargetEvent is
passed to it.

The operable part of the drop site for the DropTarget is
the part of the associated Component's geometry that is not
obscured by an overlapping top-level window or by another
Component higher in the Z-order that has an associated active
DropTarget.

During the drag, the data associated with the current drag operation can be
retrieved by calling getTransferable() on
DropTargetDragEvent instances passed to the listener's
methods.

Note that getTransferable() on the
DropTargetDragEvent instance should only be called within the
respective listener's method and all the necessary data should be retrieved
from the returned Transferable before that method returns.

This exception is thrown by various methods in the java.awt.dnd package.
It is usually thrown to indicate that the target in question is unable
to undertake the requested operation that the present time, since the
underlying DnD system is not in the appropriate state.

This abstract subclass of DragGestureRecognizer
defines a DragGestureRecognizer
for mouse-based gestures.

Each platform implements its own concrete subclass of this class,
available via the Toolkit.createDragGestureRecognizer() method,
to encapsulate
the recognition of the platform dependent mouse gesture(s) that initiate
a Drag and Drop operation.

Mouse drag gesture recognizers should honor the
drag gesture motion threshold, available through
DragSource.getDragThreshold().
A drag gesture should be recognized only when the distance
in either the horizontal or vertical direction between
the location of the latest mouse dragged event and the
location of the corresponding mouse button pressed event
is greater than the drag gesture motion threshold.

Drag gesture recognizers created with
DragSource.createDefaultDragGestureRecognizer(java.awt.Component, int, java.awt.dnd.DragGestureListener)
follow this convention.