/*

 * Copyright (c) 1997, 2006, 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.GraphicsEnvironment;

import java.awt.HeadlessException;

import java.awt.Image;

import java.awt.Point;

import java.awt.Toolkit;

import java.awt.datatransfer.FlavorMap;

import java.awt.datatransfer.SystemFlavorMap;

import java.awt.datatransfer.Transferable;

import java.awt.dnd.peer.DragSourceContextPeer;

import java.io.IOException;

import java.io.ObjectInputStream;

import java.io.ObjectOutputStream;

import java.io.Serializable;

import java.security.AccessController;

import java.util.EventListener;

import sun.awt.dnd.SunDragSourceContextPeer;

import sun.security.action.GetIntegerAction;

/**

 * The <code>DragSource</code> is the entity responsible

 * for the initiation of the Drag

 * and Drop operation, and may be used in a number of scenarios:

 * <UL>

 * <LI>1 default instance per JVM for the lifetime of that JVM.

 * <LI>1 instance per class of potential Drag Initiator object (e.g

 * TextField). [implementation dependent]

 * <LI>1 per instance of a particular

 * <code>Component</code>, or application specific

 * object associated with a <code>Component</code>

 * instance in the GUI. [implementation dependent]

 * <LI>Some other arbitrary association. [implementation dependent]

 *</UL>

 *

 * Once the <code>DragSource</code> is

 * obtained, a <code>DragGestureRecognizer</code> should

 * also be obtained to associate the <code>DragSource</code>

 * with a particular

 * <code>Component</code>.

 * <P>

 * The initial interpretation of the user's gesture,

 * and the subsequent starting of the drag operation

 * are the responsibility of the implementing

 * <code>Component</code>, which is usually

 * implemented by a <code>DragGestureRecognizer</code>.

 *<P>

 * When a drag gesture occurs, the

 * <code>DragSource</code>'s

 * startDrag() method shall be

 * invoked in order to cause processing

 * of the user's navigational

 * gestures and delivery of Drag and Drop

 * protocol notifications. A

 * <code>DragSource</code> shall only

 * permit a single Drag and Drop operation to be

 * current at any one time, and shall

 * reject any further startDrag() requests

 * by throwing an <code>IllegalDnDOperationException</code>

 * until such time as the extant operation is complete.

 * <P>

 * The startDrag() method invokes the

 * createDragSourceContext() method to

 * instantiate an appropriate

 * <code>DragSourceContext</code>

 * and associate the <code>DragSourceContextPeer</code>

 * with that.

 * <P>

 * If the Drag and Drop System is

 * unable to initiate a drag operation for

 * some reason, the startDrag() method throws

 * a <code>java.awt.dnd.InvalidDnDOperationException</code>

 * to signal such a condition. Typically this

 * exception is thrown when the underlying platform

 * system is either not in a state to

 * initiate a drag, or the parameters specified are invalid.

 * <P>

 * Note that during the drag, the

 * set of operations exposed by the source

 * at the start of the drag operation may not change

 * until the operation is complete.

 * The operation(s) are constant for the

 * duration of the operation with respect to the

 * <code>DragSource</code>.

 *

 * @since 1.2

 */

public class DragSource implements Serializable {

    private static final long serialVersionUID = 6236096958971414066L;

    /*

     * load a system default cursor

     */

    private static Cursor load(String name) {

        if (GraphicsEnvironment.isHeadless()) {

            return null;

        }

        try {

            return (Cursor)Toolkit.getDefaultToolkit().getDesktopProperty(name);

        } catch (Exception e) {

            e.printStackTrace();

            throw new RuntimeException("failed to load system cursor: " + name + " : " + e.getMessage());

        }

    }

