Chapter 12. The java.awt.dnd Package

Autoscroll	Java 1.2
java.awt.dnd

This interface allows a scrollable component to scroll itself as part of the drag-and-drop process, so that a user can drop an object anywhere within the component's scrollable content. Consider, for example, the problem of cutting a paragraph of text from the top of a long document and dragging it down to the bottom of the same document. While the drag-and-drop operation is in progress, the user obviously cannot operate the scrollbar, since the mouse is already in use. So some other technique is necessary to enable scrolling during a drag-and-drop operation.

The Autoscroll interface enables this specialized form of scrolling. When an object is first dragged over a component that implements Autoscroll, the drag-and-drop system calls the component's getAutoscrollInsets() method. This defines an autoscroll region at the edges of the component. If, during the drag, the user places the mouse within this autoscroll region and holds it there (for a platform-dependent amount of time), the drag-and-drop system begins to call the autoscroll() method repeatedly (at a platform-dependent repetition rate) until the user once again moves the mouse. The autoscroll() method of the component is responsible for scrolling the content. The direction of the scroll is determined by the position of the mouse pointer, which is passed as an argument to autoscroll().

DnDConstants	Java 1.2
java.awt.dnd

Successful completion of a drag-and-drop operation can result in a number of different types of actions being performed. This interface defines constants that represent the possible actions:

ACTION_COPY

This is the most common action: the dragged object is to be copied in some way. ACTION_COPY is also used as a default action when there is only one possible action, even if that action is not really a copy.

ACTION_MOVE

The dragged object is to be copied by the destination. The source object deletes its copy after the object is successfully transferred.

ACTION_COPY_OR_MOVE

This constant is the combination of ACTION_COPY and ACTION_MOVE. Many drop targets can accept drops of either type; this constant is used to indicate that fact.

ACTION_LINK or ACTION_REFERENCE

These two constants are synonyms. They indicate that the destination object should create a link to the transferred object or share a reference to the transferred object with the source object. Note that this action has a particularly vague meaning; its use is not recommended except for intra-application drag-and-drop of specialized data types.

ACTION_NONE

This constant specifies that no actions are supported. It is used internally by the drag-and-drop API but is not commonly used by application-level code.

DragGestureEvent	Java 1.2
java.awt.dnd	serializable event

This event type is fired by a DragGestureRecognizer and sent to the dragGestureRecognized() method of a DragGestureListener. Unlike many event classes, which are merely holders of event information, DragGestureEvent also defines the startDrag() method, which can be used to initiate the drag-and-drop process.

When the dragGestureRecognized() method is invoked, it should start the drag-and-drop process by invoking this startDrag() method, passing in the initial drag cursor to display, the Transferable data to transfer, and the DragSourceListener that monitors the drag process. If there is to be an image dragged along with the drag cursor, the image and its offset from the cursor hotspot may also be passed to startDrag().

The other methods of DragGestureEvent() are accessor methods that return information about the event. Most applications do not need to call them.

Hierarchy: Object-->java.util.EventObject(Serializable)-->DragGestureEvent

Passed To: Toolkit.createDragSourceContextPeer(), DragGestureListener.dragGestureRecognized(), DragSource.{createDragSourceContext(), startDrag()}, DragSourceContext.DragSourceContext()

Returned By: DragSourceContext.getTrigger()

DragGestureListener	Java 1.2
java.awt.dnd	event listener

This interface defines the method that is invoked by a DragGestureRecognizer when the user initiates a drag-and-drop action. When dragGestureRecognized() is called, the DragGestureListener should prepare a Transferable object to be transferred through the drag-and-drop process and then initiate that process by calling the startDrag() method of the DragGestureEvent object.

You do not typically pass a DragGestureListener to an addDragGestureListener() method. Instead, you specify the DragGestureListener when you call the createDefaultDragGestureRecognizer() method of a DragSource object. This method creates a DragGestureRecognizer and automatically registers the DragGestureListener with it.

Hierarchy: (DragGestureListener(java.util.EventListener))

Passed To: Toolkit.createDragGestureRecognizer(), DragGestureRecognizer.{addDragGestureListener(), DragGestureRecognizer(), removeDragGestureListener()}, DragSource.{createDefaultDragGestureRecognizer(), createDragGestureRecognizer()}, MouseDragGestureRecognizer.MouseDragGestureRecognizer()

Type Of: DragGestureRecognizer.dragGestureListener

