FileDocCategorySizeDatePackage
DragSourceContext.javaAPI DocJava SE 6 API20863Tue Jun 10 00:25:20 BST 2008java.awt.dnd

DragSourceContext

public class DragSourceContext extends Object implements Serializable, DragSourceMotionListener, DragSourceListener
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.

see
DragSourceListener
see
DragSourceMotionListener
version
1.53, 04/04/06
since
1.2

Fields Summary
private static final long
serialVersionUID
protected static final int
DEFAULT
An int used by updateCurrentCursor() indicating that the Cursor should change to the default (no drop) Cursor.
protected static final int
ENTER
An int used by updateCurrentCursor() indicating that the Cursor has entered a DropTarget.
protected static final int
OVER
An int used by updateCurrentCursor() indicating that the Cursor is over a DropTarget.
protected static final int
CHANGED
An int used by updateCurrentCursor() indicating that the user operation has changed.
private static Transferable
emptyTransferable
private transient DragSourceContextPeer
peer
private DragGestureEvent
trigger
The event which triggered the start of the drag.
private Cursor
cursor
The current drag cursor.
private transient Transferable
transferable
private transient DragSourceListener
listener
private boolean
useCustomCursor
true if the custom drag cursor is used instead of the default one.
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.
Constructors Summary
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.

param
dscp the DragSourceContextPeer for this drag
param
trigger the triggering event
param
dragCursor the initial Cursor
param
dragImage the Image to drag (or null)
param
offset the offset of the image origin from the hotspot at the instant of the triggering event
param
t the Transferable
param
dsl the DragSourceListener
throws
IllegalArgumentException if the Component associated with the trigger event is null.
throws
IllegalArgumentException if the DragSource for the trigger event is null.
throws
IllegalArgumentException if the drag action for the trigger event is DnDConstants.ACTION_NONE.
throws
IllegalArgumentException if the source actions for the DragGestureRecognizer associated with the trigger event are equal to DnDConstants.ACTION_NONE.
throws
NullPointerException if dscp, trigger, or t are null, or if dragImage is non-null and offset is null

	
                                                                                                                                                                                                                                                                                                                                                                                            
       
                                 
                                  
                               
        if (dscp == null) {
            throw new NullPointerException("DragSourceContextPeer");
        }

        if (trigger == null) {
            throw new NullPointerException("Trigger");
        }

        if (trigger.getDragSource() == null) {
            throw new IllegalArgumentException("DragSource");
        }

        if (trigger.getComponent() == null) {
            throw new IllegalArgumentException("Component");
        }

        if (trigger.getSourceAsDragGestureRecognizer().getSourceActions() ==
                 DnDConstants.ACTION_NONE) {
            throw new IllegalArgumentException("source actions");
        }

        if (trigger.getDragAction() == DnDConstants.ACTION_NONE) {
            throw new IllegalArgumentException("no drag action");
        }

        if (t == null) {
            throw new NullPointerException("Transferable");
        }

        if (dragImage != null && offset == null) {
            throw new NullPointerException("offset");
        }
	
        peer         = dscp;
        this.trigger = trigger;
        cursor       = dragCursor;
        transferable = t;
        listener     = dsl;
        sourceActions =
            trigger.getSourceAsDragGestureRecognizer().getSourceActions();

        useCustomCursor = (dragCursor != null);

        updateCurrentCursor(trigger.getDragAction(), getSourceActions(), DEFAULT);
    
Methods Summary
public synchronized voidaddDragSourceListener(java.awt.dnd.DragSourceListener dsl)
Add a DragSourceListener to this DragSourceContext if one has not already been added. If a DragSourceListener already exists, this method throws a TooManyListenersException.

param
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

	if (dsl == null) return;

	if (equals(dsl)) throw new IllegalArgumentException("DragSourceContext may not be its own listener");

	if (listener != null)
	    throw new TooManyListenersException();
	else
	    listener = dsl;
    
public voiddragDropEnd(java.awt.dnd.DragSourceDropEvent dsde)
Calls dragDropEnd on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceDropEvent.

param
dsde the DragSourceDropEvent

        DragSourceListener dsl = listener;
        if (dsl != null) {
            dsl.dragDropEnd(dsde);
        }
        getDragSource().processDragDropEnd(dsde);
    
public voiddragEnter(java.awt.dnd.DragSourceDragEvent dsde)
Calls dragEnter on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceDragEvent.

param
dsde the DragSourceDragEvent

        DragSourceListener dsl = listener;
        if (dsl != null) {
            dsl.dragEnter(dsde);
        }
        getDragSource().processDragEnter(dsde);

	updateCurrentCursor(getSourceActions(), dsde.getTargetActions(), ENTER);
    
public voiddragExit(java.awt.dnd.DragSourceEvent dse)
Calls dragExit on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceEvent.

param
dse the DragSourceEvent

        DragSourceListener dsl = listener;
        if (dsl != null) {
            dsl.dragExit(dse);
        }
        getDragSource().processDragExit(dse);

	updateCurrentCursor(DnDConstants.ACTION_NONE, DnDConstants.ACTION_NONE, DEFAULT);
    
public voiddragMouseMoved(java.awt.dnd.DragSourceDragEvent dsde)
Calls dragMouseMoved on the DragSourceMotionListeners registered with the DragSource associated with this DragSourceContext, and them passes the specified DragSourceDragEvent.

param
dsde the DragSourceDragEvent
since
1.4

        getDragSource().processDragMouseMoved(dsde);
    
