/*
* Copyright (c) 1998, 2014, 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 {@code DragGestureEvent} is passed
* to {@code DragGestureListener}'s
* dragGestureRecognized() method
* when a particular {@code DragGestureRecognizer} detects that a
* platform dependent drag initiating gesture has occurred
* on the {@code Component} 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 {@code DragGestureEvent} object given by the
* {@code DragGestureRecognizer} 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).
*
* @param dgr The {@code DragGestureRecognizer} 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} of events that comprise the gesture
*
* @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 {@code DragGestureRecognizer}.
*
* @return the source as a {@code DragGestureRecognizer}
*/
public DragGestureRecognizer getSourceAsDragGestureRecognizer() {
return (DragGestureRecognizer)getSource();
}
/**
* Returns the {@code Component} associated
* with this {@code DragGestureEvent}.
*
* @return the Component
*/
public Component getComponent() { return component; }
/**
* Returns the {@code DragSource}.
*
* @return the {@code DragSource}
*/
public DragSource getDragSource() { return dragSource; }
/**
* Returns a {@code Point} in the coordinates
* of the {@code Component} over which the drag originated.
*
* @return the Point where the drag originated in Component coords.
*/
public Point getDragOrigin() {
return origin;
}
/**
* Returns an {@code Iterator} for the events
* comprising the gesture.
*
* @return an Iterator for the events comprising the gesture
*/
@SuppressWarnings("unchecked")
public Iterator<InputEvent> iterator() { return events.iterator(); }
/**
* Returns an {@code Object} array of the
* events comprising the drag gesture.
*
* @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.
*
* @param array the array of {@code EventObject} sub(types)
*
* @return an array of the events comprising the gesture
*/
@SuppressWarnings("unchecked")
public Object[] toArray(Object[] array) { return events.toArray(array); }
/**
* Returns an {@code int} representing the
* action selected by the user.
*
* @return the action selected by the user
*/
public int getDragAction() { return action; }
/**
* Returns the initial event that triggered the gesture.
*
* @return the first "triggering" event in the sequence of the gesture
*/
public InputEvent getTriggerEvent() {
return getSourceAsDragGestureRecognizer().getTriggerEvent();
}
/**
* Starts the drag operation given the {@code Cursor} for this drag
* operation and the {@code Transferable} representing the source data
* for this drag operation.
* <br>
* If a {@code null Cursor} is specified no exception will
* be thrown and default drag cursors will be used instead.
* <br>
* If a {@code null Transferable} is specified
* {@code NullPointerException} 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} 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 {@code Cursor} to display,
* the {@code Transferable} object,
* and the {@code DragSourceListener} to use.
*
* @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
*
* @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 {@code Cursor} to display,
* a drag {@code Image}, the offset of
* the {@code Image},
* the {@code Transferable} object, and
* the {@code DragSourceListener} to use.
*
* @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
*
* @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 {@code DragGestureEvent}. Performs default
* serialization and then writes out this object's {@code List} of
* gesture events if and only if the {@code List} can be serialized.
* If not, {@code null} is written instead. In this case, a
* {@code DragGestureEvent} created from the resulting deserialized
* stream will contain an empty {@code List} of gesture events.
*
* @serialData The default serializable fields, in alphabetical order,
* followed by either a {@code List} instance, or
* {@code null}.
* @since 1.4
*/
private void writeObject(ObjectOutputStream s) throws IOException {
s.defaultWriteObject();
s.writeObject(SerializationTester.test(events) ? events : null);
}
/**
* Deserializes this {@code DragGestureEvent}. This method first
* performs default deserialization for all non-{@code transient}
* fields. An attempt is then made to deserialize this object's
* {@code List} of gesture events as well. This is first attempted
* by deserializing the field {@code events}, because, in releases
* prior to 1.4, a non-{@code transient} field of this name stored the
* {@code List} of gesture events. If this fails, the next object in
* the stream is used instead. If the resulting {@code List} is
* {@code null}, this object's {@code List} of gesture events
* is set to an empty {@code List}.
*
* @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
@SuppressWarnings("rawtypes")
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
*/
private DragSource dragSource;
/**
* The Component associated with this DragGestureEvent.
*
* @serial
*/
private Component component;
/**
* The origin of the drag.
*
* @serial
*/
private Point origin;
/**
* The user's preferred action.
*
* @serial
*/
private int action;
}