Whole document tree


www.fifi.org
    Documentation
        Manpages
        GNU Info
        Debian document tree
        Whole document tree
    Trigance web page
    Public services
    User info
    Mailing lists
    Secure server
    Multilingual usage
 

Copyright (C) 2000-2012
Philippe Troin
<webmaster@fifi.org>.

Validate HTML
Validate CSS

    

Whole document tree

Java 2 Platform SE v1.3.1: Class DragSource
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
JavaTM 2 Platform
Std. Ed. v1.3.1
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD

java.awt.dnd
Class DragSource

java.lang.Object
  |
  +--java.awt.dnd.DragSource
public class DragSource
extends Object

The DragSource is the entity responsible for the initiation of the Drag and Drop operation, and may be used in a number of scenarios:

  • 1 default instance per JVM for the lifetime of that JVM.
  • 1 instance per class of potential Drag Initiator object (e.g TextField). [implementation dependent]
  • 1 per instance of a particular Component, or application specific object associated with a Component instance in the GUI. [implementation dependent]
  • Some other arbitrary association. [implementation dependent]
Once the DragSource is obtained, a DragGestureRecognizer should also be obtained to associate the DragSource with a particular Component.

The initial interpretation of the user's gesture, and the subsequent starting of the drag operation are the responsibility of the implementing Component, which is usually implemented by a DragGestureRecognizer.

When a drag gesture occurs, the DragSource's startDrag() method shall be invoked in order to cause processing of the user's navigational gestures and delivery of Drag and Drop protocol notifications. A DragSource shall only permit a single Drag and Drop operation to be current at any one time, and shall reject any further startDrag() requests by throwing an IllegalDnDOperationException until such time as the extant operation is complete.

The startDrag() method invokes the createDragSourceContext() method to instantiate an appropriate DragSourceContext and associate the DragSourceContextPeer with that.

If the Drag and Drop System is unable to initiate a drag operation for some reason, the startDrag() method throws a java.awt.dnd.InvalidDnDOperationException to signal such a condition. Typically this exception is thrown when the underlying platform system is either not in a state to initiate a drag, or the parameters specified are invalid.

Note that during the drag, the set of operations exposed by the source at the start of the drag operation may not change until the operation is complete. The operation(s) are constant for the duration of the operation with respect to the DragSource.

Since:
1.2

Field Summary
static Cursor DefaultCopyDrop
          The default Cursor to use with a copy operation indicating that a drop is currently allowed.
static Cursor DefaultCopyNoDrop
          The default Cursor to use with a copy operation indicating that a drop is currently not allowed.
static Cursor DefaultLinkDrop
          The default Cursor to use with a link operation indicating that a drop is currently allowed.
static Cursor DefaultLinkNoDrop
          The default Cursor to use with a link operation indicating that a drop is currently not allowed.
static Cursor DefaultMoveDrop
          The default Cursor to use with a move operation indicating that a drop is currently allowed.
static Cursor DefaultMoveNoDrop
          The default Cursor to use with a move operation indicating that a drop is currently not allowed.
 
Constructor Summary
DragSource()
          Construct a new DragSource.
 
Method Summary
 DragGestureRecognizer createDefaultDragGestureRecognizer(Component c, int actions, DragGestureListener dgl)
          Creates a new DragSourceRecognizer that implements the default abstract subclass of DragGestureRecognizer for this DragSource, and sets the specified Component and DragGestureListener on the newly created object.
 DragGestureRecognizer createDragGestureRecognizer(Class recognizerAbstractClass, Component c, int actions, DragGestureListener dgl)
          Creates a new DragGestureRecognizer that implements the specified abstract subclass of DragGestureRecognizer, and sets the specified Component and DragGestureListener on the newly created object.
protected  DragSourceContext createDragSourceContext(java.awt.dnd.peer.DragSourceContextPeer dscp, DragGestureEvent dgl, Cursor dragCursor, Image dragImage, Point imageOffset, Transferable t, DragSourceListener dsl)
          Create the DragSourceContext to handle this drag.
static DragSource getDefaultDragSource()
          This method returns the DragSource object associated with the underlying platform.
 FlavorMap getFlavorMap()
          This method returns the FlavorMap for this DragSource.
