1 /* 2 * @(#)DropTargetListener.java 1.22 03/12/19 3 * 4 * Copyright 2004 Sun Microsystems, Inc. All rights reserved. 5 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. 6 */ 7 8 package java.awt.dnd; 9 10 import java.util.EventListener; 11 12 import java.awt.dnd.DropTargetContext; 13 import java.awt.dnd.DropTargetDragEvent; 14 import java.awt.dnd.DropTargetDropEvent; 15 16 /** 17 * The <code>DropTargetListener</code> interface 18 * is the callback interface used by the 19 * <code>DropTarget</code> class to provide 20 * notification of DnD operations that involve 21 * the subject <code>DropTarget</code>. Methods of 22 * this interface may be implemented to provide 23 * "drag under" visual feedback to the user throughout 24 * the Drag and Drop operation. 25 * <p> 26 * Create a listener object by implementing the interface and then register it 27 * with a <code>DropTarget</code>. When the drag enters, moves over, or exits 28 * the operable part of the drop site for that <code>DropTarget</code>, when 29 * the drop action changes, and when the drop occurs, the relevant method in 30 * the listener object is invoked, and the <code>DropTargetEvent</code> is 31 * passed to it. 32 * <p> 33 * The operable part of the drop site for the <code>DropTarget</code> is 34 * the part of the associated <code>Component</code>'s geometry that is not 35 * obscured by an overlapping top-level window or by another 36 * <code>Component</code> higher in the Z-order that has an associated active 37 * <code>DropTarget</code>. 38 * <p> 39 * During the drag, the data associated with the current drag operation can be 40 * retrieved by calling <code>getTransferable()</code> on 41 * <code>DropTargetDragEvent</code> instances passed to the listener's 42 * methods. 43 * <p> 44 * Note that <code>getTransferable()</code> on the 45 * <code>DropTargetDragEvent</code> instance should only be called within the 46 * respective listener's method and all the necessary data should be retrieved 47 * from the returned <code>Transferable</code> before that method returns. 48 * 49 * @version 1.22, 12/19/03 50 * @since 1.2 51 */ 52 53 public interface DropTargetListener extends EventListener { 54 55 /** 56 * Called while a drag operation is ongoing, when the mouse pointer enters 57 * the operable part of the drop site for the <code>DropTarget</code> 58 * registered with this listener. 59 * 60 * @param dtde the <code>DropTargetDragEvent</code> 61 */ 62 63 void dragEnter(DropTargetDragEvent dtde); 64 65 /** 66 * Called when a drag operation is ongoing, while the mouse pointer is still 67 * over the operable part of the drop site for the <code>DropTarget</code> 68 * registered with this listener. 69 * 70 * @param dtde the <code>DropTargetDragEvent</code> 71 */ 72 73 void dragOver(DropTargetDragEvent dtde); 74 75 /** 76 * Called if the user has modified 77 * the current drop gesture. 78 * <P> 79 * @param dtde the <code>DropTargetDragEvent</code> 80 */ 81 82 void dropActionChanged(DropTargetDragEvent dtde); 83 84 /** 85 * Called while a drag operation is ongoing, when the mouse pointer has 86 * exited the operable part of the drop site for the 87 * <code>DropTarget</code> registered with this listener. 88 * 89 * @param dte the <code>DropTargetEvent</code> 90 */ 91 92 void dragExit(DropTargetEvent dte); 93 94 /** 95 * Called when the drag operation has terminated with a drop on 96 * the operable part of the drop site for the <code>DropTarget</code> 97 * registered with this listener. 98 * <p> 99 * This method is responsible for undertaking 100 * the transfer of the data associated with the 101 * gesture. The <code>DropTargetDropEvent</code> 102 * provides a means to obtain a <code>Transferable</code> 103 * object that represents the data object(s) to 104 * be transfered.<P> 105 * From this method, the <code>DropTargetListener</code> 106 * shall accept or reject the drop via the 107 * acceptDrop(int dropAction) or rejectDrop() methods of the 108 * <code>DropTargetDropEvent</code> parameter. 109 * <P> 110 * Subsequent to acceptDrop(), but not before, 111 * <code>DropTargetDropEvent</code>'s getTransferable() 112 * method may be invoked, and data transfer may be 113 * performed via the returned <code>Transferable</code>'s 114 * getTransferData() method. 115 * <P> 116 * At the completion of a drop, an implementation 117 * of this method is required to signal the success/failure 118 * of the drop by passing an appropriate 119 * <code>boolean</code> to the <code>DropTargetDropEvent</code>'s 120 * dropComplete(boolean success) method. 121 * <P> 122 * Note: The data transfer should be completed before the call to the 123 * <code>DropTargetDropEvent</code>'s dropComplete(boolean success) method. 124 * After that, a call to the getTransferData() method of the 125 * <code>Transferable</code> returned by 126 * <code>DropTargetDropEvent.getTransferable()</code> is guaranteed to 127 * succeed only if the data transfer is local; that is, only if 128 * <code>DropTargetDropEvent.isLocalTransfer()</code> returns 129 * <code>true</code>. Otherwise, the behavior of the call is 130 * implementation-dependent. 131 * <P> 132 * @param dtde the <code>DropTargetDropEvent</code> 133 */ 134 135 void drop(DropTargetDropEvent dtde); 136 } 137 138 139 140 141 142 143 144