1 /*
   2  * Copyright (c) 1997, 2003, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.awt.dnd;
  27 
  28 import java.util.EventListener;
  29 
  30 /**
  31  * The <code>DragSourceListener</code> defines the
  32  * event interface for originators of
  33  * Drag and Drop operations to track the state of the user's gesture, and to
  34  * provide appropriate &quot;drag over&quot;
  35  * feedback to the user throughout the
  36  * Drag and Drop operation.
  37  * <p>
  38  * The drop site is <i>associated with the previous <code>dragEnter()</code>
  39  * invocation</i> if the latest invocation of <code>dragEnter()</code> on this
  40  * listener:
  41  * <ul>
  42  * <li>corresponds to that drop site and
  43  * <li> is not followed by a <code>dragExit()</code> invocation on this listener.
  44  * </ul>
  45  *
  46  * @since 1.2
  47  */
  48 
  49 public interface DragSourceListener extends EventListener {
  50 
  51     /**
  52      * Called as the cursor's hotspot enters a platform-dependent drop site.
  53      * This method is invoked when all the following conditions are true:
  54      * <UL>
  55      * <LI>The cursor's hotspot enters the operable part of a platform-
  56      * dependent drop site.
  57      * <LI>The drop site is active.
  58      * <LI>The drop site accepts the drag.
  59      * </UL>
  60      *
  61      * @param dsde the <code>DragSourceDragEvent</code>
  62      */
  63     void dragEnter(DragSourceDragEvent dsde);
  64 
  65     /**
  66      * Called as the cursor's hotspot moves over a platform-dependent drop site.
  67      * This method is invoked when all the following conditions are true:
  68      * <UL>
  69      * <LI>The cursor's hotspot has moved, but still intersects the
  70      * operable part of the drop site associated with the previous
  71      * dragEnter() invocation.
  72      * <LI>The drop site is still active.
  73      * <LI>The drop site accepts the drag.
  74      * </UL>
  75      *
  76      * @param dsde the <code>DragSourceDragEvent</code>
  77      */
  78     void dragOver(DragSourceDragEvent dsde);
  79 
  80     /**
  81      * Called when the user has modified the drop gesture.
  82      * This method is invoked when the state of the input
  83      * device(s) that the user is interacting with changes.
  84      * Such devices are typically the mouse buttons or keyboard
  85      * modifiers that the user is interacting with.
  86      *
  87      * @param dsde the <code>DragSourceDragEvent</code>
  88      */
  89     void dropActionChanged(DragSourceDragEvent dsde);
  90 
  91     /**
  92      * Called as the cursor's hotspot exits a platform-dependent drop site.
  93      * This method is invoked when any of the following conditions are true:
  94      * <UL>
  95      * <LI>The cursor's hotspot no longer intersects the operable part
  96      * of the drop site associated with the previous dragEnter() invocation.
  97      * </UL>
  98      * OR
  99      * <UL>
 100      * <LI>The drop site associated with the previous dragEnter() invocation
 101      * is no longer active.
 102      * </UL>
 103      * OR
 104      * <UL>
 105      * <LI> The drop site associated with the previous dragEnter() invocation
 106      * has rejected the drag.
 107      * </UL>
 108      *
 109      * @param dse the <code>DragSourceEvent</code>
 110      */
 111     void dragExit(DragSourceEvent dse);
 112 
 113     /**
 114      * This method is invoked to signify that the Drag and Drop
 115      * operation is complete. The getDropSuccess() method of
 116      * the <code>DragSourceDropEvent</code> can be used to
 117      * determine the termination state. The getDropAction() method
 118      * returns the operation that the drop site selected
 119      * to apply to the Drop operation. Once this method is complete, the
 120      * current <code>DragSourceContext</code> and
 121      * associated resources become invalid.
 122      *
 123      * @param dsde the <code>DragSourceDropEvent</code>
 124      */
 125     void dragDropEnd(DragSourceDropEvent dsde);
 126 }