- java.lang.Object
-
- java.awt.dnd.DragSourceContext
-
- All Implemented Interfaces:
DragSourceListener,DragSourceMotionListener,Serializable,EventListener
public class DragSourceContext extends Object implements DragSourceListener, DragSourceMotionListener, Serializable
TheDragSourceContextclass 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 theTransferablerepresenting the source data for the drag operation.Note that the
DragSourceContextitself implements theDragSourceListenerandDragSourceMotionListenerinterfaces. This is to allow the platform peer (theDragSourceContextPeerinstance) created by theDragSourceto notify theDragSourceContextof state changes in the ongoing operation. This allows theDragSourceContextobject to interpose itself between the platform and the listeners provided by the initiator of the drag operation.By default,
DragSourceContextsets 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 theDragSourceevents and calling thesetCursor()method. Alternatively, you can provide custom cursor behavior by providing custom implementations of theDragSourceand theDragSourceContextclasses.- Since:
- 1.2
- See Also:
DragSourceListener,DragSourceMotionListener,DnDConstants, Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description protected static intCHANGEDAnintused by updateCurrentCursor() indicating that the user operation has changed.protected static intDEFAULTAnintused by updateCurrentCursor() indicating that theCursorshould change to the default (no drop)Cursor.protected static intENTERAnintused by updateCurrentCursor() indicating that theCursorhas entered aDropTarget.protected static intOVERAnintused by updateCurrentCursor() indicating that theCursoris over aDropTarget.
-
Constructor Summary
Constructors Constructor Description 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.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description voidaddDragSourceListener(DragSourceListener dsl)Add aDragSourceListenerto thisDragSourceContextif one has not already been added.voiddragDropEnd(DragSourceDropEvent dsde)CallsdragDropEndon 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.voiddragMouseMoved(DragSourceDragEvent dsde)CallsdragMouseMovedon 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.voiddropActionChanged(DragSourceDragEvent dsde)CallsdropActionChangedon theDragSourceListeners registered with thisDragSourceContextand with the associatedDragSource, and passes them the specifiedDragSourceDragEvent.ComponentgetComponent()Returns theComponentassociated with thisDragSourceContext.CursorgetCursor()Returns the current custom dragCursor.DragSourcegetDragSource()Returns theDragSourcethat instantiated thisDragSourceContext.intgetSourceActions()Returns a bitwise mask ofDnDConstantsthat represent the set of drop actions supported by the drag source for the drag operation associated with thisDragSourceContext.TransferablegetTransferable()Returns theTransferableassociated with thisDragSourceContext.DragGestureEventgetTrigger()Returns theDragGestureEventthat initially triggered the drag.voidremoveDragSourceListener(DragSourceListener dsl)Removes the specifiedDragSourceListenerfrom thisDragSourceContext.voidsetCursor(Cursor c)Sets the custom cursor for this drag operation to the specifiedCursor.voidtransferablesFlavorsChanged()Notifies 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 Detail
-
DEFAULT
protected static final int DEFAULT
Anintused by updateCurrentCursor() indicating that theCursorshould change to the default (no drop)Cursor.- See Also:
- Constant Field Values
-
ENTER
protected static final int ENTER
Anintused by updateCurrentCursor() indicating that theCursorhas entered aDropTarget.- See Also:
- Constant Field Values
-
OVER
protected static final int OVER
Anintused by updateCurrentCursor() indicating that theCursoris over aDropTarget.- See Also:
- Constant Field Values
-
CHANGED
protected static final int CHANGED
Anintused by updateCurrentCursor() indicating that the user operation has changed.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
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 Detail
-
getDragSource
public DragSource getDragSource()
Returns theDragSourcethat instantiated thisDragSourceContext.- Returns:
- the
DragSourcethat instantiated thisDragSourceContext
-
getComponent
public Component getComponent()
Returns theComponentassociated with thisDragSourceContext.- Returns:
- the
Componentthat started the drag
-
getTrigger
public DragGestureEvent 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
public void setCursor(Cursor c)
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
public Cursor getCursor()
Returns the current custom dragCursor.- Returns:
- the current custom drag
Cursor, if it was set otherwise returnsnull. - See Also:
setCursor(java.awt.Cursor)
-
addDragSourceListener
public void addDragSourceListener(DragSourceListener dsl) throws TooManyListenersException
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
public void removeDragSourceListener(DragSourceListener dsl)
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
public void dragEnter(DragSourceDragEvent dsde)
CallsdragEnteron theDragSourceListeners registered with thisDragSourceContextand with the associatedDragSource, and passes them the specifiedDragSourceDragEvent.- Specified by:
dragEnterin interfaceDragSourceListener- Parameters:
dsde- theDragSourceDragEvent
-
dragOver
public void dragOver(DragSourceDragEvent dsde)
CallsdragOveron theDragSourceListeners registered with thisDragSourceContextand with the associatedDragSource, and passes them the specifiedDragSourceDragEvent.- Specified by:
dragOverin interfaceDragSourceListener- Parameters:
dsde- theDragSourceDragEvent
-
dragExit
public void dragExit(DragSourceEvent dse)
CallsdragExiton theDragSourceListeners registered with thisDragSourceContextand with the associatedDragSource, and passes them the specifiedDragSourceEvent.- Specified by:
dragExitin interfaceDragSourceListener- Parameters:
dse- theDragSourceEvent
-
dropActionChanged
public void dropActionChanged(DragSourceDragEvent dsde)
CallsdropActionChangedon theDragSourceListeners registered with thisDragSourceContextand with the associatedDragSource, and passes them the specifiedDragSourceDragEvent.- Specified by:
dropActionChangedin interfaceDragSourceListener- Parameters:
dsde- theDragSourceDragEvent
-
dragDropEnd
public void dragDropEnd(DragSourceDropEvent dsde)
CallsdragDropEndon theDragSourceListeners registered with thisDragSourceContextand with the associatedDragSource, and passes them the specifiedDragSourceDropEvent.- Specified by:
dragDropEndin interfaceDragSourceListener- Parameters:
dsde- theDragSourceDropEvent
-
dragMouseMoved
public void dragMouseMoved(DragSourceDragEvent dsde)
CallsdragMouseMovedon theDragSourceMotionListeners registered with theDragSourceassociated with thisDragSourceContext, and them passes the specifiedDragSourceDragEvent.- Specified by:
dragMouseMovedin interfaceDragSourceMotionListener- Parameters:
dsde- theDragSourceDragEvent- Since:
- 1.4
-
getTransferable
public Transferable 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
-
-