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
Modifier and TypeFieldDescriptionprotected static final int
Anint
used by updateCurrentCursor() indicating that the user operation has changed.protected static final int
Anint
used by updateCurrentCursor() indicating that theCursor
should change to the default (no drop)Cursor
.protected static final int
Anint
used by updateCurrentCursor() indicating that theCursor
has entered aDropTarget
.protected static final int
Anint
used by updateCurrentCursor() indicating that theCursor
is over aDropTarget
. -
Constructor Summary
ConstructorDescriptionDragSourceContext
(DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point offset, Transferable t, DragSourceListener dsl) Called fromDragSource
, this constructor creates a newDragSourceContext
given theDragSourceContextPeer
for this Drag, theDragGestureEvent
that triggered the Drag, the initialCursor
to use for the Drag, an (optional)Image
to display while the Drag is taking place, the offset of theImage
origin from the hotspot at the instant of the triggering event, theTransferable
subject data, and theDragSourceListener
to use during the Drag and Drop operation. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Add aDragSourceListener
to thisDragSourceContext
if one has not already been added.void
CallsdragDropEnd
on theDragSourceListener
s registered with thisDragSourceContext
and with the associatedDragSource
, and passes them the specifiedDragSourceDropEvent
.void
dragEnter
(DragSourceDragEvent dsde) CallsdragEnter
on theDragSourceListener
s registered with thisDragSourceContext
and with the associatedDragSource
, and passes them the specifiedDragSourceDragEvent
.void
dragExit
(DragSourceEvent dse) CallsdragExit
on theDragSourceListener
s registered with thisDragSourceContext
and with the associatedDragSource
, and passes them the specifiedDragSourceEvent
.void
CallsdragMouseMoved
on theDragSourceMotionListener
s registered with theDragSource
associated with thisDragSourceContext
, and them passes the specifiedDragSourceDragEvent
.void
dragOver
(DragSourceDragEvent dsde) CallsdragOver
on theDragSourceListener
s registered with thisDragSourceContext
and with the associatedDragSource
, and passes them the specifiedDragSourceDragEvent
.void
CallsdropActionChanged
on theDragSourceListener
s registered with thisDragSourceContext
and with the associatedDragSource
, and passes them the specifiedDragSourceDragEvent
.Returns theComponent
associated with thisDragSourceContext
.Returns the current custom dragCursor
.Returns theDragSource
that instantiated thisDragSourceContext
.int
Returns a bitwise mask ofDnDConstants
that represent the set of drop actions supported by the drag source for the drag operation associated with thisDragSourceContext
.Returns theTransferable
associated with thisDragSourceContext
.Returns theDragGestureEvent
that initially triggered the drag.void
Removes the specifiedDragSourceListener
from thisDragSourceContext
.void
Sets the custom cursor for this drag operation to the specifiedCursor
.void
Notifies the peer that theTransferable
'sDataFlavor
s have changed.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.
-
Field Details
-
DEFAULT
protected static final int DEFAULTAnint
used by updateCurrentCursor() indicating that theCursor
should change to the default (no drop)Cursor
.- See Also:
-
ENTER
protected static final int ENTERAnint
used by updateCurrentCursor() indicating that theCursor
has entered aDropTarget
.- See Also:
-
OVER
protected static final int OVERAnint
used by updateCurrentCursor() indicating that theCursor
is over aDropTarget
.- See Also:
-
CHANGED
protected static final int CHANGEDAnint
used 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 newDragSourceContext
given theDragSourceContextPeer
for this Drag, theDragGestureEvent
that triggered the Drag, the initialCursor
to use for the Drag, an (optional)Image
to display while the Drag is taking place, the offset of theImage
origin from the hotspot at the instant of the triggering event, theTransferable
subject data, and theDragSourceListener
to use during the Drag and Drop operation.
IfDragSourceContextPeer
isnull
NullPointerException
is thrown.
IfDragGestureEvent
isnull
NullPointerException
is thrown.
IfCursor
isnull
no exception is thrown and the default drag cursor behavior is activated for this drag operation.
IfImage
isnull
no exception is thrown.
IfImage
is notnull
and the offset isnull NullPointerException
is thrown.
IfTransferable
isnull
NullPointerException
is thrown.
IfDragSourceListener
isnull
no exception is thrown.- Parameters:
trigger
- the triggering eventdragCursor
- the initialCursor
for this drag operation ornull
for the default cursor handling; see class level documentation for more details on the cursor handling mechanism during drag and dropdragImage
- theImage
to drag (ornull
)offset
- the offset of the image origin from the hotspot at the instant of the triggering eventt
- theTransferable
dsl
- theDragSourceListener
- Throws:
IllegalArgumentException
- if theComponent
associated with the trigger event isnull
.IllegalArgumentException
- if theDragSource
for the trigger event isnull
.IllegalArgumentException
- if the drag action for the trigger event isDnDConstants.ACTION_NONE
.IllegalArgumentException
- if the source actions for theDragGestureRecognizer
associated 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 theDragSource
that instantiated thisDragSourceContext
.- Returns:
- the
DragSource
that instantiated thisDragSourceContext
-
getComponent
Returns theComponent
associated with thisDragSourceContext
.- Returns:
- the
Component
that started the drag
-
getTrigger
Returns theDragGestureEvent
that initially triggered the drag.- Returns:
- the Event that triggered the drag
-
getSourceActions
public int getSourceActions()Returns a bitwise mask ofDnDConstants
that 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 specifiedCursor
isnull
, the default drag cursor behavior is activated for this drag operation, otherwise it is deactivated.- Parameters:
c
- the initialCursor
for this drag operation, ornull
for 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 aDragSourceListener
to thisDragSourceContext
if one has not already been added. If aDragSourceListener
already exists, this method throws aTooManyListenersException
.- Parameters:
dsl
- theDragSourceListener
to add. Note that whilenull
is not prohibited, it is not acceptable as a parameter.- Throws:
TooManyListenersException
- if aDragSourceListener
has already been added
-
removeDragSourceListener
Removes the specifiedDragSourceListener
from thisDragSourceContext
.- Parameters:
dsl
- theDragSourceListener
to remove; note that whilenull
is not prohibited, it is not acceptable as a parameter
-
transferablesFlavorsChanged
public void transferablesFlavorsChanged()Notifies the peer that theTransferable
'sDataFlavor
s have changed. -
dragEnter
CallsdragEnter
on theDragSourceListener
s registered with thisDragSourceContext
and with the associatedDragSource
, and passes them the specifiedDragSourceDragEvent
.- Specified by:
dragEnter
in interfaceDragSourceListener
- Parameters:
dsde
- theDragSourceDragEvent
-
dragOver
CallsdragOver
on theDragSourceListener
s registered with thisDragSourceContext
and with the associatedDragSource
, and passes them the specifiedDragSourceDragEvent
.- Specified by:
dragOver
in interfaceDragSourceListener
- Parameters:
dsde
- theDragSourceDragEvent
-
dragExit
CallsdragExit
on theDragSourceListener
s registered with thisDragSourceContext
and with the associatedDragSource
, and passes them the specifiedDragSourceEvent
.- Specified by:
dragExit
in interfaceDragSourceListener
- Parameters:
dse
- theDragSourceEvent
-
dropActionChanged
CallsdropActionChanged
on theDragSourceListener
s registered with thisDragSourceContext
and with the associatedDragSource
, and passes them the specifiedDragSourceDragEvent
.- Specified by:
dropActionChanged
in interfaceDragSourceListener
- Parameters:
dsde
- theDragSourceDragEvent
-
dragDropEnd
CallsdragDropEnd
on theDragSourceListener
s registered with thisDragSourceContext
and with the associatedDragSource
, and passes them the specifiedDragSourceDropEvent
.- Specified by:
dragDropEnd
in interfaceDragSourceListener
- Parameters:
dsde
- theDragSourceDropEvent
-
dragMouseMoved
CallsdragMouseMoved
on theDragSourceMotionListener
s registered with theDragSource
associated with thisDragSourceContext
, and them passes the specifiedDragSourceDragEvent
.- Specified by:
dragMouseMoved
in interfaceDragSourceMotionListener
- Parameters:
dsde
- theDragSourceDragEvent
- Since:
- 1.4
-
getTransferable
Returns theTransferable
associated 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
-