java.awt.dnd
Class DragSourceContext

java.lang.Object
  extended byjava.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.
private  Cursor cursor
          The current drag cursor.
protected static int DEFAULT
          An int used by updateCurrentCursor() indicating that the Cursor should change to the default (no drop) Cursor.
private static Transferable emptyTransferable
           
protected static int ENTER
          An int used by updateCurrentCursor() indicating that the Cursor has entered a DropTarget.
private  DragSourceListener listener
           
protected static int OVER
          An int used by updateCurrentCursor() indicating that the Cursor is over a DropTarget.
private  DragSourceContextPeer peer
           
private static long serialVersionUID
           
private  int sourceActions
          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.
private  Transferable transferable
           
private  DragGestureEvent trigger
          The event which triggered the start of the drag.
private  boolean useCustomCursor
          true if the custom drag cursor is used instead of the default one.
 
Constructor Summary
DragSourceContext(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)
          Calls dragDropEnd on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceDropEvent.
 void dragEnter(DragSourceDragEvent dsde)
          Calls dragEnter on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceDragEvent.
 void dragExit(DragSourceEvent dse)
          Calls dragExit on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceEvent.
 void dragMouseMoved(DragSourceDragEvent dsde)
          Calls dragMouseMoved on the DragSourceMotionListeners registered with the DragSource associated with this DragSourceContext, and them passes the specified DragSourceDragEvent.
 void dragOver(DragSourceDragEvent dsde)
          Calls dragOver on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceDragEvent.
 void dropActionChanged(DragSourceDragEvent dsde)
          Calls dropActionChanged on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceDragEvent.
 Component getComponent()
          Returns the Component associated with this DragSourceContext.
 Cursor getCursor()
          Returns the current drag Cursor.
 DragSource getDragSource()
          Returns the DragSource that instantiated this DragSourceContext.
 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.
 Transferable getTransferable()
          Returns the Transferable associated with this DragSourceContext.
 DragGestureEvent getTrigger()
          Returns the DragGestureEvent that initially triggered the drag.
private  void readObject(ObjectInputStream s)
          Deserializes this DragSourceContext.
 void removeDragSourceListener(DragSourceListener dsl)
          Removes the specified DragSourceListener from this DragSourceContext.
 void setCursor(Cursor c)
          Sets the cursor for this drag operation to the specified Cursor.
private  void setCursorImpl(Cursor c)
           
 void transferablesFlavorsChanged()
          Notifies the peer that the Transferable's DataFlavors have changed.
protected  void updateCurrentCursor(int dropOp, int targetAct, int status)
          If the default drag cursor behavior is active, this method sets the default drag cursor for the specified selected operation, supported actions and status, otherwise this method does nothing.
private  void writeObject(ObjectOutputStream s)
          Serializes this DragSourceContext.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

serialVersionUID

private static final long serialVersionUID
See Also:
Constant Field Values

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

emptyTransferable

private static Transferable emptyTransferable

peer

private transient DragSourceContextPeer peer

trigger

private DragGestureEvent trigger
The event which triggered the start of the drag.


cursor

private Cursor cursor
The current drag cursor.


transferable

private transient Transferable transferable

listener

private transient DragSourceListener listener

useCustomCursor

private boolean useCustomCursor
true if the custom drag cursor is used instead of the default one.


sourceActions

private final int sourceActions
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.

Constructor Detail

DragSourceContext

public DragSourceContext(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 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:
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.
IllegalArgumentException - if the DragSource for the trigger event is null.
IllegalArgumentException - if the drag action for the trigger event is DnDConstants.ACTION_NONE.
IllegalArgumentException - if the source actions for the DragGestureRecognizer associated with the trigger event are equal to DnDConstants.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 this DragSourceContext

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 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 Cursor to display, or null to activate the default drag cursor behavior

getCursor

public Cursor getCursor()
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)
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()
Notifies the peer that the Transferable's DataFlavors have changed.


dragEnter

public void dragEnter(DragSourceDragEvent dsde)
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)
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)
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)
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)
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)
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()
Returns the Transferable associated with this DragSourceContext.

Returns:
the Transferable

updateCurrentCursor

protected void updateCurrentCursor(int dropOp,
                                   int targetAct,
                                   int status)
If the default drag cursor behavior is active, this method sets the default drag cursor for the specified selected operation, supported actions and status, otherwise this method does nothing.

Parameters:
dropOp - the user's currently selected operation
targetAct - the current target's supported actions
status - the constant

setCursorImpl

private void setCursorImpl(Cursor c)

writeObject

private void writeObject(ObjectOutputStream s)
                  throws IOException
Serializes this DragSourceContext. This method first performs default serialization. Next, this object's Transferable is written out if and only if it can be serialized. If not, null is written instead. In this case, a DragSourceContext created from the resulting deserialized stream will contain a dummy Transferable which supports no DataFlavors. Finally, this object's DragSourceListener is written out if and only if it can be serialized. If not, null is written instead.

Throws:
IOException
Since:
1.4

readObject

private void readObject(ObjectInputStream s)
                 throws ClassNotFoundException,
                        IOException
Deserializes this DragSourceContext. This method first performs default deserialization for all non-transient fields. This object's Transferable and DragSourceListener are then deserialized as well by using the next two objects in the stream. If the resulting Transferable is null, this object's Transferable is set to a dummy Transferable which supports no DataFlavors.

Throws:
ClassNotFoundException
IOException
Since:
1.4