    /**

     * The default <code>Cursor</code> to use with a copy operation indicating

     * that a drop is currently allowed. <code>null</code> if

     * <code>GraphicsEnvironment.isHeadless()</code> returns <code>true</code>.

     *

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public static final Cursor DefaultCopyDrop =

        load("DnD.Cursor.CopyDrop");

    /**

     * The default <code>Cursor</code> to use with a move operation indicating

     * that a drop is currently allowed. <code>null</code> if

     * <code>GraphicsEnvironment.isHeadless()</code> returns <code>true</code>.

     *

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public static final Cursor DefaultMoveDrop =

        load("DnD.Cursor.MoveDrop");

    /**

     * The default <code>Cursor</code> to use with a link operation indicating

     * that a drop is currently allowed. <code>null</code> if

     * <code>GraphicsEnvironment.isHeadless()</code> returns <code>true</code>.

     *

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public static final Cursor DefaultLinkDrop =

        load("DnD.Cursor.LinkDrop");

    /**

     * The default <code>Cursor</code> to use with a copy operation indicating

     * that a drop is currently not allowed. <code>null</code> if

     * <code>GraphicsEnvironment.isHeadless()</code> returns <code>true</code>.

     *

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public static final Cursor DefaultCopyNoDrop =

        load("DnD.Cursor.CopyNoDrop");

    /**

     * The default <code>Cursor</code> to use with a move operation indicating

     * that a drop is currently not allowed. <code>null</code> if

     * <code>GraphicsEnvironment.isHeadless()</code> returns <code>true</code>.

     *

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public static final Cursor DefaultMoveNoDrop =

        load("DnD.Cursor.MoveNoDrop");

    /**

     * The default <code>Cursor</code> to use with a link operation indicating

     * that a drop is currently not allowed. <code>null</code> if

     * <code>GraphicsEnvironment.isHeadless()</code> returns <code>true</code>.

     *

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public static final Cursor DefaultLinkNoDrop =

        load("DnD.Cursor.LinkNoDrop");

    private static final DragSource dflt =

        (GraphicsEnvironment.isHeadless()) ? null : new DragSource();

    /**

     * Internal constants for serialization.

     */

    static final String dragSourceListenerK = "dragSourceL";

    static final String dragSourceMotionListenerK = "dragSourceMotionL";

    /**

     * Gets the <code>DragSource</code> object associated with

     * the underlying platform.

     *

     * @return the platform DragSource

     * @exception HeadlessException if GraphicsEnvironment.isHeadless()

     *            returns true

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public static DragSource getDefaultDragSource() {

        if (GraphicsEnvironment.isHeadless()) {

            throw new HeadlessException();

        } else {

            return dflt;

        }

    }

    /**

     * Reports

     * whether or not drag

     * <code>Image</code> support

     * is available on the underlying platform.

     * <P>

     * @return if the Drag Image support is available on this platform

     */

    public static boolean isDragImageSupported() {

        Toolkit t = Toolkit.getDefaultToolkit();

        Boolean supported;

        try {

            supported = (Boolean)Toolkit.getDefaultToolkit().getDesktopProperty("DnD.isDragImageSupported");

            return supported.booleanValue();

        } catch (Exception e) {

            return false;

        }

    }

    /**

     * Creates a new <code>DragSource</code>.

     *

     * @exception HeadlessException if GraphicsEnvironment.isHeadless()

     *            returns true

     * @see java.awt.GraphicsEnvironment#isHeadless

     */

    public DragSource() throws HeadlessException {

        if (GraphicsEnvironment.isHeadless()) {

            throw new HeadlessException();

        }

    }

