A
DragGestureEvent
is handed to a
dragGestureRecognized
event handler when the user tries to start a drag and drop operation,
which usually happens when mouse button 1 held down while the cursor
is dragged a short distance.
The operation starts if the component's
dragGestureRecognized
event handler returns an
Object
(other than
NULL)
that is supposed to be transferred by the drag and drop operation,
and at that point other drag and drop event handlers may be called.
Incidentally, an active drag and drop operation can always be canceled
using the
ESC
key.
DragGestureEvent
is one of three special drag and drop events that currently do not
behave like the AWT and Swing events that you may be familiar with.
For example, Swing provides automatic drag handling for some components
that must be disabled by storing
NULL
in the component's
transferhandler
field before drag and drop event handlers will start working.
A
DragGestureEvent
also can not be assigned to an
Event
object or posted to a component using
postEvent.
In addition,
DragGestureEvent
contains special fields, like
anchor,
cursor,
offset,
padding,
and
visual,
that
dragGestureRecognized
can change when it wants more control over the drag and drop operation.
The fields in a
DragGestureEvent
are:
| anchor |
An
int
that together with
padding
and
offset
control the positioning of
visual,
if it is not
NULL,
relative to the cursor's hotspot.
The value should be
CENTER
(rarely used),
EAST,
NORTH,
NORTHEAST,
NORTHWEST,
SOUTH
(the default) ,
SOUTHEAST,
SOUTHWEST,
WEST,
or
NONE,
which are all defined in
yoix.awt
and
yoix.swing.
An event handler that wants better control over the placement of
visual
should set
anchor
to
NONE,
padding
to a small distance, and
offset
to a
Point
that represents the displacement of the upper left corner of
visual
from the cursor's hotspot.
These settings guarantee that a
visual
that ends up in a window will not be made visible or moved until
the cursor's hotspot moves outside the imaginary
padding
that we place around that window.
| | coordinates |
A
Point
that indicates where the cursor's hotspot was at the time of the event.
The
coordinates
and
location
fields may or may not match, but
coordinates
should only be used by event handlers that are defined in drawable objects
(i.e., components that define a
graphics
field).
In that case
coordinates
will be the location of the cursor's hotspot in the coordinate system
described by the drawable object's
graphics.CTM
at the time the event arrived, otherwise
coordinates
and
location
will match.
| | cursor |
An
Object
that can be an
int,
Image,
or
String
that represents the cursor shown during the drag and drop operation.
A
NULL
value is special and means Java's drag and drop machinery picks the cursor.
A
cursor
that is an
int
should be one of the cursors defined in the
yoix.awt.Cursor
dictionary.
A
cursor
that is an
Image
can describe the cursor using its
size
and
hotspot
fields and often draws it using its
paint
function.
A
cursor
that is a
String
should be the name of a cursor that is already defined in
yoix.awt.Cursor
or the name a local a file or URL that contains a GIF or JPEG image
that will be used as the cursor.
The
cursor
field in the
DragGestureEvent
that is received by a
dragGestureRecognized
event handler will be
NULL,
but the event handler can change it when it wants to pick the cursor
that will be used when the operation starts.
| | dragimagesupported |
An
int
that is
1
when a separate image stored in the
visual
field can be dragged along with the cursor and
0
when it can not.
The only platform that we have seen support drag images is Mac OSX.
However, if your event handler stores an image in
visual
and drag images are not supported, or you disable them by storing
0
in
dragimagesupported,
then we will try to put the image in a special window and automatically
drag that window around with the cursor.
| | id |
An
Object
that must be an
int
or
String,
that identifies the type of this event.
A value that is a
String
must be the name of an event handler that can process this event.
A value that is an
int
must be a number that the
yoix.event.HandlerID
dictionary associates with an event handler that can process this event.
| | location |
A
Point
that indicates where the cursor's hotspot was at the time of the event.
location
always describes a point in the component that
requested the event in a coordinate system that has its origin
at that component's upper left corner, positive x to the right,
positive y down, and a resolution of 72 dots per inch.
| | maximumsize |
A
Dimension
that limits the size of a drag window that is automatically created when
visual
is a
String
or
Color.
The default value is calculated as a fraction (e.g. one third)
of your screen.
Storing
NULL
in
maximumsize
means there is no limit.
maximumsize
is not currently used when
visual
is an
Image
or
Window.
| | modifiers |
An
int
that is a bitmask that tries to record the state of the mouse buttons
and keyboard modifiers at the time of the event.
Unfortunately, mouse button and keyboard modifier flags overlap
(e.g.,
BUTTON2_MASK
and
ALT_MASK
match), so
modifiers
can not record the state of all mouse buttons and keyboard modifiers,
however reliable information about them is available in
modifiersdown.
modifiers
and
modifiersdown
use disjoint sets of bits as flags, so make sure you test
modifiers
using some combination of
BUTTON1_MASK,
BUTTON2_MASK,
BUTTON3_MASK,
SHIFT_MASK,
CTRL_MASK,
ALT_MASK,
META_MASK,
and
ALT_GRAPH_MASK,
which are defined in
yoix.awt
and
yoix.swing.
Also available are
BUTTON_MASK
and
KEY_MASK,
which are convenient combinations that can be used to test for
any mouse button or any keyboard modifier.
| | modifiersdown |
An
int
that is a bitmask that represents the state of all keyboard modifiers
and mouse buttons when the event occurred.
modifiersdown
and
modifiers
use disjoint sets of bits as flags, so make sure you test
modifiersdown
using some combination of
BUTTON1_DOWN_MASK,
BUTTON2_DOWN_MASK,
BUTTON3_DOWN_MASK,
SHIFT_DOWN_MASK,
CTRL_DOWN_MASK,
ALT_DOWN_MASK,
META_DOWN_MASK,
and
ALT_GRAPH_DOWN_MASK,
which are defined in
yoix.awt
and
yoix.swing.
Also available are
BUTTON_DOWN_MASK
and
KEY_DOWN_MASK,
which are convenient combinations that can be used to test for
any mouse button or any keyboard modifier.
| | offset |
A
Point
that together with
anchor
and
padding
control the positioning of
visual,
if it is not
NULL,
relative to the cursor's hotspot.
In practice
offset
is only used when a
dragGestureRecognized
event handler sets
anchor
to
NONE,
and in that case it should be a
Point
that represents the displacement of the upper left corner of
visual
from the cursor's hotspot.
In other words,
offset
is where the upper left corner of
visual
belongs in a coordinate system that has its origin at
location,
positive x to the right, positive y down, and a resolution of 72 dots per inch.
| | padding |
A
Number
that controls the spacing, in units of 72 dots per inch,
between the cursor's hotspot and a
visual
object that can be dragged along with the cursor.
Where the actual padding is applied depends on the value assigned to
anchor.
| | screenlocation |
A
Point
that indicates where on the screen the cursor's hotspot was
at the time of the event.
screenlocation
always describes a point on the screen in a coordinate system
that has its origin at upper left corner of the screen,
positive x to the right, positive y down,
and a resolution of 72 dots per inch.
| | visual |
An
Object
that is
NULL
by default, but can be set to an
Image,
String,
Color,
or
Window
when a
dragGestureRecognized
event handler wants to have an image or window dragged along with the cursor.
A
visual
that is a
String
is displayed as a single line of text in a window that has its size
limited by
maximumsize.
A
visual
that is a
Color
is used as the background color of a small window.
A
visual
that is a
Window
is the window that is made visible and dragged along with the cursor
during the drag and drop operation.
The
anchor,
offset,
and
padding
fields control the placement of
visual
relative to the cursor's hotspot.
| | when |
A
double
that is a timestamp that represents when the event occurred.
|
| |
| Event Handlers: |
dragGestureRecognized
| | |
| Example: |
The program,
import yoix.*.*;
JFrame f = {
String title = "Drag and Drop Test";
double border = 72/12;
Dimension size = NULL;
GridLayout layoutmanager = {
int rows = 2;
};
Array layout = {
new JPanel {
String border = "Default drag and drop handling";
Array layout = {
new JTextField {
int columns = 40;
int dragenabled = TRUE;
},
};
},
new JLabel {
String text = "Now is the time for all good men...";
String border = "Custom drag from or drop handling";
Object transferhandler = NULL; // just in case
Color foreground = Color.blue;
int alignment = LEADING;
dragGestureRecognized(DragGestureEvent e) {
//
// The return value, if it's not NULL, is what
// gets transferred.
//
e.visual = text;
e.anchor = SOUTH;
e.padding = 72/4;
return(text);
}
dragEnter(DropTargetEvent e) {
return(TRUE); // accept anything
}
drop(DropTargetEvent e) {
//
// See what happens to the text in TextField when
// we return nothing or FALSE.
//
if (e.transferable instanceof String)
text = e.transferable;
return(TRUE);
}
},
};
};
f.visible = TRUE;
is a simple example that uses event handlers to implement drag and drop
in the label and uses Swing's automatic drag and drop handling in the
textfield.
| | |
| See Also: |
ActionEvent,
AdjustmentEvent,
CaretEvent,
ChangeEvent,
ComponentEvent,
DragSourceEvent,
DropTargetEvent,
Event,
FocusEvent,
HyperlinkEvent,
InvocationEvent,
invokeLater,
isDispatchThread,
ItemEvent,
KeyEvent,
ListSelectionEvent,
MouseEvent,
MouseWheelEvent,
PaintEvent,
postEvent,
TextEvent,
TreeSelectionEvent,
WindowEvent
|
|