static boolean isDragImageSupported()
          This method returns a boolean indicating whether or not drag Image support is available on the underlying platform.
 void startDrag(DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point dragOffset, Transferable transferable, DragSourceListener dsl)
          Start a drag, given the DragGestureEvent that initiated the drag, the initial Cursor to use, the Image to drag, the offset of the Image origin from the hotspot of the Cursor at the instant of the trigger, the subject data of the drag, and the DragSourceListener.
 void startDrag(DragGestureEvent trigger, Cursor dragCursor, Image dragImage, Point imageOffset, Transferable transferable, DragSourceListener dsl, FlavorMap flavorMap)
          Start a drag, given the DragGestureEvent that initiated the drag, the initial Cursor to use, the Image to drag, the offset of the Image origin from the hotspot of the Cursor at the instant of the trigger, the Transferable subject data of the drag, the DragSourceListener, and the FlavorMap.
 void startDrag(DragGestureEvent trigger, Cursor dragCursor, Transferable transferable, DragSourceListener dsl)
          Start a drag, given the DragGestureEvent that initiated the drag, the initial Cursor to use, the Transferable subject data of the drag, and the DragSourceListener.
 void startDrag(DragGestureEvent trigger, Cursor dragCursor, Transferable transferable, DragSourceListener dsl, FlavorMap flavorMap)
          Start a drag, given the DragGestureEvent that initiated the drag, the initial Cursor to use, the Transferable subject data of the drag, the DragSourceListener, and the FlavorMap.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DefaultCopyDrop

public static final Cursor DefaultCopyDrop
The default Cursor to use with a copy operation indicating that a drop is currently allowed.

DefaultMoveDrop

public static final Cursor DefaultMoveDrop
The default Cursor to use with a move operation indicating that a drop is currently allowed.

DefaultLinkDrop

public static final Cursor DefaultLinkDrop
The default Cursor to use with a link operation indicating that a drop is currently allowed.

DefaultCopyNoDrop

public static final Cursor DefaultCopyNoDrop
The default Cursor to use with a copy operation indicating that a drop is currently not allowed.

DefaultMoveNoDrop

public static final Cursor DefaultMoveNoDrop
The default Cursor to use with a move operation indicating that a drop is currently not allowed.

DefaultLinkNoDrop

public static final Cursor DefaultLinkNoDrop
The default Cursor to use with a link operation indicating that a drop is currently not allowed.
Constructor Detail

DragSource

public DragSource()
Construct a new DragSource.
Method Detail

getDefaultDragSource

public static DragSource getDefaultDragSource()
This method returns the DragSource object associated with the underlying platform.

Returns:
the platform DragSource

isDragImageSupported

public static boolean isDragImageSupported()
This method returns a boolean indicating whether or not drag Image support is available on the underlying platform.

Returns:
if the Drag Image support is available on this platform

startDrag

public void startDrag(DragGestureEvent trigger,
                      Cursor dragCursor,
                      Image dragImage,
                      Point imageOffset,
                      Transferable transferable,
                      DragSourceListener dsl,
                      FlavorMap flavorMap)
               throws InvalidDnDOperationException
Start a drag, given the DragGestureEvent that initiated the drag, the initial Cursor to use, the Image to drag, the offset of the Image origin from the hotspot of the Cursor at the instant of the trigger, the Transferable subject data of the drag, the DragSourceListener, and the FlavorMap.

Parameters:
trigger - The DragGestureEvent that initiated the drag
dragCursor - The initial Cursor or null for defaults
dragImage - The image to drag or null,
imageOffset - The offset of the Image origin from the hotspot of the Cursor at the instant of the trigger
transferable - The subject data of the drag
dsl - The DragSourceListener
flavorMap - The FlavorMap to use, or null

Throws:
java.awt.dnd.InvalidDnDOperationException - if the Drag and Drop system is unable to initiate a drag operation, or if the user attempts to start a drag while an existing drag operation is still executing.

startDrag

public void startDrag(DragGestureEvent trigger,
                      Cursor dragCursor,
                      Transferable transferable,
                      DragSourceListener dsl,
                      FlavorMap flavorMap)
               throws InvalidDnDOperationException
Start a drag, given the DragGestureEvent that initiated the drag, the initial Cursor to use, the Transferable subject data of the drag, the DragSourceListener, and the FlavorMap.

Parameters:
trigger - The DragGestureEvent that initiated the drag
dragCursor - The initial Cursor or null for defaults
transferable - The subject data of the drag
dsl - The DragSourceListener
flavorMap - The FlavorMap to use or null