    /**

     * Start a drag, given the <code>DragGestureEvent</code>

     * that initiated the drag, the initial

     * <code>Cursor</code> to use,

     * the <code>Image</code> to drag,

     * the offset of the <code>Image</code> origin

     * from the hotspot of the <code>Cursor</code> at

     * the instant of the trigger,

     * the <code>Transferable</code> subject data

     * of the drag, the <code>DragSourceListener</code>,

     * and the <code>FlavorMap</code>.

     * <P>

     * @param trigger        the <code>DragGestureEvent</code> that initiated the drag

     * @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 image to drag or {@code null}

     * @param imageOffset    the offset of the <code>Image</code> origin from the hotspot

     *                       of the <code>Cursor</code> at the instant of the trigger

     * @param transferable   the subject data of the drag

     * @param dsl            the <code>DragSourceListener</code>

     * @param flavorMap      the <code>FlavorMap</code> to use, or <code>null</code>

     * <P>

     * @throws java.awt.dnd.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(DragGestureEvent   trigger,

                          Cursor             dragCursor,

                          Image              dragImage,

                          Point              imageOffset,

                          Transferable       transferable,

                          DragSourceListener dsl,

                          FlavorMap          flavorMap) throws InvalidDnDOperationException {

        SunDragSourceContextPeer.setDragDropInProgress(true);

        try {

            if (flavorMap != null) this.flavorMap = flavorMap;

            DragSourceContextPeer dscp = Toolkit.getDefaultToolkit().createDragSourceContextPeer(trigger);

            DragSourceContext     dsc = createDragSourceContext(dscp,

                                                                trigger,

                                                                dragCursor,

                                                                dragImage,

                                                                imageOffset,

                                                                transferable,

                                                                dsl

                                                                );

            if (dsc == null) {

                throw new InvalidDnDOperationException();

            }

            dscp.startDrag(dsc, dsc.getCursor(), dragImage, imageOffset); // may throw

        } catch (RuntimeException e) {

            SunDragSourceContextPeer.setDragDropInProgress(false);

            throw e;

        }

    }

    /**

     * Start a drag, given the <code>DragGestureEvent</code>

     * that initiated the drag, the initial

     * <code>Cursor</code> to use,

     * the <code>Transferable</code> subject data

     * of the drag, the <code>DragSourceListener</code>,

     * and the <code>FlavorMap</code>.

     * <P>

     * @param trigger        the <code>DragGestureEvent</code> that

     * initiated the drag

     * @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 subject data of the drag

     * @param dsl            the <code>DragSourceListener</code>

     * @param flavorMap      the <code>FlavorMap</code> to use or <code>null</code>

     * <P>

     * @throws java.awt.dnd.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(DragGestureEvent   trigger,

                          Cursor             dragCursor,

                          Transferable       transferable,

                          DragSourceListener dsl,

                          FlavorMap          flavorMap) throws InvalidDnDOperationException {

        startDrag(trigger, dragCursor, null, null, transferable, dsl, flavorMap);

    }

    /**

     * Start a drag, given the <code>DragGestureEvent</code>

     * that initiated the drag, the initial <code>Cursor</code>

     * to use,

     * the <code>Image</code> to drag,

     * the offset of the <code>Image</code> origin

     * from the hotspot of the <code>Cursor</code>

     * at the instant of the trigger,

     * the subject data of the drag, and

     * the <code>DragSourceListener</code>.

     * <P>

     * @param trigger           the <code>DragGestureEvent</code> that initiated the drag

     * @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 <code>Image</code> to drag or <code>null</code>

     * @param dragOffset        the offset of the <code>Image</code> origin from the hotspot

     *                          of the <code>Cursor</code> at the instant of the trigger

     * @param transferable      the subject data of the drag

     * @param dsl               the <code>DragSourceListener</code>

     * <P>

     * @throws java.awt.dnd.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(DragGestureEvent   trigger,

                          Cursor             dragCursor,

                          Image              dragImage,

                          Point              dragOffset,

                          Transferable       transferable,

                          DragSourceListener dsl) throws InvalidDnDOperationException {

        startDrag(trigger, dragCursor, dragImage, dragOffset, transferable, dsl, null);

    }

    /**

     * Start a drag, given the <code>DragGestureEvent</code>

     * that initiated the drag, the initial

     * <code>Cursor</code> to

     * use,

     * the <code>Transferable</code> subject data

     * of the drag, and the <code>DragSourceListener</code>.

     * <P>

     * @param trigger           the <code>DragGestureEvent</code> that initiated the drag

     * @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> class

     *                       for more details on the cursor handling mechanism during drag and drop

     * @param transferable      the subject data of the drag

     * @param dsl               the <code>DragSourceListener</code>

     * <P>

     * @throws java.awt.dnd.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(DragGestureEvent   trigger,

                          Cursor             dragCursor,

                          Transferable       transferable,

                          DragSourceListener dsl) throws InvalidDnDOperationException {

        startDrag(trigger, dragCursor, null, null, transferable, dsl, null);

    }

    /**

     * Creates the {@code DragSourceContext} to handle the current drag

     * operation.

     * <p>

     * To incorporate a new <code>DragSourceContext</code>

     * subclass, subclass <code>DragSource</code> and

     * override this method.

     * <p>

     * If <code>dragImage</code> is <code>null</code>, no image is used

     * to represent the drag over feedback for this drag operation, but

     * <code>NullPointerException</code> is not thrown.

     * <p>

     * If <code>dsl</code> is <code>null</code>, no drag source listener

     * is registered with the created <code>DragSourceContext</code>,

     * but <code>NullPointerException</code> is not thrown.

     *

     * @param dscp          The <code>DragSourceContextPeer</code> for this drag

     * @param dgl           The <code>DragGestureEvent</code> that triggered the

     *                      drag

     * @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> class

     *                       for more details on the cursor handling mechanism during drag and drop

     * @param dragImage     The <code>Image</code> to drag or <code>null</code>

     * @param imageOffset   The offset of the <code>Image</code> origin from the

     *                      hotspot of the cursor at the instant of the trigger

     * @param t             The subject data of the drag

     * @param dsl           The <code>DragSourceListener</code>

     *

     * @return the <code>DragSourceContext</code>

     *

     * @throws NullPointerException if <code>dscp</code> is <code>null</code>

     * @throws NullPointerException if <code>dgl</code> is <code>null</code>

     * @throws NullPointerException if <code>dragImage</code> is not

     *    <code>null</code> and <code>imageOffset</code> is <code>null</code>

     * @throws NullPointerException if <code>t</code> is <code>null</code>

     * @throws IllegalArgumentException if the <code>Component</code>

     *         associated with the trigger event is <code>null</code>.

     * @throws IllegalArgumentException if the <code>DragSource</code> for the

     *         trigger event is <code>null</code>.

     * @throws IllegalArgumentException if the drag action for the

     *         trigger event is <code>DnDConstants.ACTION_NONE</code>.

     * @throws IllegalArgumentException if the source actions for the

     *         <code>DragGestureRecognizer</code> associated with the trigger

     *         event are equal to <code>DnDConstants.ACTION_NONE</code>.

     */

