This document has these sections:
This specification defines the API for the drag and drop facilities for the Java 2 Platform.
The primary requirements that this specification addresses, are:
java.awt.datatransfer.*
package to enable the transfer of data, described by an extensible
data type system based on the MIME standard.
The specification derives from the previous work mentioned above, but incorporates significant differences from that original work as a result of the advent of the JavaBeansTM event model, lightweight (Swing) components, and an increasing understanding of the cross-platform integration and interoperability issues.
The following sections cover the drag and drop API.
Drag and drop is a direct manipulation gesture found in many graphical user interface systems that provides a mechanism to transfer information between two entities logically associated with presentation elements in the GUI. Normally driven by a physical gesture of a human user using an appropriate input device, drag and drop provides both a mechanism to enable continuous feedback regarding the possible outcome of any subsequent data transfer to the user during navigation over the presentation elements in the GUI, and the facilities to provide for any subsequent data negotiation and transfer.
A typical drag and drop operation can be decomposed into the following states (not entirely sequentially):
DragSource comes into existence, associated with
some presentation element (Component) in the GUI,
to initiate a drag and drop of some potentially Transferable
data.
DropTargets come into/go out of existence,
associated with presentation elements in the GUI (Components),
potentially capable of consuming Transferable data types.
DragGestureRecognizer is obtained from the
DragSource and is associated with a Component
in order to track and identify any drag initiating gesture by the user
over the Component.
Component,
which the registered DragGestureRecognizer detects,
and notifies its DragGestureListener of.
Note: Although the body of this document consistently refers to the
stimulus for a drag and drop operation being a physical gesture by a
human user this does not preclude a programmatically driven DnD operation
given the appropriate implementation of a DragSource.
DragGestureListener causes the DragSource
to initiate the drag and drop operation on behalf of the user,
perhaps animating the GUI Cursor and/or rendering an
Image of the item(s) that are the subject of the operation.
Component(s) in the GUI
with associated DropTarget(s), the DragSource
receives notifications in order to provide "Drag Over"
feedback effects, and the DropTarget(s) receive
notifications in order to provide "Drag Under"
feedback effects based upon the operation(s) supported and the data
type(s) involved.
The gesture itself moves a logical cursor across the GUI hierarchy,
intersecting the geometry of GUI Component(s),
possibly resulting in the logical "Drag" cursor entering,
crossing, and subsequently leaving Component(s) and
associated DropTarget(s).
The DragSource object manifests "Drag Over"
feedback to the user, in the typical case by animating the GUI
Cursor associated with the logical cursor.
DropTarget objects manifest "Drag Under"
feedback to the user, in the typical case, by rendering animations
into their associated GUI Component(s) under the GUI
Cursor.
DragSource and DropTarget:
Copy, Move or Reference(link).
DragSource and the set of data types comprehensible
by the DropTarget.
DragSource and
DropTarget receive notifications that include,
and result in the type negotiation and transfer of, the information
associated with the DragSource via a Transferable
object.
The remainder of this document details the proposed API changes to support this model.
The gesture(s) that can initiate a drag and drop operation vary, not only
per platform, but also per Component, and per device.
Therefore a mechanism is required in order to encapsulate these
dependencies, thus making the task of the author of a Component
that wishes to initiate a drag and drop operation much simpler.
The DragGestureRecognizer is an abstract base class for
all device/platform/Component specific drag and drop
gesture recognizers, and is defined as:
public abstract DragGestureRecognizer {
protected DragGestureRecognizer(
DragSource ds,
Component c,
int srcActions,
DragGestureListener dgl
);
public Component getComponent();
public void setComponent(Component c);
public int getSourceActions();
public void setSourceActions(int actions);
public java.awt.InputEvent getTriggerEvent();
public void resetRecognizer();
public void addDragGestureListener(
DragGestureListener dgl
) throws TooManyListenerExceptions;
public void removeDragGestureListener(
DragGestureListener dgl
);
protected abstract void registerListeners();
protected abstract void unregisterListeners();
protected void fireDragGestureRecognized(
int dragAction
);
protected void appendEvent(InputEvent awtie);
}
An appropriate concrete subclasses of DragGestureRecognizer
for a particular may be obtained in a variety of ways; from a
DragSource instance, from the Toolkit,
or by other means. Concrete implementation subclasses are obtained
through standard APIs' by specifying a Class reference
to an abstract DragGestureRecognizer superclass,
an instance of a concrete subclass of this actual parameter is
instantiated and returned to the requestor.
Once a DragGestureRecognizer instance is associated with a
Component and a DragSource it registers its
own particular set of EventListeners' with the
target Component in order to monitor the appropriate
events being delivered to that Component to detect an
initiating gesture. (Using registerListeners and
unregisterListeners to add/remove these monitoring
EventListeners').
Note that a DragGestureRecognizer may throw either an
IllegalStateException or an IllegalArgumentException
if either the Component or DragSource specified
is either not in the correct state for, or is not interoperable with,
that DragGestureRecognizer.
When a concrete DragGestureRecognizer instance detects
a drag-initiating user 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).
The implementation provides (at least) an abstract subclass for
recognizing mouse device gestures MouseDragGestureRecognizer.
Other abstract subclasses may be provided by the platform to support
other input devices or particular Component class semantics.
Concrete superclasses of this MouseDragGestureRecognizer
that encapsulate platform dependent mouse based gestures are available
from the Toolkit object via its
createDragGestureRecognizer(Class adgrc, DragSource ds,
Component c, int sa, DragGestureListener dgl) method.
This Toolkit API provides platform dependent concrete
implementations that extend particular platform independent abstract
definitions (classes).
The MouseDragGestureRecognizer abstract class is defined as:
public abstract MouseDragGestureRecognizer
extends DragGestureRecognizer
implements MouseListener, MouseMotionListener {
public MouseDragGestureRecognizer(
DragSource ds,
Component c,
int sa,
DragGestureListener dsl
);
//...
}
The DragGestureListener is defined as:
public interface DragGestureListener extends EventListener {
void dragGestureRecognized(DragGestureEvent dge);
}
Usually the dragGestureRecognized() method will simply,
via the DragGestureEvent's convenience API
startDrag, start a drag and drop operation on the
associated DragSource.
Note that per Component (class or instance) behavior
that may effect the initiating gesture would usually be implemented
in this DragGestureListener method, or in the
DragGestureRecognizer subclass where appropriate or possible.
The DragGestureEvent is defined as:
publc class DragGestureEvent extends EventObject {
public DragGestureEvent(DragGestureRecognizer dgr,
int dragAction,
java.util.List events
);
public DragGestureRecognizer getSourceAsDragGestureRecognizer();
public Component getComponent();
public DragSource getDragSource();
public java.util.Iterator iterator();
public Object[] toArray();
public Object[] toArray(Object[] array);
public int getDragAction();
public startDrag(Cursor dragCursor,
Transferable t,
DragSourceListener dsl
);
public startDrag(Cursor dragCursor,
Image dragImage,
Point imageOffset,
Transferable t,
DragSourceListener dsl
);
//...
}
The DragGestureEvent encapsulates all the information
regarding the nature of the gesture that has just been recognized, including:
DragGestureRecognizer that recognized the gesture
Component that the gesture occurred on
DragSource that will process the operation
InputEvent objects that comprise the gesture.
The DragSource is the entity responsible for the initiation
of the drag and drop operation:
The DragSource and associated constant interfaces are
defined as follows:
The DnDConstants class defines the operations that may be
applied to the subject of the transfer:
public final class java.awt.dnd.DnDConstants {
public static int ACTION_NONE = 0x0;
public static int ACTION_COPY = 0x1;
public static int ACTION_MOVE = 0x2;
public static int ACTION_COPY_OR_MOVE= ACTION_COPY | ACTION_MOVE;
public static int ACTION_REFERENCE = 0x40000000;
}
public class java.awt.dnd.DragSource {
public static Cursor DefaultCopyDrop;
public static Cursor DefaultMoveDrop;
public static Cursor DefaultLinkDrop;
public static Cursor DefaultCopyNoDrop;
public static Cursor DefaultMoveNoDrop;
public static Cursor DefaultLinkNoDrop;
public static DragSource getDefaultDragSource();
public static boolean isDragImageSupported();
public void startDrag(DragGestureEvent trigger,
Cursor dragCursor,
Image dragImage,
Point dragImageOffset,
Transferable transferable,
DragSourceListener dsl,
FlavorMap fm)
throws InvalidDnDOperationException;
protected DragSourceContext createDragSourceContext(
DragSourceContextPeer dscp,
DragGestureEvent trigger,
Cursor dragCursor,
Image dragImage,
Point dragImageOffset,
Transferable transferable,
DragSourceListener dsl
);
public FlavorMap getFlavorMap();
public DragGestureRecongizer createDragGestureRecognizer(
Class abstractRecognizerClass,
Component c,
int srcActions,
DragGestureListener dgl
);
public DragGestureRecongizer createDefaultDragGestureRecognizer(
Component c,
int srcActions,
DragGestureListener dgl
);
//...
}
The DragSource may be used in a number of scenarios:
TextField). [implementation dependent]
Component, or
application specific object associated with a Component
instance in the GUI. [implementation dependent]
A controlling object, shall obtain a DragSource instance
prior to a user's gesture, effecting an associated Component,
in order to process the operation. Once obtained a
DragGestureRecognizer should be obtained and used to
associate the DragSource with a Component.
The initial interpretation of the user's gesture, and the subsequent
starting of the drag operation are the responsibility of the implementing
Component, this is usually implemented by a
DragGestureRecognizer.
When a 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.
In order to start a drag operation the caller of the
startDrag method shall provide the following parameters:
DragGestureEvent for the gesture.
Cursor representing the initial "Drag Over"
feedback for the operation(s) specified. (This shall be a
Cursor that provides "No Drop" visual
feedback to the user).
Image to visually represent the item, or item(s) that are the subject(s) of the operation.
On platforms that can support this feature, a "Drag"
image may be associated with the operation to enhance the fidelity
of the "Drag Over" feedback. This image would typically
be a small "iconic" representation of the object, or objects
being dragged, and would be rendered by the underlying system, tracking
the movement of, and coincident with, but typically in addition to the
Cursor animation.
Where this facility is not available, or where the image is not of a
suitable type to be rendered by the underlying system, this parameter
is ignored and only Cursor "Drag Over"
animation results, so applications should not depend upon this feature.
The presence of the facility on a particular platform may be tested by
invoking the static method isDragImageSupported.
Image is provided; a Point
(in the co-ordinate space of the Component) specifying
the initial origin of that Image relative to the co-ordinates
of the "hotspot" of the drag "Cursor", in the
co-ordinate space of the Component, at the time of the
initial gesture, for the purposes of initiating a correctly positioned
"Drag Over" animation of that Image relative
to that "hotspot".
Transferable that describes the various
DataFlavor(s) that represent the subject(s) of any
subsequent data transfer that may result from a successful Drop.
The Transferable instance associated with the
DragSource at the start of the drag operation,
represents the object(s) or data that are the operand(s),
or the subject(s), of the Drag and Drop operation, that is the
information that will subsequently be passed from the
DragSource to the DropTarget as a result
of a successful Drop on the Component associated with
that DropTarget.
Note that multiple (collections) of either homogeneous, or heterogeneous,
objects may be subject of a Drag and Drop operation, by creating a
container object, that is the subject of the transfer, and implements
Transferable. However it should be noted that since none
of the targeted native platforms systems support a standard mechanism
for describing and thus transferring such collections it is not possible
to implement such transfers in a transparent, or platform portable fashion.
DragSourceListener instance, which will subsequently
receive events notifying it of changes in the state of the ongoing
operation in order to provide the "Drag Over" feedback
to the user.
As stated above, the primary role of the startDrag method
is to initiate a Drag on behalf of the user. In order to accomplish this,
the startDrag method must create a DragSourceContext
instance to track the operation itself, and more importantly it must initiate
the operation itself in the underlying platform implementation.
In order to accomplish this, the DragSource must first obtain
a DragSourceContextPeer from the underlying system
(usually via an invocation of
java.awt.Toolkit.createDragSourceContextPeer method)
and subsequently associate this newly created
DragSourceContextPeer (which provides a platform
independent interface to the underlying systems capabilities)
with a DragSourceContext.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 shall throw 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 neither the set of operations the source
exposed at the start of the drag operation may change for the duration
of the operation, in other words the operation(s) and are constant
for the duration of the operation with respect to the DragSource.
The getFlavorMap method is used by the underlying system
to obtain a FlavorMap object in order to map the
DataFlavors exposed by the Transferable
to data type names of the underlying DnD platform.
[see later for details of the FlavorMap]
A "private" FlavorMap may be provided to the
startDrag() method of the DragSource, or null,
in which case the "default" FlavorMap for that
DragSource class or instance is used.
As a result of a DragSource's
startDrag method being successfully invoked an instance
of the DragSourceContext class is created. This instance
is responsible for tracking the state of the operation on behalf of the
DragSource and dispatching state changes to the
DragSourceListener.
The DragSourceContext class is defined as follows:
public class DragSourceContext implements DragSourceListener {
public DragSourceContext(
DragSourceContextPeer dscp,
DragGestureEvent trigger,
Cursor dragCursor,
Image dragImage,
Point dragOffset,
Transferable transferable,
DragSourceListener dsl
);
public DragSource getDragSource();
public Component getComponent();
public DragGestureEvent getTrigger();
public Image getDragImage();
public Point getDragImageOffset();
public void transferablesFlavorsChanged();
public int getSourceActions();
public Cursor getCursor();
pbulic void setCursor(Cursor Cursor)
throws InvalidDnDOperationException;
public void addDragSourceListener(DragSourceListener dsl)
throws TooManyListenersException;
public void removeDragSourceListener(DragSourceListener dsl);
protected updateCurrentCursor(int dropOperation,
int targetActions,
int status
);
// values for status parameter above.
protected static final int DEFAULT = 0;
protected static final int ENTER = 1;
protected static final int OVER = 2;
protected static final int CHANGED = 3;
//...
}
Note that the DragSourceContext itself implements
DragSourceListener, this is to allow the platform peer,
the DragSourceContextPeer instance, created by the
DragSource, to notify the DragSourceContext
of changes in state in the ongoing operation, and thus allows the
DragSourceContext to interpose itself between the platform
and the DragSourceListener provided by the initiator of the
operation.
The state machine the platform exposes, with respect to the source, or initiator of the Drag and Drop operation is detailed below:
Notifications of changes in state with respect to the initiator
during a drag and drop operation, as illustrated above, are delivered
from the DragSourceContextPeer, to the appropriate
DragSourceContext, which delegates notifications,
via a unicast JavaBeans compliant EventListener subinterface,
to an arbitrary object that implements DragSourceListener
registered with the DragSource via startDrag.
The primary responsibility of the DragSourceListener
is to monitor the progress of the user's navigation during the drag and
drop operation and provide the "Drag-Over" effects feedback
to the user. Typically this is accomplished via changes to the
"Drag Cursor".
Every drag operation has 2 logical cursor states (Drag Cursors) associated with it:
Cursor, the cursor displayed when dragging
over a valid DropTarget.
Cursor, the cursor displayed when dragging
over everything else (the initial state of the cursor at the start
of a drag).
The state of the Cursor may be modified by calling the
setCursor method of the DragSourceContext.
The DragSourceListener interface is defined as follows:
public interface java.awt.dnd.DragSourceListener
extends java.util.EventListener {
void dragEnter (DragSourceDragEvent dsde);
void dragOver (DragSourceDragEvent dsde);
void dropActionChanged (DragSourceDragEvent dsde);
void dragExit (DragSourceEvent dse);
void dragDropEnd (DragSourceDropEvent dsde);
}
As the drag operation progresses, the DragSourceListener's
dragEnter, dragOver, and dragExit
methods shall be invoked as a result of the user's navigation of the logical
"Drag" cursor's location intersecting the geometry
of GUI Component(s) with associated DropTarget(s).
[See below for details of the DropTarget's protocol
interactions].
The DragSourceListener's dragEnter
method is invoked when the following conditions are true:
Component's visible geometry.
Component has an active DropTarget
associated.
The DropTarget's registered DropTargetListener
dragEnter method is invoked and returns successfully.
The registered DropTargetListener invokes the
DropTargetDragEvent's acceptDrag
method to accept the drag based upon interrogation of the source's
potential drop actions and available data types (DataFlavors).
The DragSourceListener's dragOver method is invoked
when the following conditions are true:
The DragSourceListener's dragExit
method is invoked when one of the following conditions is true:
Component associated with the previous
dragEnter invocation.
Or:
Component that the logical cursor's hotspot
intersected that resulted in the previous dragEnter
invocation, no longer has an active DropTarget
(or DropTargetListener) associated.
Or:
DropTarget's DropTargetListener
has invoked rejectDrag since the last
dragEnter or dragOver invocation.
The DragSourceListener's dropActionChanged()
method is invoked when the state of the input device(s), typically the
mouse buttons or keyboard modifiers, that the user is interacting with
in order to perform the drag operation, changes.
The dragDropEnd() method is invoked to signify that the
operation is completed. The getDropSuccess method of the
DragSourceDropEvent can be used to determine the termination
state. The getDropAction method returns the operation that
the DropTarget selected (via the DropTargetDropEvent
acceptDrop parameter) to apply to the drop operation.
Once this method is complete the current DragSourceContext
and the associated resources are invalid.
The DragSourceEvent class is the root Event
class for all events pertaining to the DragSource,
and is defined as follows:
public class java.awt.dnd.DragSourceEvent extends java.util.EventObject {
public DragSourceEvent(DragSourceContext dsc);
public DragSourceContext getDragSourceContext();
//...
};
An instance of this event is passed to the DragSourceListener
dragExit method.
The DragSourceDragEvent class is defined as follows:
public class java.awt.dnd.DragSourceDragEvent extends DragSourceEvent {
public int getTargetActions();
public int getUserAction();
public int getGestureModifiers();
public int getGestureModifiersEx();
public int getDropAction();
}
An instance of the above class is passed to a
DragSourceListener's dragEnter,
dragOver, and dragGestureChanged methods.
The getDragSourceContext method returns the
DragSourceContext associated with the current drag and drop
operation.
The getUserAction method returns the action that is currently
selected by the user's gesture.
The getTargetActions method returns 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.
The logical intersection of these two results and the set of drop actions
supported by the drag source defines the actual effect of a drop and is
returned via getDropAction.
The getGestureModifiers method returns the current state of
the input device modifiers, usually the mouse buttons and keyboard
modifiers, associated with the user's gesture.
The getGestureModifiersEx method returns the current state
of the input device extended modifiers associated with the user's
gesture.
The DragSourceDropEvent class is defined as follows:
public public class java.awt.dnd.DragSourceDropEvent
extends java.util.EventObject {
public DragSourceDropEvent(DragSourceContext dsc);
public DragSourceDropEvent(DragSourceContext dsc,
int action,
boolean success);
public boolean getDropSuccess();
public int getDropAction();
}
An instance of the above class is passed to a
DragSourceListener's dragDropEnd method.
This event encapsulates the termination state of the drag and drop
operation for the DragSource.
If the drop occurs, then the participating DropTarget
will signal the success or failure of the data transfer via the
DropTargetContext's dropComplete method,
this status is made available to the initiator via the
getDropSuccess method. The operation that the destination
DropTarget selected to perform on the subject of the drag
(passed by the DropTarget's acceptDrop method)
is returned via the getDropAction method.
If the drag operation was aborted for any reason prior to a drop
occurring, for example if the user ends the gesture outside a
DropTarget, or if the DropTarget invokes
rejectDrop, the getDropSuccess method will
return false, otherwise true.
The java.awt.Component class has two additional methods
added to allow the (dis)association with a DropTarget.
In particular:
public class java.awt.Component /* ... */ {
//...
public synchronized void setDropTarget(DropTarget dt);
public synchronized DropTarget getDropTarget(DropTarget df);
//...
}
To associate a DropTarget with a Component
one may invoke either; DropTarget.setCompononent or
Component.setDropTarget methods. Thus conforming
implementations of both methods are required to guard against mutual
recursive invocations.
To disassociate a DropTarget with a Component
one may invoke either; DropTarget.setCompononent(null) or
Component.setDropTarget(null) methods.
Conformant implementations of both setter methods in
DropTarget and Component should be implemented
in terms of each other to ensure proper maintenance of each other's state.
The setDropTarget method throws
IllegalArgumentException if the DropTarget
actual parameter is not suitable for use with this class/instance of
Component. It may also throw
UnsupportedOperationException if, for instance, the
Component does not support external setting of a
DropTarget.
A DropTarget encapsulates all of the platform-specific
handling of the Drag and Drop protocol with respect to the role of the
recipient or destination of the operation.
A single DropTarget instance may typically be associated
with any arbitrary instance of java.awt.Component.
Establishing such a relationship exports the associated
Components geometry to the client desktop as being
receptive to drag and drop operations when the coordinates of the
logical cursor intersects that visible geometry.
The DropTarget class is defined as follows:
public class java.awt.dnd.DropTarget
implements DropTargetListener, Serializable {
public DropTarget(Component c,
int actions,
DropTargetListener dsl,
boolean isActive,
FlavorMap fm
);
public DropTarget();
public DropTarget(Component c);
public DropTarget(Component c, DropTargetListener dsl);
public Component getComponent();
public void setComponent(Component c);
public DropTargetContext getDropTargetContext();
public void addDropTargetListener(DropTargetListener dte)
throws TooManyListenersException;
public void removeDropTargetListener(DropTargetListener dte);
public void setActive(boolean active);
public boolean isActive();
public FlavorMap getFlavorMap();
public void setFlavorMap(FlavorMap fm);
public void setDefaultActions(int actions);
public int getDefaultActions();
protected DropTargetContext createDropTargetContext();
public void addNotify(ComponentPeer cp);
public void removeNotify(ComponentPeer cp);
// ...
}
The setComponent method throws
IllegalArgumentException if the Component
actual parameter is not appropriate for use with this class/instance of
DropTarget, and may also throw
UnsupportedOperationException if the Component
specified disallows the external setting of a DropTarget.
The addDropTargetListener and
removeDropTargetListener methods allow the unicast
DropTargetListener to be changed.
The setActive and isActive methods allow the
DropTarget to be made active or otherwise and for its current
state to be determined.
The getFlavorMap methods is used to obtain the
FlavorMap associated with this DropTarget
for the purposes of mapping any platform dependent type names to/from
their corresponding platform independent DataFlavors.
The setFlavorMap method allows a new FlavorMap
to be assigned to the DropTarget, a parameter of null causes
a "default" FlavorMap to be installed for the
DropTarget.
The createDropTargetContext method is only invoked to
provide the underlying platform dependent peer with an instantiation
of a new DropTargetContext as a Drag operation initially
encounters the Component associated with the
DropTarget. If no DropTargetContext is
currently associated with a DropTarget, a permitted
side-effect of an invocation of getDropTargetContext
is to instantiate a new DropTargetContext.
The addNotify and removeNotify methods
are only called from Component to notify the
DropTarget of the Component's (dis)association
with its ComponentPeer.
Note that the DropTarget itself implements
DropTargetListener, this is to allow the platform peer,
the DropTargetContextPeer instance, created by the platform,
to notify the DropTarget of changes in state in the ongoing
operation, and thus allows the DropTarget to interpose itself
between the platform and the DropTargetListener registered
with the DropTarget.
As the logical cursor associated with an ongoing drag and drop operation
first intersects the visible geometry of a Component with
an associated DropTarget, the DropTargetContext
associated with the DropTarget is the interface, through which,
access to, and control over state of the recipient protocol is achieved
from the DropTargetListener.
A DropTargetContext is created by a
DropTarget, via it's createDropTargetContext method,
as a side effect of a call to a DropTarget's
getDropTargetContext method, if no <>DropTargetContext
currently exists for that DropTarget.
The DropTargetContext interface is defined as follows:
public class DropTargetContext {
public DropTarget getDropTarget();
public Component getComponent();
public void dropComplete(boolean success)
throws InvalidDnDOperationException;
public void acceptDrag(int dropAction);
public void rejectDrag();
public void acceptDrop(int dropAction);
public void rejectDrop();
public void addNotify(DropTargetContextPeer dtcp);
public void removeNotify();
protected Transferable createTransferableProxy(Transferable t,
boolean isLocal
);
protected void setTargetActions(int actions);
protected int getTargetActions();
protected DataFlavor[] getCurrentDataFlavors();
protected List getCurrentDataFlavorsAsList();
protected boolean isDataFlavorSupported(DataFlavor df);
protected Transferable getTransferable();
// ...
}
Most of the access and control methods are protected, since public
access to their state is usually achieved by calling through a particular
DropTargetEvent subclass that delegates the request to the
DropTargetContext.
The getDropTarget() method return the DropTarget
that created this DropTargetContext.
The getComponent method returns the Component
associated with the DropTarget that created this
DropTargetContext.
The acceptDrag method is delegated from the similar
method on DropTargetDragEvent and is invoked from one
of the DropTargetListener's methods; dragEnter(),
dragOver or dropActionChanged to signify that
the recipient is prepared to accept a drop with the operation specified,
which is usually the user's currently selected action.
The rejectDrag method is delegated from the similar method
on DropTargetDragEvent and is invoked from one of the
DropTargetListener's methods; dragEnter,
dragOver or dropActionChanged to signify that
the recipient is unable to accept a drop with the user's currently
selected action.
The acceptDrop method is delegated from the similar method
on DropTargetDropEvent and is invoked from the
DropTargetListener's drop method to signify
that the recipient is prepared to accept a drop with the operation specified,
which is usually the user's currently selected action.
The rejectDrop method is delegated from the similar method
on DropTargetDropEvent and is invoked from the
DropTargetListener's drop method to signify
that the recipient is unable to accept a drop with the user's currently
selected action. This terminates a drag and drop operation without a
data transfer.
The dropComplete method signals to the originating
DragSource that the DropTargetListener
has completed the transfer(s) that comprise the subject of the drag and drop
operation and that the operation is complete. The success (or failure)
of the transfer(s) and the subsequent application of the operation specified
is signaled by the value of the actual parameter.
The getDataFlavors method returns an array of the
DataFlavors available from the DragSource.
The getTransferable method returns a Transferable
(not necessarily the one the DragSource registered, it may be
a proxy, and certainly shall be in the inter-JVM case) to enable data
transfers to occur via its getTransferData method.
Note that it is illegal to invoke getTransferable without
first invoking an acceptDrop.
The addNotify and removeNotify methods are
exclusively called by the underlying platform's
DropTargetContextPeer in order to notify the
DropTargetContext that a drag and drop operation is
occurring/ceasing on the DropTargetContext and associated
DropTarget.
The createTransferableProxy method enables a
DropTargetContext implementation to interpose a
Transferable between the DropTargetListener and
the Transferable provided by the caller, which is typically
the underlying platform DropTargetContextPeer.
Providing the appropriate "Drag-under" feedback semantics,
and processing of any subsequent Drop, is enabled through the
DropTargetListener asssociated with a DropTarget.
The DropTargetListener determines the appropriate
"Drag-under" feedback and its response to the
DragSource regarding drop eligibility by inspecting the
sources suggested actions, the data types available and the data itself.
A particular DropTargetListener instance may be associated
with a DropTarget via addDropTargetListener
and removed via removeDropTargetListener methods.
public interface java.awt.dnd.DropTargetListener
extends java.util.EventListener {
void dragEnter (DropTargetDragEvent dtde);
void dragOver (DropTargetDragEvent dtde);
void dropActionChanged (DropTargetDragEvent dtde);
void dragExit (DropTargetDragEvent dtde);
void drop (DropTargetDropEvent dtde);
}
The dragEnter method of the DropTargetListener
is invoked when the hotspot of the logical "Drag"
Cursor intersects a visible portion of the DropTarget's
associated Component's geometry. The
DropTargetListener, upon receipt of this notification,
shall interrogate the operations or actions, and the types of the data
(DataFlavors) and the data itself as supplied by the
DragSource to determine the appropriate actions and
"Drag-under" feedback to respond with invocation of either
acceptDrag or rejectDrag.
The dragOver method of the DropTargetListener
is invoked while the hotspot of the logical "Drag" Cursor,
in motion, continues to intersect a visible portion of the
DropTarget's associated Component's geometry.
The DropTargetListener, upon receipt of this notification,
shall interrogate the operation "actions" the types of the
data and the data itself as supplied by the DragSource
to determine the appropriate "actions" and "Drag-under"
feedback to respond with an invocation of either acceptDrag or
rejectDrag.
The dragExit method of the DropTargetListener
is invoked when the hotspot of the logical "Drag" Cursor
ceases to intersect a visible portion of the DropTarget's
associated Component's geometry, or immediately prior to a
drop notification. The DropTargetListener,
upon receipt of this notification, shall undo any "Drag-under"
feedback effects it has previously applied. Note that the
DropTargetContext associated with the DropTarget
is invalidated as a side-effect.
The drop method of the DropTargetListener
is invoked as a result of the user terminating their drag gesture while
intersecting. The DropTargetListener, upon receipt of this
notification, shall perform the operation specified by the return value
of the getSourceActions method on the
DropTargetDropEvent object, upon the Transferable
object returned from the getTransferable method, and
subsequently invoke the dropComplete method of the associated
DropTargetContext to signal the success, or otherwise, of
the operation.
The DropTargetEvent and DropTargetDragEvent are
defined as follows:
public abstract class java.awt.dnd.DropTargetEvent
extends java.util.EventObject {
public DropTargetContext getDropTargetContext();
//...
}
A DropTargetEvent is passed to the
DropTargetListener's dragExit method.
public class java.awt.dnd.DropTargetDragEvent
extends java.awt.dnd.DropTargetEvent {
public Transferable getTransferable();
public Point getLocation();
public int getSourceActions();
public getDropAction();
public DataFlavor[] getCurrentDataFlavors();
public List getCurrentDataFlavorsAsList();
public boolean isDataFlavorSupported();
public void acceptDrag(int operation);
public void rejectDrag();
//...
}
A DropTargetDragEvent is passed to the
DropTargetListener's dragEnter,
dragOver and dropActionChanged methods.
The getLocation method return the current co-ordinates,
relative to the associated Component's origin, of the
hotspot of the logical "Drag" cursor.
The getSourceActions method returns the current
"actions", or operations (ACTION_MOVE, ACTION_COPY, or
ACTION_REFERENCE) the DragSource associates with the
current drag and drop gesture.
The return value of the getDropAction method is the
action that is selected by the user's gesture.
The getCurrentDataFlavors,
getCurrentDataFlavorsAsList and
isDataFlavorSupported methods are provided in order for the
recipient to interrogate the list of types available from the source.
The getTransferable method is provided in order for the
recipient to interrogate the data available from the source. Note that
getTransferable on the DropTargetDragEvent
instance should only be called within the respective
DropTargetListener's method, and all the necessary
data should be retrieved from the returned Transferable
before that method returns.
The DropTargetDropEvent is defined as follows:
public class java.awt.dnd.DropTargetDropEvent
extends java.awt.dnd.DropTargetEvent {
public Point getLocation();
public int getSourceActions();
public int getDropAction();
public void acceptDrop(int dropAction);
public void rejectDrop();
public boolean isLocalTransfer();
public DataFlavor[] getCurrentDataFlavors();
public List getCurrentDataFlavorsAsList();
public boolean isDataFlavorSupported(DataFlavor df);
public Transferable getTransferable();
public void dropComplete(boolean success);
//...
}
A DropTargetDropEvent is passed to the
DropTargetListener's drop method, as the
drop occurs. The DropTargetDropEvent provides the
DropTargetListener with access to the data associated
with the operation, via the Transferable returned from the
getTransferable method.
The return value of the getSourceActions method is defined
to be the action(s) defined by the source at the time at which the
drop occurred.
The return value of the getDropAction method is the
action that is selected by the user's gesture.
The return value of the getLocation method is defined to be
the location at which the drop occurred.
The getCurrentDataFlavors,
getCurrentDataFlavorsAsList, and
isDataFlavorSupported, methods are provided in order for the
recipient to interrogate the list of types available from the source for
subsequent transfer via the getTransferData method of the
Transferable.
A typical implementation of the drop method will inspect
the actions and the DataFlavors' available to determine
if a successful exchange can occur or not.
When an exchange may occur, a DropTargetListener.drop
implementation shall invoke acceptDrop with the selected
operation as an actual parameter, prior to any invocation of
getTransferable. Calling getTransferable prior
to acceptDrop shall result in an
InvalidDnDOperationException.
The rejectDrop shall be called to reject the drop operation.
Once called no further interaction can occur between the two participants,
therefore it is typical to return from the drop method
immediately after calling this.
The isLocalTransfer method shall return true, if the source
of the drag and drop operation resides within the same physical JVM
as the recipient of the drop notification, and false otherwise.
This distinction is significant to the recipient when it receives
object references back from invoking Transferable.getTransferData
in the local case, since in this case the object reference it receives is
the same object reference held by the source (i.e it is not a copy,
proxy or distinct object) thus the recipient must treat such a shared
object reference differently in the local case as follows:
dropCompete
that the transfer is effected. (Note that a source is also prohibited
from modifying the state of such an object after it has returned such an
object from it's getTransferData method, until such time
as it receives a dragDropEnd notification.)
dropComplete and
dragDropEnd methods have been processed. Thereafter the
sharing semantics are implementation dependent upon the object(s) shared.
The dropComplete method signals the end of the associated
drag and drop operation, and indicates the success (or failure) of
the transfers performed by the recipient. Invoking this method results
in the DragSourceListener's dragDropEnd
method being called with the appropriate state available from it's
DragSourceDropEvent. Failure to invoke this method will
result in the drag and drop operation failing to terminate properly.
Many GUI Components present a scrollable
"viewport" over a (potentially) large dataset.
During a drag and drop operation it is desirable to be able to
"autoscroll" such "viewports" to allow
a user to navigate over such a dataset, scrolling to locate a
particular member (initially not visible through the "viewport")
that they wish to drop the subject of the operation upon.
Components that are scrollable provide drag
"autoscrolling" support to their DropTarget
by implementing the following interface:
public interface Autoscroll {
Insets getAutoscrollInsets();
void autoScrollContent(Point cursorLocn);
}
An implementing DropTarget shall periodically call the
autoscroll method of its associated
Component (if present), passing the current logical
cursor location in Component co-ordinates, when the
following conditions are met:
Component's visible geometry and the boundary region
described by the Insets returned by the
getAutoscrollInsets method.
Should any of the above conditions cease to be valid, autoscrolling shall terminate until the next triggering condition occurs.
Both the initial delay prior to autoscrolling commencing, the interval
between autoscrolling notifications, and the pixel hysteresis value are
externally configurable and can be queried from the
Toolkit.getDesktopProperty method.
In the case where a valid drop occurs, the DropTargetListener's
drop method is responsible for undertaking the transfer
of the data associated with the gesture. The DropTargetDropEvent
provides a means to obtain a Transferable object that represent
that data object(s) to be transferred.
From the drop method, the DropTargetListener
shall initially either rejectDrop (immediately returning
thereafter) or acceptDrop specifying the selected operation
from those returned by getSourceActions.
Subsequent to an acceptDrop, but not before,
getTransferable may be invoked, and any data transfers
performed via the returned Transferable's
getTransferData method. Finally, once the destination of
the drop has completed the transfer(s) of the objects from the source
it shall signal the success, or immediate failure, of the transfer(s)
via an invocation of DropTargetContext.dropComplete.
Upon returning from the DropTargetContext.dropComplete
method the Transferable and DragSourceContext
instances are no longer guaranteed to be valid and all references to
them shall be discarded by the recipient to allow them to be subsequently
garbage collected.
When using the ACTION_REFERENCE operation the source and destination
should take care to agree upon the object and the associated semantics
of the transfer. Typically in intra-JVM transfers a live object reference
would be passed between source and destination, but in the case of inter-JVM
transfers, or transfers between native and Java applications, live object
references do not make sense, so some other ‘reference' type should
be exchanged such as a URI for example. Both the DragSource
and DropTarget can detect if the transfer is intra-JVM or not.
All the target DnD platforms represent their transfer data types
using a similar mechanism, however the representations do differ.
The Java platform uses MIME types encapsulated within a DataFlavor
to represent its data types. Unfortunately in order to permit the transfer
of data between Java and platform native applications the existence of these
platform names need to be exposed, thus a mechanism is required in order
to create an extensible (platform independent) mapping between these platform
dependent type names, their representations, and the Java MIME based
DataFlavors.
The implementation will provide a mechanism to externally specify a
mapping between platform native data types (strings) and MIME types
(strings) used to construct DataFlavors. This external
mapping will be used by the underlying platform specific implementation
code in order to expose the appropriate DataFlavors
(MIME types), exported by the source, to the destination, via the
underlying platform DnD mechanisms.
Both the DragSource and DropTarget classes
provide access for the underlying system to map platform dependent names
to and from DataFlavors.
public interface java.awt.datatransfer.FlavorMap {
java.util.Map getNativesForFlavors(DataFlavor[] dfs);
java.util.Map getFlavorsForNatives(String[] natives);
}
The getNativesForFlavors method takes an array of
DataFlavors and returns a Map object
containing zero or more keys of type DataFlavor,
from the actual parameter dfs, with associated values
of type String, which correspond to the platform-dependent
type name for that MIME type.
The getFlavorsForNatives method takes an array of
String types and returns a Map object
containing zero or more keys of type String, from the
actual parameter natives, with associated values of type
DataFlavor, which correspond to the platform-independent
type for that platform-dependent type name.
The Map object returned by both methods may be mutable
but is not required to be.
If NULL is passed to either of these methods they should return their current map of all keys and values known to the implementation at the time of the call.
For example on Win32 the Clipboard Format Name for simple text is
"CF_TEXT" (actually it is the integer 1) and on Motif it is the X11 Atom
named "STRING", the MIME type one may use to represent this would be
"text/plain;charset=us-ascii". Therefore a platform portable
FlavorMap would map between these names; CF_TEXT on win32
and STRING on Motif/X11.
Typically, as implemented in the SystemFlavorMap
these mappings are held in an external persistent configuration
format (a properties file or URL) and are loaded from the platform
to configure the FlavorMap appropriately for a given platform.
The SystemFlavorMap class is provided to implement a
simple, platform configurable mechanism for specifying a system-wide
set of common mappings, and is defined as follows:
public class java.awt.datatransfer.SystemFlavorMap implements FlavorMap, FlavorTable {
public static FlavorMap getSystemFlavorMap();
public synchronized Map getNativesForFlavors(DataFlavor[] dfs);
public synchronized Map getFlavorsForNatives(String[] natives);
public static String encodeDataFlavor(DataFlavor flav);
public static String encodeJavaMIMEType(String mimeType);
public static boolean isJavaMIMEType(String mimeStr);
public static String decodeJavaMIMEType(String nat);
public static DataFlavor decodeDataFlavor(String nat);
//...
}
The SystemFlavorMap class provides a simple implementation,
using a properties file (see java.awt.Properties),
of a persistent platform FlavorMap. Using the value of the
AWT property "AWT.flavorMapFileURL" (see Toolkit.getProperty)
or the default file location of
System.getProperty("java.home")
+ File.separator + "lib" + File.separator + "flavormap.properties",
this class creates the appropriate Maps from the
properties found therein.
In addition the class provides several static convenience functions
used to encode and decode Java MimeTypes to and from a
platform dependent namespace. The syntax of the properties file is:
{ <platform_type_name> ‘=' <IETF_MIME_RFC_conformant_specification> <nl> } *
The default implementations of DragSource and
DropTarget return the SystemFlavorMap
from their getFlavorMap method, unless they have been
provided with an overriding implementation.
Since one of the primary goals of this API is to allow drag and drop of data between Java and native applications this has some significant consequences upon the method and mechanism of the actual data encoding and exchange when data is passed across the boundary of the Java Virtual Machine.
Since one of the participants in such an exchange may be a native application, and thus has no knowledge of the Java type system, the drag and drop system cannot just exchange a Java object reference since the other participant may have no knowledge of, or capability to manipulate such a type.
When any exchange occurs, it can only do so, regardless of the implementation of the participants, if and only if both participants are agreed upon a familiar data type and encoding. Thus, sadly the burden of the exchange is born mostly by the participants themselves.
What this means in practical terms is that for "native" data formats, such as platform-dependent image, document, or other "Content-Types" the encoding and decoding of their associated external data format is the responsibility of the source and destination of the transfer.
The drag and drop system shall expose the external representation of
such "native" data types across the boundary of the Java Virtual Machine
as encapsulated within a java.io.InputStream or a subclass thereof.
This means that any DataFlavor with a representation class
that extends java.io.InputStream can be transferred,
and will be exposed for transfer, across the Java Virtual Machine boundary.
To implement the exchange of such a native data type, a developer
would define a DataFlavor with a MIME "Content-Type"
that describes the nature of the "native" data type, with a representation
class that extends a java.io.InputStream class that encodes
the data encapsulated into a stream of bytes.
In particular such InputStream subclasses shall implement
the following semantics:
java.io.InputStream.
Provision of this constructor by a subclass of
java.io.InputStream will allow the drag and drop system
(associated with the DropTarget) to automatically
re-construct an instance of the representation class specified by
the requested DataFlavor, and initialize it with an
InputStream containing the encapsulated data formatted
according to the expectations of that subclass. Once initialized this
instance is returned to the caller of the
Transferable.getTransferData method, thus allowing the
caller to subsequently re-read and interpret the formatted content
of the data stream transferred.
InputStream.read(byte b[], int off, int len).
Provision of this method (or inheriting a superclasses implementation)
enables the drag and drop system (associated with the
DragSource) to automatically extract an encoded stream
of the encapsulated data from the Transferable,
thus enabling the transfer of the data across the JVM boundary
as a simple byte stream to the requestor of the particular
DataFlavor.
A typical subject of a Drag and Drop transfer is a list of one or more platform dependent filenames. In order to ease the programming task of developers either producing or consuming such lists the drag and drop system treats them as a special case.
If a DataFlavor is specified with a MIME "Content-Type"
of application/x-java-file-list;class=java.util.List
the drag and drop system will expect the list elements to be a
homogeneous list of objects of type java.io.File.
Thus a source shall, if supporting the transfer of a list of files,
construct such a List of File objects when
such a DataFlavor is requested, and a recipient shall
expect such a List of File objects if it
requests such a valid DataFlavor from its source.
This special case provides a simple mechanism for the transfer of
lists of files between source and target.
It is possible to Drag and Drop object references between JVMs' by using the facilities of the RMI mechanism. The Drag and Drop system will automatically arrange for the transfer of any object reference that adheres to these requirements:
DataFlavor implements both
java.rmi.Remote and java.io.Serializable.
(the MIME "Content-Type" can be any suitable, arbitrary type or application/x-java-remote-object)
(effectively the object implementation class transferred should
be extended from java.rmi.server.UnicastRemoteObject
since the RMI system implements some required initialization,
without which the transfer will not complete properly).
If these conditions are met, then if an appropriate
DataFlavor is requested, then the object returned
to the requestor (if it is in a difference JVM from the source)
will be an RMI reference to an instance of the Remote
object subinterface specified as the representation class of the
DataFlavor.
Due to limitations of particular underlying platform drag and drop and
window system implementations, the interaction of a drag operation,
and the event delivery semantics to AWT Components is
platform dependent. Therefore during a drag operation a DragSource
may process platform Window System Events pertaining to that drag to the
exclusion of normal event processing.
Due to interactions between the single-threaded design center of the
platform native DnD systems, and the native window system event dispatching
implementations in AWT, "callbacks" into
DropTargetListener and DragSourceListener
will occur either on, or synchronized with the AWT system event dispatch
thread. This behavior is highly undesirable for security reasons but is an
implementation, not architectural feature, and is unavoidable.
To enable intra-JVM Drag and Drop Transfers the existing
DataFlavor class will be extended to enable it to represent
the type of a "live" object reference, as opposed to a
Serialized (persistent) representation of one. Such objects may be
transferred between source and destination within the same JVM and
ClassLoader context.
The MIME Content-Type shall be application/x-java-local-objectref.
Transferable objects, their associated
DataFlavors', and the objects that encapsulate the
underlying data specified as the operand(s) of a drag and drop
operation shall remain valid until, at least, the
DragSourceListener associated with the DragSource
controlling the operation, receives a dragDropEnd.
The lifetime of the subject(s) of the operation, transferred between source
and target is implementation defined beyond that point in time.
The "source" of a successful Drag and Drop (ACTION_MOVE)
operation is required to delete/relinquish all references to the object(s)
that are the subject of the Transferable immediately after
transfer has been successfully completed. That is before returning from the
DragSourceListener.dragDropEnd notification.
As a result of significant input from developers to an earlier version of the specification an additional operation/action tag; ACTION_REFERENCE was added to include existing platform Drag and Drop"Link" semantics.
It is believed that Reference, or Link, semantics are already sufficiently poorly specified for the platform native Drag and Drop to render it essentially useless even between native applications, thus between native and platform independent Java applications it is not recommended.
For Java to Java usage the required semantic; within the same
JVM/ClassLoader, is defined such that the destination
shall obtain a Java object reference to the subject(s) of the transfer.
Between Java JVM's or ClassLoaders, the semantic is
implementation defined, but could be implemented through transferring
either a URL from the source to the destination or an RMI
Remote reference.
Although not a normative part of this specification this definition is included for clarity:
public interface DropTargetPeer {
void addDropTarget(DropTarget dt);
void removeDropTarget(DropTarget dt);
}
Although not a normative part of this specification this definition is included for clarity:
public interface DragSourceContextPeer {
void startDrag(DragSourceContext dsc,
Cursor c,
Image di,
Point ioff
) throws InvalidDnDOperationException;
Cursor getCursor();
void setCursor(Cursor c) throws InvalidDnDOperationException;
void transferablesFlavorsChanged();
}
Although not a normative part of this specification this definition is included for clarity:
public interface DropTargetContextPeer {
int getTargetActions();
void setTargetActions(int actions);
DropTarget getDropTarget();
DataFlavor[] getTransferDataFlavors();
Transferable getTransferable() throws InvalidDnDOperationException;
boolean isTransferableJVMLocal();
void acceptDrag(int dragAction);
void rejectDrag();
void acceptDrop(int dropAction);
void rejectDrop();
void dropComplete(boolean success);
}