Class DragSourceContext
- All Implemented Interfaces:
DragSourceListener,DragSourceMotionListener,Serializable,EventListener
DragSourceContext class is responsible for managing the
initiator side of the Drag and Drop protocol. In particular, it is responsible
for managing drag event notifications to the
DragSourceListeners
and DragSourceMotionListeners, and providing the
Transferable representing the source data for the drag operation.
Note that the DragSourceContext itself
implements the DragSourceListener and
DragSourceMotionListener interfaces.
This is to allow the platform peer
(the DragSourceContextPeer instance)
created by the DragSource to notify
the DragSourceContext of
state changes in the ongoing operation. This allows the
DragSourceContext object to interpose
itself between the platform and the
listeners provided by the initiator of the drag operation.
By default, DragSourceContext sets the cursor as appropriate
for the current state of the drag and drop operation. For example, if
the user has chosen the move action,
and the pointer is over a target that accepts
the move action, the default move cursor is shown. When
the pointer is over an area that does not accept the transfer,
the default "no drop" cursor is shown.
This default handling mechanism is disabled when a custom cursor is set
by the setCursor(java.awt.Cursor) method. When the default handling is disabled,
it becomes the responsibility
of the developer to keep the cursor up to date, by listening
to the DragSource events and calling the setCursor() method.
Alternatively, you can provide custom cursor behavior by providing
custom implementations of the DragSource
and the DragSourceContext classes.
- Since:
- 1.2
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected static final intAnintused by updateCurrentCursor() indicating that the user operation has changed.protected static final intAnintused by updateCurrentCursor() indicating that theCursorshould change to the default (no drop)Cursor.protected static final intAnintused by updateCurrentCursor() indicating that theCursorhas entered aDropTarget.protected static final intAnintused by updateCurrentCursor() indicating that theCursoris over aDropTarget. -
Constructor Summary
ConstructorsConstructorDescriptionDragSourceContext(DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point offset, Transferable t, DragSourceListener dsl) Called fromDragSource, this constructor creates a newDragSourceContextgiven theDragSourceContextPeerfor this Drag, theDragGestureEventthat triggered the Drag, the initialCursorto use for the Drag, an (optional)Imageto display while the Drag is taking place, the offset of theImageorigin from the hotspot at the instant of the triggering event, theTransferablesubject data, and theDragSourceListenerto use during the Drag and Drop operation. -
Method Summary
Modifier and TypeMethodDescriptionvoidAdd aDragSourceListenerto thisDragSourceContextif one has not already been added.voidCallsdragDropEndon theDragSourceListeners registered with thisDragSourceContextand with the associatedDragSource, and passes them the specifiedDragSourceDropEvent.voiddragEnter(DragSourceDragEvent dsde) CallsdragEnteron theDragSourceListeners registered with thisDragSourceContextand with the associatedDragSource, and passes them the specifiedDragSourceDragEvent.voiddragExit(DragSourceEvent dse) CallsdragExiton theDragSourceListeners registered with thisDragSourceContextand with the associatedDragSource, and passes them the specifiedDragSourceEvent.voidCallsdragMouseMovedon theDragSourceMotionListeners registered with theDragSourceassociated with thisDragSourceContext, and them passes the specifiedDragSourceDragEvent.voiddragOver(DragSourceDragEvent dsde) CallsdragOveron theDragSourceListeners registered with thisDragSourceContextand with the associatedDragSource, and passes them the specifiedDragSourceDragEvent.voidCallsdropActionChangedon theDragSourceListeners registered with thisDragSourceContextand with the associatedDragSource, and passes them the specifiedDragSourceDragEvent.Returns theComponentassociated with thisDragSourceContext.Returns the current custom dragCursor.Returns theDragSourcethat instantiated thisDragSourceContext.intReturns a bitwise mask ofDnDConstantsthat represent the set of drop actions supported by the drag source for the drag operation associated with thisDragSourceContext.Returns theTransferableassociated with thisDragSourceContext.Returns theDragGestureEventthat initially triggered the drag.voidRemoves the specifiedDragSourceListenerfrom thisDragSourceContext.voidSets the custom cursor for this drag operation to the specifiedCursor.voidNotifies the peer that theTransferable'sDataFlavors have changed.protected voidupdateCurrentCursor(int sourceAct, int targetAct, int status) If the default drag cursor behavior is active, this method sets the default drag cursor for the specified actions supported by the drag source, the drop target action, and status, otherwise this method does nothing.
-
Field Details
-
DEFAULT
protected static final int DEFAULTAnintused by updateCurrentCursor() indicating that theCursorshould change to the default (no drop)Cursor.- See Also:
-
ENTER
protected static final int ENTERAnintused by updateCurrentCursor() indicating that theCursorhas entered aDropTarget.- See Also:
-
OVER
protected static final int OVERAnintused by updateCurrentCursor() indicating that theCursoris over aDropTarget.- See Also:
-
CHANGED
protected static final int CHANGEDAnintused by updateCurrentCursor() indicating that the user operation has changed.- See Also:
-
-
Constructor Details
-
DragSourceContext
public DragSourceContext(DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point offset, Transferable t, DragSourceListener dsl) Called fromDragSource, this constructor creates a newDragSourceContextgiven theDragSourceContextPeerfor this Drag, theDragGestureEventthat triggered the Drag, the initialCursorto use for the Drag, an (optional)Imageto display while the Drag is taking place, the offset of theImageorigin from the hotspot at the instant of the triggering event, theTransferablesubject data, and theDragSourceListenerto use during the Drag and Drop operation.
IfDragSourceContextPeerisnullNullPointerExceptionis thrown.
IfDragGestureEventisnullNullPointerExceptionis thrown.
IfCursorisnullno exception is thrown and the default drag cursor behavior is activated for this drag operation.
IfImageisnullno exception is thrown.
IfImageis notnulland the offset isnull NullPointerExceptionis thrown.
IfTransferableisnullNullPointerExceptionis thrown.
IfDragSourceListenerisnullno exception is thrown.- Parameters:
trigger- the triggering eventdragCursor- the initialCursorfor this drag operation ornullfor the default cursor handling; see class level documentation for more details on the cursor handling mechanism during drag and dropdragImage- theImageto drag (ornull)offset- the offset of the image origin from the hotspot at the instant of the triggering eventt- theTransferabledsl- theDragSourceListener- Throws:
IllegalArgumentException- if theComponentassociated with the trigger event isnull.IllegalArgumentException- if theDragSourcefor the trigger event isnull.IllegalArgumentException- if the drag action for the trigger event isDnDConstants.ACTION_NONE.IllegalArgumentException- if the source actions for theDragGestureRecognizerassociated with the trigger event are equal toDnDConstants.ACTION_NONE.NullPointerException- if dscp, trigger, or t are null, or if dragImage is non-null and offset is null
-
-
Method Details
-
getDragSource
Returns theDragSourcethat instantiated thisDragSourceContext.- Returns:
- the
DragSourcethat instantiated thisDragSourceContext
-
getComponent
Returns theComponentassociated with thisDragSourceContext.- Returns:
- the
Componentthat started the drag
-
getTrigger
Returns theDragGestureEventthat initially triggered the drag.- Returns:
- the Event that triggered the drag
-
getSourceActions
public int getSourceActions()Returns a bitwise mask ofDnDConstantsthat represent the set of drop actions supported by the drag source for the drag operation associated with thisDragSourceContext.- Returns:
- the drop actions supported by the drag source
-
setCursor
Sets the custom cursor for this drag operation to the specifiedCursor. If the specifiedCursorisnull, the default drag cursor behavior is activated for this drag operation, otherwise it is deactivated.- Parameters:
c- the initialCursorfor this drag operation, ornullfor the default cursor handling; see class level documentation for more details on the cursor handling during drag and drop
-
getCursor
Returns the current custom dragCursor.- Returns:
- the current custom drag
Cursor, if it was set otherwise returnsnull. - See Also:
-
addDragSourceListener
Add aDragSourceListenerto thisDragSourceContextif one has not already been added. If aDragSourceListeneralready exists, this method throws aTooManyListenersException.- Parameters:
dsl- theDragSourceListenerto add. Note that whilenullis not prohibited, it is not acceptable as a parameter.- Throws:
TooManyListenersException- if aDragSourceListenerhas already been added
-
removeDragSourceListener
Removes the specifiedDragSourceListenerfrom thisDragSourceContext.- Parameters:
dsl- theDragSourceListenerto remove; note that whilenullis not prohibited, it is not acceptable as a parameter
-
transferablesFlavorsChanged
public void transferablesFlavorsChanged()Notifies the peer that theTransferable'sDataFlavors have changed. -
dragEnter
CallsdragEnteron theDragSourceListeners registered with thisDragSourceContextand with the associatedDragSource, and passes them the specifiedDragSourceDragEvent.- Specified by:
dragEnterin interfaceDragSourceListener- Parameters:
dsde- theDragSourceDragEvent
-
dragOver
CallsdragOveron theDragSourceListeners registered with thisDragSourceContextand with the associatedDragSource, and passes them the specifiedDragSourceDragEvent.- Specified by:
dragOverin interfaceDragSourceListener- Parameters:
dsde- theDragSourceDragEvent
-
dragExit
CallsdragExiton theDragSourceListeners registered with thisDragSourceContextand with the associatedDragSource, and passes them the specifiedDragSourceEvent.- Specified by:
dragExitin interfaceDragSourceListener- Parameters:
dse- theDragSourceEvent
-
dropActionChanged
CallsdropActionChangedon theDragSourceListeners registered with thisDragSourceContextand with the associatedDragSource, and passes them the specifiedDragSourceDragEvent.- Specified by:
dropActionChangedin interfaceDragSourceListener- Parameters:
dsde- theDragSourceDragEvent
-
dragDropEnd
CallsdragDropEndon theDragSourceListeners registered with thisDragSourceContextand with the associatedDragSource, and passes them the specifiedDragSourceDropEvent.- Specified by:
dragDropEndin interfaceDragSourceListener- Parameters:
dsde- theDragSourceDropEvent
-
dragMouseMoved
CallsdragMouseMovedon theDragSourceMotionListeners registered with theDragSourceassociated with thisDragSourceContext, and them passes the specifiedDragSourceDragEvent.- Specified by:
dragMouseMovedin interfaceDragSourceMotionListener- Parameters:
dsde- theDragSourceDragEvent- Since:
- 1.4
-
getTransferable
Returns theTransferableassociated with thisDragSourceContext.- Returns:
- the
Transferable
-
updateCurrentCursor
protected void updateCurrentCursor(int sourceAct, int targetAct, int status) If the default drag cursor behavior is active, this method sets the default drag cursor for the specified actions supported by the drag source, the drop target action, and status, otherwise this method does nothing.- Parameters:
sourceAct- the actions supported by the drag sourcetargetAct- the drop target actionstatus- one of the fieldsDEFAULT,ENTER,OVER,CHANGED
-