JavaTM 2 Platform
Std. Ed. v1.3.1

java.awt.dnd
Class DragSourceContext

java.lang.Object
  |
  +--java.awt.dnd.DragSourceContext
All Implemented Interfaces:
DragSourceListener, EventListener

public class DragSourceContext
extends Object
implements DragSourceListener

The DragSourceContext class is responsible for managing the initiator side of the Drag and Drop protocol. In particular it is responsible for managing event notifications to the DragSourceListener, and providing the Transferable state to enable the data transfer.

An instance of this class is created as a result of a DragSource's startDrag() method being successfully invoked. This instance is responsible for tracking the state of the operation on behalf of the DragSource and dispatching state changes to the DragSourceListener.

Note that the DragSourceContext itself implements the DragSourceListener interface. This is to allow the platform peer (the DragSourceContextPeer instance) created by the DragSource to notify the DragSourceContext of changes in state in the ongiong operation. This allows the DragSourceContext to interpose itself between the platform and the DragSourceListener provided by the initiator of the operation.

Since:
1.2

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 intercepts the DragSourceDropEvent associated with dragDropEnd() from the peer.
 void dragEnter(DragSourceDragEvent dsde)
          This method intercepts the DragSourceDragEvent associated with dragEnter() from the peer.
 void dragExit(DragSourceEvent dse)
          This method intercepts the DragSourceEvent associated with dragExit() from the peer.
 void dragOver(DragSourceDragEvent dsde)
          This method intercepts the DragSourceDragEvent associated with dragOver() from the peer.
 void dropActionChanged(DragSourceDragEvent dsde)
          This method intercepts the DragSourceDragEvent associated with dropActionChanged() from the peer.
 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 an int representing the current action(s) 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.

ENTER

protected static final int ENTER
An int used by updateCurrentCursor() indicating that the Cursor has entered a DropTarget.

OVER

protected static final int OVER
An int used by updateCurrentCursor() indicating that the Cursor is over a DropTarget.

CHANGED

protected static final int CHANGED
An int used by updateCurrentCursor() indicating that the user operation has changed.
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.
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 trigger instance is incomplete
NullPointerException - if dscp, dsl, 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 an int representing the current action(s) associated with this DragSourceContext.

Returns:
the current actions

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

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 intercepts the DragSourceDragEvent associated with dragEnter() from the peer.

Note: This method is called by the peer implementation, not the user.

Specified by:
dragEnter in interface DragSourceListener
Parameters:
dsde - the intercepted DragSourceDragEvent

dragOver

public void dragOver(DragSourceDragEvent dsde)
This method intercepts the DragSourceDragEvent associated with dragOver() from the peer.

Note: This method is called by the peer implementation, not the user.

Specified by:
dragOver in interface DragSourceListener
Parameters:
dsde - the intercepted DragSourceDragEvent

dragExit

public void dragExit(DragSourceEvent dse)
This method intercepts the DragSourceEvent associated with dragExit() from the peer.

Note: This method is called by the peer implementation, not the user.

Specified by:
dragExit in interface DragSourceListener
Parameters:
dse - the intercepted DragSourceEvent

dropActionChanged

public void dropActionChanged(DragSourceDragEvent dsde)
This method intercepts the DragSourceDragEvent associated with dropActionChanged() from the peer.

Note: This method is called by the peer implementation, not the user.

Specified by:
dropActionChanged in interface DragSourceListener
Parameters:
dsde - the intercepted DragSourceDragEvent

dragDropEnd

public void dragDropEnd(DragSourceDropEvent dsde)
This method intercepts the DragSourceDropEvent associated with dragDropEnd() from the peer.

Note: This method is called by the peer implementation, not the user. The value of null is not acceptable as a parameter to this method.

Specified by:
dragDropEnd in interface DragSourceListener
Parameters:
dsde - the intercepted DragSourceDropEvent

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

JavaTM 2 Platform
Std. Ed. v1.3.1

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Java, Java 2D, and JDBC are trademarks or registered trademarks of Oracle and/or its affiliates, in the US and other countries.
Copyright © 1995, 2010 Oracle and/or its affiliates. All rights reserved.