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

Fields

Modifier and Type	Field and Description
`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

Constructors

Constructor and Description

Constructor and Description
`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.

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

All Methods

Instance Methods

Concrete Methods
Modifier and Type	Method and Description
`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 `DragSourceListener`s registered with this `DragSourceContext` and with the associated `DragSource`, and passes them the specified `DragSourceDropEvent`.
`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`.
`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`.
`void`	`dragMouseMoved(DragSourceDragEvent dsde)` Calls `dragMouseMoved` on the `DragSourceMotionListener`s registered with the `DragSource` associated with this `DragSourceContext`, and them passes the specified `DragSourceDragEvent`.
`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`.
`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`.
`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.
`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`.
`void`	`transferablesFlavorsChanged()` Notifies the peer that the `Transferable`'s `DataFlavor`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.

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 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 for this drag operation or null for the default cursor handling; see class level documentation for more details on the cursor handling mechanism during drag and drop
    
    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 initial Cursor for this drag operation, or null 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 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)
```
    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 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 fields DEFAULT, ENTER, OVER, CHANGED

Class DragSourceContext

Field Summary

Fields

Constructor Summary

Constructors

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT

ENTER

OVER

CHANGED

Constructor Detail

DragSourceContext

Method Detail

getDragSource

getComponent

getTrigger

getSourceActions

setCursor

getCursor

addDragSourceListener

removeDragSourceListener

transferablesFlavorsChanged

dragEnter

dragOver

dragExit

dropActionChanged

dragDropEnd

dragMouseMoved

getTransferable

updateCurrentCursor