java.awt.dnd
Class DragSourceContext

java.lang.Object
  |
  +--java.awt.dnd.DragSourceContext

All Implemented Interfaces:

DragSourceListener, DragSourceMotionListener, EventListener, Serializable

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 to interpose itself between the platform and the listeners provided by the initiator of the drag operation.

Since:

1.2

See Also:

DragSourceListener, DragSourceMotionListener, Serialized Form

Field Summary

protected static int	CHANGED An int used by updateCurrentCursor() indicating that the user operation has changed.
protected static int	DEFAULT An int used by updateCurrentCursor() indicating that the Cursor should change to the default (no drop) Cursor.
protected static int	ENTER An int used by updateCurrentCursor() indicating that the Cursor has entered a DropTarget.
protected static int	OVER An int used by updateCurrentCursor() indicating that the Cursor is over a DropTarget.

Constructor Summary

DragSourceContext(java.awt.dnd.peer.DragSourceContextPeer dscp, 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.

Method Summary

void	addDragSourceListener(DragSourceListener dsl) Add a DragSourceListener to this DragSourceContext if one has not already been added.
void	dragDropEnd(DragSourceDropEvent dsde) This method calls dragDropEnd on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceDropEvent.
void	dragEnter(DragSourceDragEvent dsde) This method calls dragEnter on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceDragEvent.
void	dragExit(DragSourceEvent dse) This method calls dragExit on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceEvent.
void	dragMouseMoved(DragSourceDragEvent dsde) This method calls dragMouseMoved on the DragSourceMotionListeners registered with the DragSource associated with this DragSourceContext, and them passes the specified DragSourceDragEvent.
void	dragOver(DragSourceDragEvent dsde) This method calls dragOver on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceDragEvent.
void	dropActionChanged(DragSourceDragEvent dsde) This method calls dropActionChanged on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceDragEvent.
Component	getComponent() This method returns the Component associated with this DragSourceContext.
Cursor	getCursor() This method returns the current drag Cursor.
DragSource	getDragSource() This method returns the DragSource that instantiated this DragSourceContext.
int	getSourceActions() This method returns a bitwise mask of DnDConstants that represents the set of drop actions supported by the drag source for the drag operation associated with this DragSourceContext.
Transferable	getTransferable() This method returns the Transferable associated with this DragSourceContext.
DragGestureEvent	getTrigger() This method returns the DragGestureEvent that initially triggered the drag.
void	removeDragSourceListener(DragSourceListener dsl) This method removes the specified DragSourceListener from this DragSourceContext.
void	setCursor(Cursor c) This method sets the current drag Cursor.
void	transferablesFlavorsChanged() This method notifies the peer that the Transferable's DataFlavors have changed.
protected void	updateCurrentCursor(int dropOp, int targetAct, int status) check the cursor for updates and implement defaults

Methods inherited from 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(java.awt.dnd.peer.DragSourceContextPeer dscp,
                         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 default drag cursors are used 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:

dscp - the DragSourceContextPeer for this drag

trigger - the triggering event

dragCursor - the initial Cursor

dragImage - the Image to drag (or null)

offset - the offset of the image origin from the hotspot at the instant of the triggering event

t - the Transferable

dsl - the DragSourceListener

Throws:

IllegalArgumentException - if the Component associated with the trigger event is null.

NullPointerException - if dscp, trigger, or t are null, or if dragImage is non-null and offset is null

Method Detail

getDragSource

public DragSource getDragSource()

This method returns the DragSource that instantiated this DragSourceContext.

Returns:

the DragSource that instantiated this DragSourceContext

getComponent

public Component getComponent()

This method returns the Component associated with this DragSourceContext.

Returns:

the Component that started the drag

getTrigger

public DragGestureEvent getTrigger()

This method returns the DragGestureEvent that initially triggered the drag.

Returns:

the Event that triggered the drag

getSourceActions

public int getSourceActions()

This method returns a bitwise mask of DnDConstants that represents 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)

This method sets the current drag Cursor.

Parameters:

c - the Cursor to display. Note that while null is not prohibited, it is not an acceptable value for this parameter.

getCursor

public Cursor getCursor()

This method returns the current drag Cursor.

Returns:

the current drag 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 - the DragSourceListener to add. Note that while null is not prohibited, it is not acceptable as a parameter.

Throws:

TooManyListenersException - if a DragSourceListener has already been added

TooManyListenersException

removeDragSourceListener

public void removeDragSourceListener(DragSourceListener dsl)

This method removes the specified DragSourceListener from this DragSourceContext.

Parameters:

dsl - the DragSourceListener to remove. Note that while null is not prohibited, it is not acceptable as a parameter.

transferablesFlavorsChanged

public void transferablesFlavorsChanged()

This method notifies the peer that the Transferable's DataFlavors have changed.

dragEnter

public void dragEnter(DragSourceDragEvent dsde)

This method calls dragEnter on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceDragEvent.

Specified by:

dragEnter in interface DragSourceListener

Parameters:

dsde - the DragSourceDragEvent

dragOver

public void dragOver(DragSourceDragEvent dsde)

This method calls dragOver on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceDragEvent.

Specified by:

dragOver in interface DragSourceListener

Parameters:

dsde - the DragSourceDragEvent

dragExit

public void dragExit(DragSourceEvent dse)

This method calls dragExit on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceEvent.

Specified by:

dragExit in interface DragSourceListener

Parameters:

dse - the DragSourceEvent

dropActionChanged

public void dropActionChanged(DragSourceDragEvent dsde)

This method calls dropActionChanged on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceDragEvent.

Specified by:

dropActionChanged in interface DragSourceListener

Parameters:

dsde - the DragSourceDragEvent

dragDropEnd

public void dragDropEnd(DragSourceDropEvent dsde)

This method calls dragDropEnd on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceDropEvent.

Specified by:

dragDropEnd in interface DragSourceListener

Parameters:

dsde - the DragSourceDropEvent

dragMouseMoved

public void dragMouseMoved(DragSourceDragEvent dsde)

This method calls dragMouseMoved on the DragSourceMotionListeners registered with the DragSource associated with this DragSourceContext, and them passes the specified DragSourceDragEvent.

Specified by:

dragMouseMoved in interface DragSourceMotionListener

Parameters:

dsde - the DragSourceDragEvent

Since:

1.4

getTransferable

public Transferable getTransferable()

This method returns the Transferable associated with this DragSourceContext.

Returns:

the Transferable

updateCurrentCursor

protected void updateCurrentCursor(int dropOp,
                                   int targetAct,
                                   int status)

check the cursor for updates and implement defaults

Parameters:

dropOp - the user's currently selected operation

targetAct - the current target's supported actions

status - the constant