DragGestureRecognizer	Java 1.2
java.awt.dnd

Drag-and-drop operations may be initiated in different ways on different native platforms. This abstract class is the superclass of the platform-dependent classes that are used to recognize the platform-dependent gesture used to begin a drag. As an abstract class, you cannot instantiate a DragGestureRecognizer directly. Instead, you typically create a DragGestureRecognizer by calling the createDefaultDragGestureRecognizer() method of a DragSource object. If you want to allow the user to initiate drags with nonstandard gestures, you may implement your own DragGestureRecognizer subclass and instantiate it by calling the createDragGestureRecognizer() method of java.awt.Toolkit.

When you create a DragGestureRecognizer, you specify the Component it is to look for drag gestures over and the DragGestureListener it is to notify when it recognizes one. The creation process automatically links these three objects together, so you typically never need to do anything with a DragGestureRecognizer other than create it.

One additional piece of information you must supply when you create a DragGestureRecognizer is a bit mask of allowed drag actions. ACTION_COPY, ACTION_MOVE, and ACTION_LINK actions are usually initiated with different gestures (different modifier keys). A DragGestureRecognizer must know which actions are available so it can know which gestures to recognize and which to ignore.

Subclasses: MouseDragGestureRecognizer

Passed To: DragGestureEvent.DragGestureEvent()

Returned By: Toolkit.createDragGestureRecognizer(), DragGestureEvent.getSourceAsDragGestureRecognizer(), DragSource.{createDefaultDragGestureRecognizer(), createDragGestureRecognizer()}

DragSource	Java 1.2
java.awt.dnd

This class coordinates the initiation of drag-and-drop operations. Despite the central role it plays in the drag-and-drop system, it is not used much in typical drag-and-drop code.

You can create a DragSource object by calling the constructor, but because the DragSource object does not hold any state, you can continually reuse a single object. Call the static getDefaultDragSource() method to obtain a reference to a shared default DragSource object.

Once you have obtained a DragSource object, call createDefaultDragGestureRecognizer() to create and register a DragGestureRecognizer object that detects user gestures that should initiate drags. If you want to drag an image that represents the dragged data along with the drag cursor, you may also call the isDragImageSupported() method to find out whether that option is supported on the native platform.

After you have called these two methods, you typically never need to use the DragSource again. The startDrag() method of the DragSource is responsible for initiating a drag action, but it is easier to invoke it through the startDrag() utility method of the DragGestureEvent class instead.

Passed To: Toolkit.createDragGestureRecognizer(), DragGestureRecognizer.DragGestureRecognizer(), MouseDragGestureRecognizer.MouseDragGestureRecognizer()

Returned By: DragGestureEvent.getDragSource(), DragGestureRecognizer.getDragSource(), DragSource.getDefaultDragSource(), DragSourceContext.getDragSource()

Type Of: DragGestureRecognizer.dragSource

DragSourceContext	Java 1.2
java.awt.dnd

This class contains state information about a drag operation currently in progress. It is the DragSourceContext that is responsible for communicating with the native drag-and-drop system of the underlying platform and relaying drag-and-drop events to the DragSourceListener. Although this is an important class, it does its work in the background, and you typically do not need to use it. If you do want to use it, for example, to perform cursor animation with the setCursor() method, you may obtain the current DragSourceContext from any DragSourceEvent object.

Hierarchy: Object-->DragSourceContext(DragSourceListener(java.util.EventListener))

Passed To: DragSourceDragEvent.DragSourceDragEvent(), DragSourceDropEvent.DragSourceDropEvent(), DragSourceEvent.DragSourceEvent(), java.awt.dnd.peer.DragSourceContextPeer.startDrag()

Returned By: DragSource.createDragSourceContext(), DragSourceEvent.getDragSourceContext()

DragSourceDragEvent	Java 1.2
java.awt.dnd	serializable event

This event type is fired by a DragSourceContext and passed to the dragEnter(), dragOver(), dragExit(), and dragActionChanged() methods of a DragSourceListener. These methods may use the notification as an opportunity to perform drag-over animation effects, by changing the cursor, for example.

isLocalDropTarget() specifies whether the drop target currently under the cursor is in the same Java VM as the drag source. getUserAction() returns the current drag action selected by the user. This is usually a function of the modifier keys the user is holding down; these modifiers are available from getGestureModifiers(). getTargetActions() returns a bit mask of the actions that the drop target can support, and getDropAction() is the intersection of the user action with the set of target actions.

