/*
* Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.awt.dnd;
import java.awt.Component;
import java.awt.Cursor;
import java.awt.Image;
import java.awt.Point;
import java.awt.event.InputEvent;
import java.awt.datatransfer.Transferable;
import java.io.InvalidObjectException;
import java.util.EventObject;
import java.util.Collections;
import java.util.List;
import java.util.Iterator;
import java.io.IOException;
import java.io.ObjectInputStream;
import java.io.ObjectOutputStream;
A DragGestureEvent
is passed
to DragGestureListener
's
dragGestureRecognized() method
when a particular DragGestureRecognizer
detects that a
platform dependent drag initiating gesture has occurred
on the Component
that it is tracking. The action
field of any DragGestureEvent
instance should take one of the following values:
-
DnDConstants.ACTION_COPY
-
DnDConstants.ACTION_MOVE
-
DnDConstants.ACTION_LINK
Assigning the value different from listed above will cause an unspecified behavior.
See Also:
/**
* A <code>DragGestureEvent</code> is passed
* to <code>DragGestureListener</code>'s
* dragGestureRecognized() method
* when a particular <code>DragGestureRecognizer</code> detects that a
* platform dependent drag initiating gesture has occurred
* on the <code>Component</code> that it is tracking.
*
* The {@code action} field of any {@code DragGestureEvent} instance should take one of the following
* values:
* <ul>
* <li> {@code DnDConstants.ACTION_COPY}
* <li> {@code DnDConstants.ACTION_MOVE}
* <li> {@code DnDConstants.ACTION_LINK}
* </ul>
* Assigning the value different from listed above will cause an unspecified behavior.
*
* @see java.awt.dnd.DragGestureRecognizer
* @see java.awt.dnd.DragGestureListener
* @see java.awt.dnd.DragSource
* @see java.awt.dnd.DnDConstants
*/
public class DragGestureEvent extends EventObject {
private static final long serialVersionUID = 9080172649166731306L;
Constructs a DragGestureEvent
object given by the
DragGestureRecognizer
instance firing this event, an act
parameter representing the user's preferred action, an ori
parameter indicating the origin of the drag, and a List
of events that comprise the gesture(evs
parameter).
Params: - dgr – The
DragGestureRecognizer
firing this event - act – The user's preferred action. For information on allowable values, see the class description for
DragGestureEvent
- ori – The origin of the drag
- evs – The
List
of events that comprise the gesture
Throws: - IllegalArgumentException – if any parameter equals
null
- IllegalArgumentException – if the act parameter does not comply with the values given in the class description for
DragGestureEvent
See Also:
/**
* Constructs a <code>DragGestureEvent</code> object given by the
* <code>DragGestureRecognizer</code> instance firing this event,
* an {@code act} parameter representing
* the user's preferred action, an {@code ori} parameter
* indicating the origin of the drag, and a {@code List} of
* events that comprise the gesture({@code evs} parameter).
* <P>
* @param dgr The <code>DragGestureRecognizer</code> firing this event
* @param act The user's preferred action.
* For information on allowable values, see
* the class description for {@link DragGestureEvent}
* @param ori The origin of the drag
* @param evs The <code>List</code> of events that comprise the gesture
* <P>
* @throws IllegalArgumentException if any parameter equals {@code null}
* @throws IllegalArgumentException if the act parameter does not comply with
* the values given in the class
* description for {@link DragGestureEvent}
* @see java.awt.dnd.DnDConstants
*/
public DragGestureEvent(DragGestureRecognizer dgr, int act, Point ori,
List<? extends InputEvent> evs)
{
super(dgr);
if ((component = dgr.getComponent()) == null)
throw new IllegalArgumentException("null component");
if ((dragSource = dgr.getDragSource()) == null)
throw new IllegalArgumentException("null DragSource");
if (evs == null || evs.isEmpty())
throw new IllegalArgumentException("null or empty list of events");
if (act != DnDConstants.ACTION_COPY &&
act != DnDConstants.ACTION_MOVE &&
act != DnDConstants.ACTION_LINK)
throw new IllegalArgumentException("bad action");
if (ori == null) throw new IllegalArgumentException("null origin");
events = evs;
action = act;
origin = ori;
}
Returns the source as a DragGestureRecognizer
.
Returns: the source as a DragGestureRecognizer
/**
* Returns the source as a <code>DragGestureRecognizer</code>.
* <P>
* @return the source as a <code>DragGestureRecognizer</code>
*/
public DragGestureRecognizer getSourceAsDragGestureRecognizer() {
return (DragGestureRecognizer)getSource();
}
Returns the Component
associated
with this DragGestureEvent
.
Returns: the Component
/**
* Returns the <code>Component</code> associated
* with this <code>DragGestureEvent</code>.
* <P>
* @return the Component
*/
public Component getComponent() { return component; }
Returns the DragSource
.
Returns: the DragSource
/**
* Returns the <code>DragSource</code>.
* <P>
* @return the <code>DragSource</code>
*/
public DragSource getDragSource() { return dragSource; }
Returns a Point
in the coordinates
of the Component
over which the drag originated.
Returns: the Point where the drag originated in Component coords.
/**
* Returns a <code>Point</code> in the coordinates
* of the <code>Component</code> over which the drag originated.
* <P>
* @return the Point where the drag originated in Component coords.
*/
public Point getDragOrigin() {
return origin;
}
Returns an Iterator
for the events
comprising the gesture.
Returns: an Iterator for the events comprising the gesture
/**
* Returns an <code>Iterator</code> for the events
* comprising the gesture.
* <P>
* @return an Iterator for the events comprising the gesture
*/
@SuppressWarnings("unchecked")
public Iterator<InputEvent> iterator() { return events.iterator(); }
Returns an Object
array of the
events comprising the drag gesture.
Returns: an array of the events comprising the gesture
/**
* Returns an <code>Object</code> array of the
* events comprising the drag gesture.
* <P>
* @return an array of the events comprising the gesture
*/
public Object[] toArray() { return events.toArray(); }
Returns an array of the events comprising the drag gesture.
Params: - array – the array of
EventObject
sub(types)
Returns: an array of the events comprising the gesture
/**
* Returns an array of the events comprising the drag gesture.
* <P>
* @param array the array of <code>EventObject</code> sub(types)
* <P>
* @return an array of the events comprising the gesture
*/
@SuppressWarnings("unchecked")
public Object[] toArray(Object[] array) { return events.toArray(array); }
Returns an int
representing the
action selected by the user.
Returns: the action selected by the user
/**
* Returns an <code>int</code> representing the
* action selected by the user.
* <P>
* @return the action selected by the user
*/
public int getDragAction() { return action; }
Returns the initial event that triggered the gesture.
Returns: the first "triggering" event in the sequence of the gesture
/**
* Returns the initial event that triggered the gesture.
* <P>
* @return the first "triggering" event in the sequence of the gesture
*/
public InputEvent getTriggerEvent() {
return getSourceAsDragGestureRecognizer().getTriggerEvent();
}
Starts the drag operation given the Cursor
for this drag
operation and the Transferable
representing the source data
for this drag operation.
If a null
Cursor
is specified no exception will
be thrown and default drag cursors will be used instead.
If a null
Transferable
is specified
NullPointerException
will be thrown.
Params: - dragCursor – The initial
Cursor
for this drag operation or null
for the default cursor handling; see DragSourceContext
for more details on the cursor handling mechanism
during drag and drop - transferable – The
Transferable
representing the source
data for this drag operation.
Throws: - 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.
- NullPointerException – if the
Transferable
is null
Since: 1.4
/**
* Starts the drag operation given the <code>Cursor</code> for this drag
* operation and the <code>Transferable</code> representing the source data
* for this drag operation.
* <br>
* If a <code>null</code> <code>Cursor</code> is specified no exception will
* be thrown and default drag cursors will be used instead.
* <br>
* If a <code>null</code> <code>Transferable</code> is specified
* <code>NullPointerException</code> will be thrown.
* @param dragCursor The initial {@code Cursor} for this drag operation
* or {@code null} for the default cursor handling;
* see
* <a href="DragSourceContext.html#defaultCursor">DragSourceContext</a>
* for more details on the cursor handling mechanism
* during drag and drop
* @param transferable The <code>Transferable</code> representing the source
* data for this drag operation.
*
* @throws 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.
* @throws NullPointerException if the {@code Transferable} is {@code null}
* @since 1.4
*/
public void startDrag(Cursor dragCursor, Transferable transferable)
throws InvalidDnDOperationException {
dragSource.startDrag(this, dragCursor, transferable, null);
}
Starts the drag given the initial Cursor
to display,
the Transferable
object,
and the DragSourceListener
to use.
Params: - dragCursor – The initial
Cursor
for this drag operation or null
for the default cursor handling; see DragSourceContext
for more details on the cursor handling mechanism
during drag and drop - transferable – The source's Transferable
- dsl – The source's DragSourceListener
Throws: - 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.
/**
* Starts the drag given the initial <code>Cursor</code> to display,
* the <code>Transferable</code> object,
* and the <code>DragSourceListener</code> to use.
* <P>
* @param dragCursor The initial {@code Cursor} for this drag operation
* or {@code null} for the default cursor handling;
* see
* <a href="DragSourceContext.html#defaultCursor">DragSourceContext</a>
* for more details on the cursor handling mechanism
* during drag and drop
* @param transferable The source's Transferable
* @param dsl The source's DragSourceListener
* <P>
* @throws 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.
*/
public void startDrag(Cursor dragCursor, Transferable transferable, DragSourceListener dsl) throws InvalidDnDOperationException {
dragSource.startDrag(this, dragCursor, transferable, dsl);
}
Start the drag given the initial Cursor
to display,
a drag Image
, the offset of
the Image
,
the Transferable
object, and
the DragSourceListener
to use.
Params: - dragCursor – The initial
Cursor
for this drag operation or null
for the default cursor handling; see DragSourceContext
for more details on the cursor handling mechanism
during drag and drop - dragImage – The source's dragImage
- imageOffset – The dragImage's offset
- transferable – The source's Transferable
- dsl – The source's DragSourceListener
Throws: - 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.
/**
* Start the drag given the initial <code>Cursor</code> to display,
* a drag <code>Image</code>, the offset of
* the <code>Image</code>,
* the <code>Transferable</code> object, and
* the <code>DragSourceListener</code> to use.
* <P>
* @param dragCursor The initial {@code Cursor} for this drag operation
* or {@code null} for the default cursor handling;
* see
* <a href="DragSourceContext.html#defaultCursor">DragSourceContext</a>
* for more details on the cursor handling mechanism
* during drag and drop
* @param dragImage The source's dragImage
* @param imageOffset The dragImage's offset
* @param transferable The source's Transferable
* @param dsl The source's DragSourceListener
* <P>
* @throws 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.
*/
public void startDrag(Cursor dragCursor, Image dragImage, Point imageOffset, Transferable transferable, DragSourceListener dsl) throws InvalidDnDOperationException {
dragSource.startDrag(this, dragCursor, dragImage, imageOffset, transferable, dsl);
}
Serializes this DragGestureEvent
. Performs default
serialization and then writes out this object's List
of
gesture events if and only if the List
can be serialized.
If not, null
is written instead. In this case, a
DragGestureEvent
created from the resulting deserialized
stream will contain an empty List
of gesture events.
@serialData The default serializable fields, in alphabetical order,
followed by either a List
instance, or
null
. Since: 1.4
/**
* Serializes this <code>DragGestureEvent</code>. Performs default
* serialization and then writes out this object's <code>List</code> of
* gesture events if and only if the <code>List</code> can be serialized.
* If not, <code>null</code> is written instead. In this case, a
* <code>DragGestureEvent</code> created from the resulting deserialized
* stream will contain an empty <code>List</code> of gesture events.
*
* @serialData The default serializable fields, in alphabetical order,
* followed by either a <code>List</code> instance, or
* <code>null</code>.
* @since 1.4
*/
private void writeObject(ObjectOutputStream s) throws IOException {
s.defaultWriteObject();
s.writeObject(SerializationTester.test(events) ? events : null);
}
Deserializes this DragGestureEvent
. This method first
performs default deserialization for all non-transient
fields. An attempt is then made to deserialize this object's
List
of gesture events as well. This is first attempted
by deserializing the field events
, because, in releases
prior to 1.4, a non-transient
field of this name stored the
List
of gesture events. If this fails, the next object in
the stream is used instead. If the resulting List
is
null
, this object's List
of gesture events
is set to an empty List
.
Since: 1.4
/**
* Deserializes this <code>DragGestureEvent</code>. This method first
* performs default deserialization for all non-<code>transient</code>
* fields. An attempt is then made to deserialize this object's
* <code>List</code> of gesture events as well. This is first attempted
* by deserializing the field <code>events</code>, because, in releases
* prior to 1.4, a non-<code>transient</code> field of this name stored the
* <code>List</code> of gesture events. If this fails, the next object in
* the stream is used instead. If the resulting <code>List</code> is
* <code>null</code>, this object's <code>List</code> of gesture events
* is set to an empty <code>List</code>.
*
* @since 1.4
*/
private void readObject(ObjectInputStream s)
throws ClassNotFoundException, IOException
{
ObjectInputStream.GetField f = s.readFields();
DragSource newDragSource = (DragSource)f.get("dragSource", null);
if (newDragSource == null) {
throw new InvalidObjectException("null DragSource");
}
dragSource = newDragSource;
Component newComponent = (Component)f.get("component", null);
if (newComponent == null) {
throw new InvalidObjectException("null component");
}
component = newComponent;
Point newOrigin = (Point)f.get("origin", null);
if (newOrigin == null) {
throw new InvalidObjectException("null origin");
}
origin = newOrigin;
int newAction = f.get("action", 0);
if (newAction != DnDConstants.ACTION_COPY &&
newAction != DnDConstants.ACTION_MOVE &&
newAction != DnDConstants.ACTION_LINK) {
throw new InvalidObjectException("bad action");
}
action = newAction;
// Pre-1.4 support. 'events' was previously non-transient
List newEvents;
try {
newEvents = (List)f.get("events", null);
} catch (IllegalArgumentException e) {
// 1.4-compatible byte stream. 'events' was written explicitly
newEvents = (List)s.readObject();
}
// Implementation assumes 'events' is never null.
if (newEvents != null && newEvents.isEmpty()) {
// Constructor treats empty events list as invalid value
// Throw exception if serialized list is empty
throw new InvalidObjectException("empty list of events");
} else if (newEvents == null) {
newEvents = Collections.emptyList();
}
events = newEvents;
}
/*
* fields
*/
@SuppressWarnings("rawtypes")
private transient List events;
The DragSource associated with this DragGestureEvent.
@serial
/**
* The DragSource associated with this DragGestureEvent.
*
* @serial
*/
private DragSource dragSource;
The Component associated with this DragGestureEvent.
@serial
/**
* The Component associated with this DragGestureEvent.
*
* @serial
*/
private Component component;
The origin of the drag.
@serial
/**
* The origin of the drag.
*
* @serial
*/
private Point origin;
The user's preferred action.
@serial
/**
* The user's preferred action.
*
* @serial
*/
private int action;
}