java.awt.dnd Documentation Differences

This file contains all the changes in documentation in the package java.awt.dnd as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

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. @version 1.610 02/02/00 @since JDK11.2

This class contains constant values representing the type of action(s) to be performed by a Drag and Drop operation. @version 1.1216 02/02/00 @since JDK11.2

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. @version 1.1315 @see java.awt.dnd.DragGestureRecognizer @see java.awt.dnd.DragGestureListener @see java.awt.dnd.DragSource

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 is obtained from the DragSource asssociated 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 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).

@author Laurence P. G. Cable @version 1.1113 @see java.awt.dnd.DragGestureListener @see java.awt.dnd.DragGestureEvent @see java.awt.dnd.DragSource

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. @version 1.2630 02/02/00 @since JDK11.2

The DragSourceContext class is responsible for managing the initiator side of the Drag and Drop protocol. In particular it is responsible for managing event notifications to the DragSourceListener and providing the Transferable state to enable the data transfer.

An instance of this class is created as a result of a DragSource's startDrag() method being successfully invoked. This instance is responsible for tracking the state of the operation on behalf of the DragSource and dispatching state changes to the DragSourceListener.

Note that the DragSourceContext itself implements the DragSourceListener interface. This is to allow the platform peer (the DragSourceContextPeer instance) created by the DragSource to notify the DragSourceContext of changes in state in the ongiong operation. This allows the DragSourceContext to interpose itself between the platform and the DragSourceListener provided by the initiator of the operation. @version 1.3539 02/02/00 @since JDK11.2

The DragSourceDragEvent is delivered from the DragSourceContextPeer via the DragSourceContext to the currently registered DragSourceListener. It contains state regarding the current state of the operation to enable the operations initiator to provide the end user with the appropriate drag over feedback. @version 1.1620 02/02/00 @since JDK11.2

The DragSourceDropEvent is delivered from the DragSourceContextPeer via the DragSourceContext to its currently registered DragSourceListener's dragDropEnd() method. It contains sufficient information for the originator of the operation to provide appropriate feedback to the end user when the operation completes.

@version 1.812 02/02/00

@since JDK11.2

This class is the base class for DragSourceDragEvent and DragSourceDropEvent. @since JDK11.2

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. @version 1.1115 02/02/00 @since JDK11.2

The DropTarget is associated with a Component when that Component wishes to accept drops during Drag and Drop operations. @version 1.2934 02/02/00 @since JDK11.2

Construct a DropTarget given the Component to associate itself with and the DropTargetListener to handle event processing.

The Component will receive drops only if it is enabled. @param c The Component with which this DropTarget is associated @param dtl The DropTargetListener for this DropTarget

Construct a DropTarget given the Component to associate itself with an int representing the default acceptable action(s) to support and a DropTargetListener to handle event processing.

The Component will receive drops only if it is enabled. @param c The Component with which this DropTarget is associated @param ops The default acceptable actions for this DropTarget @param dtl The DropTargetListener for this DropTarget

Construct a DropTarget given the Component to associate itself with an int representing the default acceptable action(s) to support a DropTargetListener to handle event processing and a boolean indicating if the DropTarget is currently accepting drops.

The Component will receive drops only if it is enabled. @param c The Component with which this DropTarget is associated @param ops The default acceptable actions for this DropTarget @param dtl The DropTargetListener for this DropTarget @param act Is the DropTarget accepting drops.

Construct a new DropTarget given the Component to associate itself with an int representing the default acceptable action(s) to support a DropTargetListener to handle event processing a boolean indicating if the DropTarget is currently accepting drops and a FlavorMap to use (or null).

The Component will receive drops only if it is enabled. @param c The Component with which this DropTarget is associated @param ops The default acceptable actions for this DropTarget @param dtl The DropTargetListener for this DropTarget @param act Is the DropTarget accepting drops. @param fm The FlavorMap to use or null

Note: this interface is required to permit the safe association of a DropTarget with a Component in one of two ways either: component.setDropTarget(droptarget); or droptarget.setComponent(component);

The Component will receive drops only if it is enabled. @param c The new Component this DropTarget is to be associated with.

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. @version 1.828 02/02/00 @since JDK11.2

The DropTargetDragEvent is delivered to a DropTargetListener via its dragEnter() and dragOver() methods. @version 1.1216 02/02/00 @since JDK11.2

The DropTargetDropEvent is delivered via the DropTargetListener drop() method. @version 1.1721 02/02/00 @since JDK11.2

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. @version 1.1014 02/02/00 @since JDK11.2

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. @version 1.1216 02/02/00 @since JDK11.2

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 undrelying DnD system is not in the appropriate state. @version 1.59 02/02/00 @since JDK11.2

This abstract subclass of DragGestureRecognizer defines a DragGestureRecognizer for mouse based gestures. Each platform will implement 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. @author Laurence P. G. Cable @version 1.79 @see java.awt.dnd.DragGestureListener @see java.awt.dnd.DragGestureEvent @see java.awt.dnd.DragSource