Hierarchy: Object-->java.util.EventObject(Serializable)-->DragSourceEvent-->DragSourceDragEvent

Passed To: DragSourceContext.{dragEnter(), dragOver(), dropActionChanged()}, DragSourceListener.{dragEnter(), dragOver(), dropActionChanged()}

DragSourceDropEvent	Java 1.2
java.awt.dnd	serializable event

This event type is fired by the DragSourceContext and is passed to the dragDropEnd() method of a DragSourceListener to signify that the drag-and-drop operation is complete. getDropSuccess() returns true if the drop occurs and the data is successfully transferred. It returns false if the drag is cancelled, if the drop is performed over an invalid drop target, or if the data transfer is not successful. getDropAction() returns the action (see DnDConstants) that is actually performed. The user's selected action may change during the drag, so this value may not be the same as the initially selected action.

Hierarchy: Object-->java.util.EventObject(Serializable)-->DragSourceEvent-->DragSourceDropEvent

Passed To: DragSourceContext.dragDropEnd(), DragSourceListener.dragDropEnd()

DragSourceEvent	Java 1.2
java.awt.dnd	serializable event

This class is the superclass of event types fired by a DragSourceContext to notify a DragSourceListener about events in the drag-and-drop process. Although applications typically do not need to do so, they can call getDragSourceContext() or getSource() to obtain a reference to the current DragSourceContext. This object can be used, for example, to perform drag over animation effects by changing the current drag cursor. If you are writing a DragSourceListener that handles drags on more than one component, you can determine which component initiated the drag by calling getSource() to obtain a DragSourceContext and then calling its getComponent() method.

See also DragSourceDragEvent and DragSourceDropEvent.

Hierarchy: Object-->java.util.EventObject(Serializable)-->DragSourceEvent

Subclasses: DragSourceDragEvent, DragSourceDropEvent

Passed To: DragSourceContext.dragExit(), DragSourceListener.dragExit()

DragSourceListener	Java 1.2
java.awt.dnd	event listener

This interface is implemented by objects that allow data to be transferred through drag-and-drop and want to be notified about the progress of the drag-and-drop process. The methods of this interface are invoked by a DragSourceContext at various interesting points during the drag-and-drop. The methods are passed a DragSourceDragEvent or a DragSourceDropEvent, both of which are subclasses of DragSourceEvent. The methods are:

dragDropEnd()

Invoked when the drag-and-drop operation is complete and has ended in success or failure. This is the only method that is passed a DragSourceDropEvent, instead of a DragSourceDragEvent. If the drag is of type ACTION_MOVE and the getDropSuccess() method of DragSourceDropEvent returns true, the DragSourceListener knows that the data has been safely transferred to the drop target and should delete the source copy of that data.

dragEnter()

Called when the drag cursor has entered an active drop target that has indicated an interest in and capability to receive a drop. This method should initiate any custom drag over effects.

dragExit()

Invoked when the drag cursor has left a receptive drop target. This method should terminate any custom drag over effects.

dragOver()

Called continuously while the mouse remains within a receptive drop target. Because this method is called very frequently, it should not perform any lengthy operations.

dropActionChanged()

Invoked if the user changes his desired drop action, typically by changing the keyboard modifiers she is holding down. If you are displaying a custom drag cursor, this method may need to modify the currently displayed cursor.

Hierarchy: (DragSourceListener(java.util.EventListener))

Implementations: DragSourceContext

Passed To: DragGestureEvent.startDrag(), DragSource.{createDragSourceContext(), startDrag()}, DragSourceContext.{addDragSourceListener(), DragSourceContext(), removeDragSourceListener()}

DropTarget	Java 1.2
java.awt.dnd	serializable

This class holds the state necessary for a Component to accept drops. Create a DropTarget by specifying the Component with which it is to be associated and the DropTargetListener that responds to interesting events during a drag-and-drop operation. You may optionally specify a bit mask of drop actions that this DropTarget can support and a boolean value that indicates whether the DropTarget is currently active. If you do not specify these optional values, your DropTarget supports ACTION_COPY_OR_MOVE and is active.

Once you have created a DropTarget, you often never have to do anything else with it. The DropTarget() constructor automatically connects the DropTarget with the Component it serves and the DropTargetListener it notifies, so you do not have to perform any of the registration yourself. In fact, the only time you typically need to use the DropTarget object you create is if you need to activate or deactivate it with setActive().