    protected DragSourceContext createDragSourceContext(DragSourceContextPeer dscp, DragGestureEvent dgl, Cursor dragCursor, Image dragImage, Point imageOffset, Transferable t, DragSourceListener dsl) {

        return new DragSourceContext(dscp, dgl, dragCursor, dragImage, imageOffset, t, dsl);

    }

    /**

     * This method returns the

     * <code>FlavorMap</code> for this <code>DragSource</code>.

     * <P>

     * @return the <code>FlavorMap</code> for this <code>DragSource</code>

     */

    public FlavorMap getFlavorMap() { return flavorMap; }

    /**

     * Creates a new <code>DragGestureRecognizer</code>

     * that implements the specified

     * abstract subclass of

     * <code>DragGestureRecognizer</code>, and

     * sets the specified <code>Component</code>

     * and <code>DragGestureListener</code> on

     * the newly created object.

     * <P>

     * @param recognizerAbstractClass the requested abstract type

     * @param actions                 the permitted source drag actions

     * @param c                       the <code>Component</code> target

     * @param dgl        the <code>DragGestureListener</code> to notify

     * <P>

     * @return the new <code>DragGestureRecognizer</code> or <code>null</code>

     *    if the <code>Toolkit.createDragGestureRecognizer</code> method

     *    has no implementation available for

     *    the requested <code>DragGestureRecognizer</code>

     *    subclass and returns <code>null</code>

     */

    public <T extends DragGestureRecognizer> T

        createDragGestureRecognizer(Class<T> recognizerAbstractClass,

                                    Component c, int actions,

                                    DragGestureListener dgl)

    {

        return Toolkit.getDefaultToolkit().createDragGestureRecognizer(recognizerAbstractClass, this, c, actions, dgl);

    }

    /**

     * Creates a new <code>DragGestureRecognizer</code>

     * that implements the default

     * abstract subclass of <code>DragGestureRecognizer</code>

     * for this <code>DragSource</code>,

     * and sets the specified <code>Component</code>

     * and <code>DragGestureListener</code> on the

     * newly created object.

     *

     * For this <code>DragSource</code>