Throws:
java.awt.dnd.InvalidDnDOperationException - if the Drag and Drop system is unable to initiate a drag operation, or if the user attempts to start a drag while an existing drag operation is still executing.

startDrag

public void startDrag(DragGestureEvent trigger,
                      Cursor dragCursor,
                      Image dragImage,
                      Point dragOffset,
                      Transferable transferable,
                      DragSourceListener dsl)
               throws InvalidDnDOperationException
Start a drag, given the DragGestureEvent that initiated the drag, the initial Cursor to use, the Image to drag, the offset of the Image origin from the hotspot of the Cursor at the instant of the trigger, the subject data of the drag, and the DragSourceListener.

Parameters:
trigger - The DragGestureEvent that initiated the drag
dragCursor - The initial Cursor or null for defaults
dragImage - The Image to drag or null
imageOffset - The offset of the Image origin from the hotspot of the Cursor at the instant of the trigger
transferable - The subject data of the drag
dsl - The DragSourceListener

Throws:
java.awt.dnd.InvalidDnDOperationException - if the Drag and Drop system is unable to initiate a drag operation, or if the user attempts to start a drag while an existing drag operation is still executing.

startDrag

public void startDrag(DragGestureEvent trigger,
                      Cursor dragCursor,
                      Transferable transferable,
                      DragSourceListener dsl)
               throws InvalidDnDOperationException
Start a drag, given the DragGestureEvent that initiated the drag, the initial Cursor to use, the Transferable subject data of the drag, and the DragSourceListener.

Parameters:
trigger - The DragGestureEvent that initiated the drag
dragCursor - The initial Cursor or null for defaults
transferable - The subject data of the drag
dsl - The DragSourceListener

Throws:
java.awt.dnd.InvalidDnDOperationException - if the Drag and Drop system is unable to initiate a drag operation, or if the user attempts to start a drag while an existing drag operation is still executing.

createDragSourceContext

protected DragSourceContext createDragSourceContext(java.awt.dnd.peer.DragSourceContextPeer dscp,
                                                    DragGestureEvent dgl,
                                                    Cursor dragCursor,
                                                    Image dragImage,
                                                    Point imageOffset,
                                                    Transferable t,
                                                    DragSourceListener dsl)
Create the DragSourceContext to handle this drag. To incorporate a new DragSourceContext subclass, subclass DragSource and override this method.

Parameters:
dscp - The DragSourceContextPeer for this drag
trigger - The DragGestureEvent that triggered the drag
dragCursor - The initial Cursor to display
dragImage - The Image to drag or null
imageOffset - The offset of the Image origin from the hotspot of the cursor at the instant of the trigger
transferable - The subject data of the drag
dsl - The DragSourceListener

Returns:
the DragSourceContext

getFlavorMap

public FlavorMap getFlavorMap()
This method returns the FlavorMap for this DragSource.

Returns:
the FlavorMap for this DragSource

createDragGestureRecognizer

public DragGestureRecognizer createDragGestureRecognizer(Class recognizerAbstractClass,
                                                         Component c,
                                                         int actions,
                                                         DragGestureListener dgl)
Creates a new DragGestureRecognizer that implements the specified abstract subclass of DragGestureRecognizer, and sets the specified Component and DragGestureListener on the newly created object.

Parameters:
recognizerAbstractClass - The requested abstract type
actions - The permitted source drag actions
c - The Component target
dgl - The DragGestureListener to notify

Returns:
the new DragGestureRecognizer or null if the Toolkit.createDragGestureRecognizer() method has no implementation available for the requested DragGestureRecognizer subclass and returns null.

createDefaultDragGestureRecognizer

public DragGestureRecognizer createDefaultDragGestureRecognizer(Component c,
                                                                int actions,
                                                                DragGestureListener dgl)
Creates a new DragSourceRecognizer that implements the default abstract subclass of DragGestureRecognizer for this DragSource, and sets the specified Component and DragGestureListener on the newly created object. For this DragSource the default is MouseDragGestureRecognizer.

Parameters:
c - The Component target for the recognizer
actions - The permitted source actions
dgl - The DragGestureListener to notify

Returns:
the new DragGestureRecognizer or null if the Toolkit.createDragGestureRecognizer() method has no implementation available for the requested DragGestureRecognizer subclass and returns null.
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
JavaTM 2 Platform
Std. Ed. v1.3.1
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD
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 Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2001 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.