Whole document tree

2.2 Drag Gesture Recognition

The gesture(s) that can initiate a Drag and Drop operation vary, not only per platform, but also per Component, and per device. Therefore a mechanism is required in order to encapsulate these dependencies, thus making the task of the author of a Component that wishes to initiate a Drag and Drop operation much simpler.

2.2.1 DragGestureRecognizer

The DragGestureRecognizer is an abstract base class for all device/platform/Component specific Drag and Drop gesture recognizers, and is defined as:

public abstract DragGestureRecognizer {
    protected DragGestureRecognizer(
				DragSource          ds,
				Component           c,
				int                 srcActions,
				DragGestureListener dgl
    );

    public Component getComponent();
    public void      setComponent(Component c);

    public int  getSourceActions();
    public void setSourceActions(int actions);
    
    public java.awt.InputEvent getTriggerEvent();

    public void resetRecognizer();

    public void addDragGestureListener(
                    DragGestureListener dgl
    ) throws TooManyListenerExceptions;

    public void removeDragGestureListener(
                    DragGestureListener dgl
    );

    protected abstract void registerListeners();
    protected abstract void unregisterListeners();

    protected void fireDragGestureRecognized(
                       int dragAction
    );

    protected void appendEvent(InputEvent awtie);
}

An appropriate concrete subclasses of DragGestureRecognizer for a particular may be obtained in a variety of ways; from a DragSource instance, from the Toolkit, or by other means. Concrete implementation subclasses are obtained through standard APIs' by specifying a Class reference to an abstract DragGestureRecognizer superclass, an instance of a concrete subclass of this actual parameter is instantiated and returned to the requestor.

Once a DragGestureRecognizer instance is associated with a Component and a DragSource it registers its own particular set of EventListeners' with the target Component in order to monitor the appropriate events being delivered to that Component to detect an initiating gesture. (Using registerListeners() and unregisterListeners() to add/remove these monitoring EventListeners').

Note that a DragGestureRecognizer may throw either an IllegalStateException or an IllegalArgumentException if either the Component or DragSource specified is either not in the correct state for, or is not interoperable with, that DragGestureRecognizer.

When a concrete DragGestureRecognizer instance detects a Drag initiating user gesture on the Component it is associated with, it will fire a DragGestureEvent to the DragGestureListener registered on its unicast event source for DragGestureListener events. This DragGestureListener is responsible for causing the associated DragSource to start the Drag and Drop operation (if appropriate).

The implementation provides (at least) an abstract subclass for recognizing mouse device gestures MouseDragGestureRecognizer. Other abstract subclasses may be provided by the platform to support other input devices or particular Component class semantics. Concrete superclasses of this MouseDragGestureRecognizer that encapsulate platform dependent mouse based gestures are available from the Toolkit object via its createDragGestureRecognizer(Class adgrc, DragSource ds, Component c, int sa, DragGestureListener dgl) method. This Toolkit API provides platform dependent concrete implementations that extend particular platform independent abstract definitions (classes).

The MouseDragGestureRecognizer abstract class is defined as:

public abstract   MouseDragGestureRecognizer
       extends    DragGestureRecognizer
	  implements MouseListener, MouseMotionListener {

    public MouseDragGestureRecognizer(
			DragSource          ds,
			Component           c,
			int                 sa,
			DragGestureListener dsl
    );
   
    // ...                      
}

The DragGestureListener is defined as:

public interface DragGestureListener extends EventListener {
    void dragGestureRecognized(DragGestureEvent dge);
}

Usually the dragGestureRecognized() method will simply, via the DragGestureEvent's convenience API startDrag(), start a Drag and Drop operation on the associated DragSource.

Note that per Component (class or instance) behavior that may effect the initiating gesture would usually be implemented in this DragGestureListener method, or in the DragGestureRecognizer subclass where appropriate or possible.

The DragGestureEvent is defined as:

publc class DragGestureEvent extends EventObject {
	public DragGestureEvent(DragGestureRecognizer dgr,
                             int                   dragAction,
                             java.util.List        events
     );

    public DragGestureRecognizer
               getSourceAsDragGestureRecognizer();

    public Component  getComponent();
    public DragSource getDragSource();

    public java.util.Iterator iterator();

    public Object[] toArray();
    public Object[] toArray(Object[] array);

    public int getDragAction();

    public startDrag(Cursor             dragCursor,
                     Transferable       t,
                     DragSourceListener dsl
    );
   
    public startDrag(Cursor             dragCursor,
                     Image              dragImage,
                     Point              imageOffset,
                     Transferable       t,
                     DragSourceListener dsl
    );
}

The DragGestureEvent encapsulates all the information regarding the nature of the gesture that has just been recognized, including:

• The DragGestureRecognizer that recognized the gesture
• The Component that the gesture occurred on
• The DragSource that will process the operation
• The List of InputEvent objects that comprise the gesture.
• The action (ACTION_COPY, ACTION_MOVE or ACTION_LINK, selected by the users gesture.