001 /*
002 * Copyright 1997-2003 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt.dnd;
027
028 import java.util.EventListener;
029
030 /**
031 * The <code>DragSourceListener</code> defines the
032 * event interface for originators of
033 * Drag and Drop operations to track the state of the user's gesture, and to
034 * provide appropriate "drag over"
035 * feedback to the user throughout the
036 * Drag and Drop operation.
037 * <p>
038 * The drop site is <i>associated with the previous <code>dragEnter()</code>
039 * invocation</i> if the latest invocation of <code>dragEnter()</code> on this
040 * listener:
041 * <ul>
042 * <li>corresponds to that drop site and
043 * <li> is not followed by a <code>dragExit()</code> invocation on this listener.
044 * </ul>
045 *
046 * @version 1.27, 05/05/07
047 * @since 1.2
048 */
049
050 public interface DragSourceListener extends EventListener {
051
052 /**
053 * Called as the cursor's hotspot enters a platform-dependent drop site.
054 * This method is invoked when all the following conditions are true:
055 * <UL>
056 * <LI>The cursor's hotspot enters the operable part of a platform-
057 * dependent drop site.
058 * <LI>The drop site is active.
059 * <LI>The drop site accepts the drag.
060 * </UL>
061 *
062 * @param dsde the <code>DragSourceDragEvent</code>
063 */
064 void dragEnter(DragSourceDragEvent dsde);
065
066 /**
067 * Called as the cursor's hotspot moves over a platform-dependent drop site.
068 * This method is invoked when all the following conditions are true:
069 * <UL>
070 * <LI>The cursor's hotspot has moved, but still intersects the
071 * operable part of the drop site associated with the previous
072 * dragEnter() invocation.
073 * <LI>The drop site is still active.
074 * <LI>The drop site accepts the drag.
075 * </UL>
076 *
077 * @param dsde the <code>DragSourceDragEvent</code>
078 */
079 void dragOver(DragSourceDragEvent dsde);
080
081 /**
082 * Called when the user has modified the drop gesture.
083 * This method is invoked when the state of the input
084 * device(s) that the user is interacting with changes.
085 * Such devices are typically the mouse buttons or keyboard
086 * modifiers that the user is interacting with.
087 *
088 * @param dsde the <code>DragSourceDragEvent</code>
089 */
090 void dropActionChanged(DragSourceDragEvent dsde);
091
092 /**
093 * Called as the cursor's hotspot exits a platform-dependent drop site.
094 * This method is invoked when any of the following conditions are true:
095 * <UL>
096 * <LI>The cursor's hotspot no longer intersects the operable part
097 * of the drop site associated with the previous dragEnter() invocation.
098 * </UL>
099 * OR
100 * <UL>
101 * <LI>The drop site associated with the previous dragEnter() invocation
102 * is no longer active.
103 * </UL>
104 * OR
105 * <UL>
106 * <LI> The drop site associated with the previous dragEnter() invocation
107 * has rejected the drag.
108 * </UL>
109 *
110 * @param dse the <code>DragSourceEvent</code>
111 */
112 void dragExit(DragSourceEvent dse);
113
114 /**
115 * This method is invoked to signify that the Drag and Drop
116 * operation is complete. The getDropSuccess() method of
117 * the <code>DragSourceDropEvent</code> can be used to
118 * determine the termination state. The getDropAction() method
119 * returns the operation that the drop site selected
120 * to apply to the Drop operation. Once this method is complete, the
121 * current <code>DragSourceContext</code> and
122 * associated resources become invalid.
123 *
124 * @param dsde the <code>DragSourceDropEvent</code>
125 */
126 void dragDropEnd(DragSourceDropEvent dsde);
127 }
|