| I l@ve RuBoard |
|
24.3 The Drag Gesture APINow that the drop side is working, how do we make the drag side go? First, we need a bit of background information. To successfully accomplish a drag in Java, we must first recognize what constitutes a drag gesture. A drag gesture is an action the user takes to indicate that she's starting a drag. Typically, this is a mouse drag event, but it is not hard to imagine other gestures that could be used. For example, a voice-activated system might listen for the words "pick up" or something similar. The API for drag gestures is fairly simple. Four DnD classes and interfaces make up the core: DragGestureRecognizer, MouseDragGestureRecognizer, DragGestureListener, and DragGestureEvent, as shown in Figure 24-4. Figure 24-4. Drag recognition class diagram 24.3.1 The DragGestureRecognizer ClassAt the heart of this API is the DragGestureRecognizer class. Basically, the recognizer is responsible for recognizing a sequence of events that says "start dragging." This can be quite different for different platforms, so the DragGestureRecognizer class is abstract and must be subclassed to create an appropriate implementation. (The MouseDragGestureRecognizer takes a few more steps to complete the class and makes assumptions about using a mouse as the trigger for drag events. You can use the toolkit on your system to retrieve a concrete version.) This sounds more complex than it is. The idea is that you attach a drag gesture recognizer to a component with code similar to this: JLabel jl = new JLabel("Drag Me!");
DragSource ds = new DragSource( );
DragGestureRecognizer dgr = ds.createDefaultDragGestureRecognizer(
jl, DnDConstants.ACTION_COPY, this);
Now when you click on the jl label and start dragging, a drag gesture is recognized. The system then reports that recognition to your application through any registered DragGestureListener. An example is shown later in this section. 24.3.1.1 PropertiesThe DragGestureRecognizer uses the properties in Table 24-12 to hold information about a drag operation.
The component property refers to the component registered as the source for possible drag initiations. The dragSource property represents a DragSource object that wraps the component that are generating drags in much the same way that a DropTarget object wraps components that are receiving drops. The sourceActions property is the set of acceptable drag operations (coming from DnDConstants) for the drag source. The triggerEvent returns the first in a list of events that led to this recognizer declaring that a drag started. If no drag is currently recognized, this property is null. 24.3.1.2 EventsAs mentioned before, the DragGestureRecognizer reports its events to a DragGestureListener and sends a DragGestureEvent. The usual add and remove methods for the listener are available.
24.3.1.3 FieldsDragGestureRecognizer defines the following fields:
24.3.1.4 ConstructorsAll of the constructors for DragGestureRecognizer are protected. Because the class is abstract, a subclass is needed to create an instance of DragGestureRecognizer anyway. In real programs, you would use the DragSource.createDefaultDragGestureRecognizer( ) method or the Toolkit.createDragGestureRecognizer( ) method to build a recognizer.
24.3.1.5 Trigger event list methodsSince it is possible a sequence of events (such as pressing the Tab key and then dragging the mouse) is responsible for causing a drag, the following methods help set up the list of trigger events correctly:
24.3.2 The MouseDragGestureRecognizer ClassFor many applications, we use the mouse drag as the drag gesture. The MouseDragGestureRecognizer class implements the appropriate recognizer functions for us. Note that this class is still abstract. Individual platforms must subclass it and fill out the specifics of what constitutes a valid drag initiation. However, this class does make it much easier to create your own recognizer than to start from the DragGestureRecognizer class directly. As you start playing with DnD functionality, you will probably rely on the prebuilt recognizers you can retrieve from the DragSource class. 24.3.2.1 ConstructorsThe MouseDragGestureRecognizer class contains the same set of constructors found in its parent class:
24.3.2.2 Mouse methodsBecause this class recognizes gestures started by mouse events, it implements both the MouseListener and MouseMotionListener interfaces. The following methods come from these interfaces:
24.3.2.3 Listener methodsThis class implements the two abstract methods inherited from DragGestureListener:
24.3.3 The Drag Gesture Events and ListenersThe DragGestureListener interface provides one method to indicate whether a drag gesture has been recognized:
The DragGestureEvent provides you with everything you need to know about the drag the user has initiated. If you like everything you see, you can start the drag process. If something is wrong (the wrong action, the wrong object to drag, the application is not in a draggable mode, etc.), you can ignore the gesture. 24.3.3.1 PropertiesMost of the properties stored in a DragGestureEvent provide convenient access to similar properties in the DragGestureRecognizer that generated the event. These are listed in Table 24-13.
The dragOrigin property corresponds to the location of the mouse when the gesture was recognized. The sourceAsDragGestureRecognizer property is merely a convenience property allowing you to access the source of the event as a DragGestureRecognizer rather than as an Object, which is what happens with the source property inherited from the EventObject class. 24.3.3.2 Event list methodsIn discussing the DragGestureRecognizer fields, we noted that several events can be sequenced together to create a drag. The entire list of these events can be retrieved with these methods:
24.3.3.3 Drag initiation methodsWe worry about DragGestureEvent objects because they have the mechanism for starting a drag operation. These methods are required to get a drag underway and usually appear in your dragGestureRecognized( ) method. Now you can package the data to be dragged and pick a cursor to indicate that a successful drag start has occurred. (You can pick one of the cursors predefined in the DragSource class. See Table 24-15 for a complete list.) This sounds worse than it is. Be sure to look at the example code to get an idea of the relatively small amount of programming required.
24.3.4 A Simple GestureWhile they won't do us any good by themselves, we need to familiarize ourselves with these drag gestures before we can do anything with the DnD process. (This must be done in the 1.3 and 1.2 SDKs. In the 1.4 SDK, we need to do this only if we want more control over the drag process.) Here's a simple example of a JList object that will eventually contain draggable list items. Right now, we'll just make sure that we can recognize a drag gesture when it happens in our list object. /*
* GestureTest.java
* A simple (?) test of the DragSource classes to
* create a draggable object in a Java application
*/
import java.awt.*;
import java.awt.dnd.*;
import java.awt.datatransfer.*;
import java.awt.event.*;
import java.io.*;
import java.util.*;
import javax.swing.*;
public class GestureTest extends JFrame {
DragSource ds;
JList jl;
String[] items = {"Java", "C", "C++", "Lisp", "Perl", "Python"};
public GestureTest( ) {
super("Gesture Test");
setSize(200,150);
setDefaultCloseOperation(EXIT_ON_CLOSE);
// Create a JList object and add it to our application.
jl = new JList(items);
jl.setSelectionMode(ListSelectionModel.SINGLE_SELECTION);
getContentPane( ).add(new JScrollPane(jl), BorderLayout.CENTER);
// Now create a DragRecognizer with the DragSource class; you can
// use a Toolkit if you prefer. Notice that we specify our JList
// object when creating the recognizer, not when creating the drag
// source.
ds = new DragSource( );
DragGestureRecognizer dgr = ds.createDefaultDragGestureRecognizer(
jl, DnDConstants.ACTION_COPY,
new DragGestureListener( ) {
// Report the recognized drag event to the console.
public void dragGestureRecognized(DragGestureEvent dge) {
System.out.println("Drag Gesture Recognized!");
}
});
setVisible(true);
}
public static void main(String args[]) {
new GestureTest( );
}
}
 |
| I l@ve RuBoard |
|