Hierarchy: Object-->DropTarget(DropTargetListener(java.util.EventListener),Serializable)

Passed To: Component.setDropTarget(), java.awt.dnd.peer.DropTargetPeer.{addDropTarget(), removeDropTarget()}

Returned By: Component.getDropTarget(), DropTargetContext.getDropTarget(), java.awt.dnd.peer.DropTargetContextPeer.getDropTarget()

DropTarget.DropTargetAutoScroller	Java 1.2
java.awt.dnd

This protected inner class implements autoscrolling behavior for a drop target. If the drop target is associated with a component that implements Autoscroll, this class invokes the autoscroll() method of that component as appropriate. Applications never need to use this class directly. Applications that want to override the default autoscrolling behavior can subclass this class and override the createDropTargetAutoScroller() method of DropTarget to return an instance of the subclass.

Returned By: DropTarget.createDropTargetAutoScroller()

DropTargetContext	Java 1.2
java.awt.dnd

This class contains state information about a drag operation currently in progress above a DropTarget. The DropTargetContext is responsible for communicating with the native drag-and-drop system of the underlying platform and relaying drag-and-drop events from that native system to the DropTargetListener.

Although this is an important class, it does its work internally, and application-level code does not typically need to use it. DropTargetContext does define some important methods, such as acceptDrag() and acceptDrop(), but these are typically invoked through the utility methods of DropTargetDragEvent and DropTargetDropEvent. If you ever do need to use a DropTargetContext directly, it is available from any DropTargetEvent.

Passed To: DropTargetDragEvent.DropTargetDragEvent(), DropTargetDropEvent.DropTargetDropEvent(), DropTargetEvent.DropTargetEvent()

Returned By: DropTarget.{createDropTargetContext(), getDropTargetContext()}, DropTargetEvent.getDropTargetContext()

Type Of: DropTargetEvent.context

DropTargetContext.TransferableProxy	Java 1.2
java.awt.dnd

This protected inner class is used by the protected createTransferableProxy() method of DropTargetContext. Applications never need to use this class. This class is not defined by the JFC drag-and-drop specification and its inclusion in the public API of java.awt.dnd was probably unintentional.

DropTargetDragEvent	Java 1.2
java.awt.dnd	serializable event

This event is fired by a DropTargetContext and passed to the dragEnter(), dragOver(), and dropActionChanged() methods of a DropTargetListener. Each of these methods should use getDropAction(), getCurrentDataFlavors(), and related methods to check whether the drop target knows how to handle the drag action and is able to interpret the data formats offered. If so, the method should call acceptDrag(). If not, it should call rejectDrag(). See DropTargetListener for further details.

Hierarchy: Object-->java.util.EventObject(Serializable)-->DropTargetEvent-->DropTargetDragEvent

Passed To: DropTarget.{dragEnter(), dragOver(), dropActionChanged()}, DropTargetListener.{dragEnter(), dragOver(), dropActionChanged()}

DropTargetDropEvent	Java 1.2
java.awt.dnd	serializable event

This event is fired by a DropTargetContext and delivered to the drop() method of a DropTargetListener. This method should call getDropAction() to ensure that it is able to perform the requested action. It should also call getCurrentDataFlavors() or isDataFlavorSupported() to ensure that it can interpret the data that is transferred. If it cannot perform the action or interpret the data, it should call rejectDrag() and return.

If the DropTargetListener can perform the action and interpret the data, it should accept the drop. It does this in a four-step process. First, it calls acceptDrop() to signal that it accepts the drop. Second, it calls getTransferable() to obtain a java.awt.datatransfer.Transferable object. Third, it calls the getTransferData() method of Transferable to actually transfer the data.

Finally, if the data transfer fails for any reason, the DropTargetListener should pass false to the dropComplete() method of the DropTargetDropEvent, indicating that the drop action is complete but that it was not successful. If the data transfer is successful and the data has been safely and completely transferred, the drop() method should pass true to the dropComplete() method. This notifies the system that the data has been successfully transferred. The notification is passed on to the DragSourceListener, which can then complete its part of the action. For example, if the action is ACTION_MOVE, the DragSourceListener deletes its copy of the data once it receives notification that the DropTargetListener has successfully copied it.