public voiddragOver(java.awt.dnd.DragSourceDragEvent dsde)
Calls dragOver on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceDragEvent.

param
dsde the DragSourceDragEvent

        DragSourceListener dsl = listener;
        if (dsl != null) {
            dsl.dragOver(dsde);
        }
        getDragSource().processDragOver(dsde);

	updateCurrentCursor(getSourceActions(), dsde.getTargetActions(), OVER);
    
public voiddropActionChanged(java.awt.dnd.DragSourceDragEvent dsde)
Calls dropActionChanged on the DragSourceListeners registered with this DragSourceContext and with the associated DragSource, and passes them the specified DragSourceDragEvent.

param
dsde the DragSourceDragEvent

        DragSourceListener dsl = listener;
        if (dsl != null) {
            dsl.dropActionChanged(dsde);
        }
        getDragSource().processDropActionChanged(dsde);

	updateCurrentCursor(getSourceActions(), dsde.getTargetActions(), CHANGED);
    
public java.awt.ComponentgetComponent()
Returns the Component associated with this DragSourceContext.

return
the Component that started the drag

 return trigger.getComponent(); 
public java.awt.CursorgetCursor()
Returns the current drag Cursor.

return
the current drag Cursor

 return cursor; 
public java.awt.dnd.DragSourcegetDragSource()
Returns the DragSource that instantiated this DragSourceContext.

return
the DragSource that instantiated this DragSourceContext

 return trigger.getDragSource(); 
public intgetSourceActions()
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.

return
the drop actions supported by the drag source

        return sourceActions;
    
public java.awt.datatransfer.TransferablegetTransferable()
Returns the Transferable associated with this DragSourceContext.

return
the Transferable

 return transferable; 
public java.awt.dnd.DragGestureEventgetTrigger()
Returns the DragGestureEvent that initially triggered the drag.

return
the Event that triggered the drag

 return trigger; 
private voidreadObject(java.io.ObjectInputStream s)
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.

since
1.4

        s.defaultReadObject();

        transferable = (Transferable)s.readObject();
        listener = (DragSourceListener)s.readObject();

        // Implementation assumes 'transferable' is never null.
        if (transferable == null) {
            if (emptyTransferable == null) {
                emptyTransferable = new Transferable() {
                        public DataFlavor[] getTransferDataFlavors() {
                            return new DataFlavor[0];
                        }
                        public boolean isDataFlavorSupported(DataFlavor flavor)
                        {
                            return false;
                        }
                        public Object getTransferData(DataFlavor flavor)
                            throws UnsupportedFlavorException
                        {
                            throw new UnsupportedFlavorException(flavor);
                        }
                    };
            }
            transferable = emptyTransferable;
        }
    
public synchronized voidremoveDragSourceListener(java.awt.dnd.DragSourceListener dsl)
Removes the specified DragSourceListener from this DragSourceContext.

param
dsl the DragSourceListener to remove; note that while null is not prohibited, it is not acceptable as a parameter

	if (listener != null && listener.equals(dsl)) {
	    listener = null;
	} else
	    throw new IllegalArgumentException();
    
public synchronized voidsetCursor(java.awt.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.

param
c the Cursor to display, or null to activate the default drag cursor behavior

        useCustomCursor = (c != null);
        setCursorImpl(c);
    
private voidsetCursorImpl(java.awt.Cursor c)

        if (cursor == null || !cursor.equals(c)) {
            cursor = c;
            if (peer != null) peer.setCursor(cursor);
        }
    
public voidtransferablesFlavorsChanged()
Notifies the peer that the Transferable's DataFlavors have changed.

	if (peer != null) peer.transferablesFlavorsChanged();
    
protected synchronized voidupdateCurrentCursor(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.

param
sourceAct the actions supported by the drag source
param
targetAct the drop target action
param
status one of the fields DEFAULT, ENTER, OVER, CHANGED


	// if the cursor has been previously set then dont do any defaults
	// processing.

	if (useCustomCursor) {
	    return;
	}

	// do defaults processing

	Cursor c = null;

	switch (status) {
	    default:
		targetAct = DnDConstants.ACTION_NONE;
	    case ENTER:
	    case OVER:
	    case CHANGED:
		int    ra = sourceAct & targetAct;

		if (ra == DnDConstants.ACTION_NONE) { // no drop possible
		    if ((sourceAct & DnDConstants.ACTION_LINK) == DnDConstants.ACTION_LINK)
		        c = DragSource.DefaultLinkNoDrop;
		    else if ((sourceAct & DnDConstants.ACTION_MOVE) == DnDConstants.ACTION_MOVE)
		        c = DragSource.DefaultMoveNoDrop;
		    else
		        c = DragSource.DefaultCopyNoDrop;
		} else { // drop possible
		    if ((ra & DnDConstants.ACTION_LINK) == DnDConstants.ACTION_LINK)
		        c = DragSource.DefaultLinkDrop;
		    else if ((ra & DnDConstants.ACTION_MOVE) == DnDConstants.ACTION_MOVE)
		        c = DragSource.DefaultMoveDrop;
		    else
		        c = DragSource.DefaultCopyDrop;
		}
	}

        setCursorImpl(c);
    
private voidwriteObject(java.io.ObjectOutputStream s)
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.

serialData
The default serializable fields, in alphabetical order, followed by either a Transferable instance, or null, followed by either a DragSourceListener instance, or null.
since
1.4

        s.defaultWriteObject();

        s.writeObject(SerializationTester.test(transferable)
                      ? transferable : null);
        s.writeObject(SerializationTester.test(listener)
                      ? listener : null);