Class DragSourceContext
- java.lang.Object
-
- java.awt.dnd.DragSourceContext
- All Implemented Interfaces:
-
DragSourceListener
,DragSourceMotionListener
,Serializable
,EventListener
public class DragSourceContext extends Object implements DragSourceListener, DragSourceMotionListener, Serializable
The 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:
-
DragSourceListener
,DragSourceMotionListener
,DnDConstants
, Serialized Form
Field Summary
Modifier and Type | Field | Description |
---|---|---|
protected static int | CHANGED | An |
protected static int | DEFAULT | An |
protected static int | ENTER | An |
protected static int | OVER | An |
Constructor Summary
Constructor | Description |
---|---|
DragSourceContext(DragGestureEvent trigger,
Cursor dragCursor,
Image dragImage,
Point offset,
Transferable t,
DragSourceListener dsl) | Called from |
Method Summary
Modifier and Type | Method | Description |
---|---|---|
void | addDragSourceListener(DragSourceListener dsl) | Add a |
void | dragDropEnd(DragSourceDropEvent dsde) | Calls |
void | dragEnter(DragSourceDragEvent dsde) | Calls |
void | dragExit(DragSourceEvent dse) | Calls |
void | dragMouseMoved(DragSourceDragEvent dsde) | Calls |
void | dragOver(DragSourceDragEvent dsde) | Calls |
void | dropActionChanged(DragSourceDragEvent dsde) | Calls |
Component | getComponent() | Returns the |
Cursor | getCursor() | Returns the current custom drag |
DragSource | getDragSource() | Returns the |
int | getSourceActions() | Returns a bitwise mask of |
Transferable | getTransferable() | Returns the |
DragGestureEvent | getTrigger() | Returns the |
void | removeDragSourceListener(DragSourceListener dsl) | Removes the specified |
void | setCursor(Cursor c) | Sets the custom cursor for this drag operation to the specified |
void | transferablesFlavorsChanged() | Notifies the peer that the |
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. |
Methods declared in class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Field Detail
DEFAULT
protected static final int DEFAULT
An int
used by updateCurrentCursor() indicating that the Cursor
should change to the default (no drop) Cursor
.
- See Also:
- Constant Field Values
ENTER
protected static final int ENTER
An int
used by updateCurrentCursor() indicating that the Cursor
has entered a DropTarget
.
- See Also:
- Constant Field Values
OVER
protected static final int OVER
An int
used by updateCurrentCursor() indicating that the Cursor
is over a DropTarget
.
- See Also:
- Constant Field Values
CHANGED
protected static final int CHANGED
An int
used 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 from DragSource
, this constructor creates a new DragSourceContext
given the DragSourceContextPeer
for this Drag, the DragGestureEvent
that triggered the Drag, the initial Cursor
to use for the Drag, an (optional) Image
to display while the Drag is taking place, the offset of the Image
origin from the hotspot at the instant of the triggering event, the Transferable
subject data, and the DragSourceListener
to use during the Drag and Drop operation.
If DragSourceContextPeer
is null
NullPointerException
is thrown.
If DragGestureEvent
is null
NullPointerException
is thrown.
If Cursor
is null
no exception is thrown and the default drag cursor behavior is activated for this drag operation.
If Image
is null
no exception is thrown.
If Image
is not null
and the offset is null NullPointerException
is thrown.
If Transferable
is null
NullPointerException
is thrown.
If DragSourceListener
is null
no exception is thrown.
- Parameters:
-
trigger
- the triggering event -
dragCursor
- 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 drop -
dragImage
- theImage
to drag (ornull
) -
offset
- the offset of the image origin from the hotspot at the instant of the triggering event -
t
- 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 Detail
getDragSource
public DragSource getDragSource()
Returns the DragSource
that instantiated this DragSourceContext
.
- Returns:
- the
DragSource
that instantiated thisDragSourceContext
getComponent
public Component getComponent()
Returns the Component
associated with this DragSourceContext
.
- Returns:
- the
Component
that started the drag
getTrigger
public DragGestureEvent getTrigger()
Returns the DragGestureEvent
that initially triggered the drag.
- Returns:
- the Event that triggered the drag
getSourceActions
public int getSourceActions()
Returns a bitwise mask of DnDConstants
that represent the set of drop actions supported by the drag source for the drag operation associated with this DragSourceContext
.
- 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 specified Cursor
. If the specified Cursor
is null
, 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
public Cursor getCursor()
Returns the current custom drag Cursor
.
- 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 a DragSourceListener
to this DragSourceContext
if one has not already been added. If a DragSourceListener
already exists, this method throws a TooManyListenersException
.
- 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
public void removeDragSourceListener(DragSourceListener dsl)
Removes the specified DragSourceListener
from this DragSourceContext
.
- 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 the Transferable
's DataFlavor
s have changed.
dragEnter
public void dragEnter(DragSourceDragEvent dsde)
Calls dragEnter
on the DragSourceListener
s registered with this DragSourceContext
and with the associated DragSource
, and passes them the specified DragSourceDragEvent
.
- Specified by:
-
dragEnter
in interfaceDragSourceListener
- Parameters:
-
dsde
- theDragSourceDragEvent
dragOver
public void dragOver(DragSourceDragEvent dsde)
Calls dragOver
on the DragSourceListener
s registered with this DragSourceContext
and with the associated DragSource
, and passes them the specified DragSourceDragEvent
.
- Specified by:
-
dragOver
in interfaceDragSourceListener
- Parameters:
-
dsde
- theDragSourceDragEvent
dragExit
public void dragExit(DragSourceEvent dse)
Calls dragExit
on the DragSourceListener
s registered with this DragSourceContext
and with the associated DragSource
, and passes them the specified DragSourceEvent
.
- Specified by:
-
dragExit
in interfaceDragSourceListener
- Parameters:
-
dse
- theDragSourceEvent
dropActionChanged
public void dropActionChanged(DragSourceDragEvent dsde)
Calls dropActionChanged
on the DragSourceListener
s registered with this DragSourceContext
and with the associated DragSource
, and passes them the specified DragSourceDragEvent
.
- Specified by:
-
dropActionChanged
in interfaceDragSourceListener
- Parameters:
-
dsde
- theDragSourceDragEvent
dragDropEnd
public void dragDropEnd(DragSourceDropEvent dsde)
Calls dragDropEnd
on the DragSourceListener
s registered with this DragSourceContext
and with the associated DragSource
, and passes them the specified DragSourceDropEvent
.
- Specified by:
-
dragDropEnd
in interfaceDragSourceListener
- Parameters:
-
dsde
- theDragSourceDropEvent
dragMouseMoved
public void dragMouseMoved(DragSourceDragEvent dsde)
Calls dragMouseMoved
on the DragSourceMotionListener
s registered with the DragSource
associated with this DragSourceContext
, and them passes the specified DragSourceDragEvent
.
- Specified by:
-
dragMouseMoved
in interfaceDragSourceMotionListener
- Parameters:
-
dsde
- theDragSourceDragEvent
- Since:
- 1.4
getTransferable
public Transferable getTransferable()
Returns the Transferable
associated with this DragSourceContext
.
- 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 source -
targetAct
- the drop target action -
status
- one of the fieldsDEFAULT
,ENTER
,OVER
,CHANGED