Hierarchy: Object-->java.util.EventObject(Serializable)-->DropTargetEvent-->DropTargetDropEvent

Passed To: DropTarget.drop(), DropTargetListener.drop()

DropTargetEvent	Java 1.2
java.awt.dnd	serializable event

This class is the superclass of both DropTargetDragEvent and DropTargetDropEvent. getDropTargetContext() returns the DropTargetContext object that generated the event, and getSource() returns the corresponding DropTarget object. Applications rarely need to use these methods, however.

Hierarchy: Object-->java.util.EventObject(Serializable)-->DropTargetEvent

Subclasses: DropTargetDragEvent, DropTargetDropEvent

Passed To: DropTarget.dragExit(), DropTargetListener.dragExit()

DropTargetListener	Java 1.2
java.awt.dnd	event listener

This interface is implemented by objects that want to be able to receive dropped data. Its methods are invoked by a DropTargetContext at various interesting points in the drag-and-drop process. The methods of this interface are passed a DropTargetEvent or one of its subclasses, a DropTargetDragEvent or a DropTargetDropEvent. The methods are:

dragEnter()

Invoked when a drag enters the Component associated with the DropTargetListener. This method should call getDropAction() to determine whether it can perform the requested action and either getCurrentDataFlavors() or isDataFlavorSupported() to determine whether it can interpret the data that is being offered. If so, it should call the acceptDrag() method of the event object. If not, it should call the rejectDrag() method.

If this method accepts the drag, it may also perform or initiate custom graphical drag under effects on the associated Component. These effects provide feedback to the user that the drop target Component is interested in receiving the drop.

dragExit()

Called when a previously accepted drag leaves the DropTarget. If the dragEnter() method performed any custom drag under effects, this method should undo them.

dragOver()

Invoked continuously while the mouse pointer remains over the DragTarget. In most cases, this method need not do anything. If the DropTarget is a complex one that is capable of accepting drags in some regions but not in other regions, this method should behave like dragEnter() and call the acceptDrag() or rejectDrag() methods of the event object to inform the system whether a drag is possible at the current location. In this case, this method is also responsible for any custom drag under graphical effects.

drop()

Called when data is dropped over the DropTarget. This method should determine whether the DropTarget can accept the drop and call the acceptDrop() or rejectDrop() method of the DropTargetDropEvent event object. If it accepts the drop, it must then transfer the data, perform the requested action, and call dropComplete(). See DropTargetDropEvent for details on this process. This method need not undo your drag under effects; the dragExit() method is invoked for this purpose.

dropActionChanged()

Invoked when the user changes the requested action in mid-drag. This typically occurs if the user changes the modifier keys currently held down. This method should behave like dragEnter() to evaluate whether the drop target can perform the requested action on the offered data and then call acceptDrag() or rejectDrag() and begin or end custom drag under effects, as appropriate.

Hierarchy: (DropTargetListener(java.util.EventListener))

Implementations: DropTarget

Passed To: DropTarget.{addDropTargetListener(), DropTarget(), removeDropTargetListener()}

InvalidDnDOperationException	Java 1.2
java.awt.dnd	serializable unchecked

Signals that a misconfiguration or error of some sort prevents a drag-and-drop operation from completing normally. This exception is thrown by methods throughout the java.awt.dnd package.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->RuntimeException-->java.lang.IllegalStateException-->InvalidDnDOperationException

Thrown By: Toolkit.createDragSourceContextPeer(), DragGestureEvent.startDrag(), DragSource.startDrag(), DropTargetContext.{dropComplete(), getTransferable()}, java.awt.dnd.peer.DragSourceContextPeer.{setCursor(), startDrag()}, java.awt.dnd.peer.DropTargetContextPeer.getTransferable()

MouseDragGestureRecognizer	Java 1.2
java.awt.dnd

This class is a DragGestureRecognizer that is designed to recognize mouse gestures (as opposed, for example, to keyboard gestures). Like DragGestureRecognizer, this is an abstract class and cannot be instantiated. The createDefaultDragGestureRecognizer() method of DragSource returns a platform-specific concrete subclass of this class. Most applications do not need to use this class. Applications that want to support custom drag-and-drop gestures may find it convenient to subclass this class.

Hierarchy: Object-->DragGestureRecognizer-->MouseDragGestureRecognizer(java.awt.event.MouseListener(java.util.EventListener),java.awt.event.MouseMotionListener(java.util.EventListener))