1. /*
  2. * @(#)DragSourceListener.java 1.20 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. package java.awt.dnd;
  8. import java.util.EventListener;
  9. /**
  10. * The <code>DragSourceListener</code> defines the
  11. * event interface for originators of
  12. * Drag and Drop operations to track the state of the user's gesture, and to
  13. * provide appropriate "drag over"
  14. * feedback to the user throughout the
  15. * Drag and Drop operation.
  16. * <p>
  17. * The drop site is <i>associated with the previous <code>dragEnter()</code>
  18. * invocation</i> if the latest invocation of <code>dragEnter()</code> on this
  19. * listener:
  20. * <ul>
  21. * <li>corresponds to that drop site and
  22. * <li> is not followed by a <code>dragExit()</code> invocation on this listener.
  23. * </ul>
  24. *
  25. * @version 1.20, 12/19/03
  26. * @since 1.2
  27. */
  28. public interface DragSourceListener extends EventListener {
  29. /**
  30. * Called as the cursor's hotspot enters a platform-dependent drop site.
  31. * This method is invoked when all the following conditions are true:
  32. * <UL>
  33. * <LI>The cursor's hotspot enters the operable part of a platform-
  34. * dependent drop site.
  35. * <LI>The drop site is active.
  36. * <LI>The drop site accepts the drag.
  37. * </UL>
  38. *
  39. * @param dsde the <code>DragSourceDragEvent</code>
  40. */
  41. void dragEnter(DragSourceDragEvent dsde);
  42. /**
  43. * Called as the cursor's hotspot moves over a platform-dependent drop site.
  44. * This method is invoked when all the following conditions are true:
  45. * <UL>
  46. * <LI>The cursor's hotspot has moved, but still intersects the
  47. * operable part of the drop site associated with the previous
  48. * dragEnter() invocation.
  49. * <LI>The drop site is still active.
  50. * <LI>The drop site accepts the drag.
  51. * </UL>
  52. *
  53. * @param dsde the <code>DragSourceDragEvent</code>
  54. */
  55. void dragOver(DragSourceDragEvent dsde);
  56. /**
  57. * Called when the user has modified the drop gesture.
  58. * This method is invoked when the state of the input
  59. * device(s) that the user is interacting with changes.
  60. * Such devices are typically the mouse buttons or keyboard
  61. * modifiers that the user is interacting with.
  62. *
  63. * @param dsde the <code>DragSourceDragEvent</code>
  64. */
  65. void dropActionChanged(DragSourceDragEvent dsde);
  66. /**
  67. * Called as the cursor's hotspot exits a platform-dependent drop site.
  68. * This method is invoked when any of the following conditions are true:
  69. * <UL>
  70. * <LI>The cursor's hotspot no longer intersects the operable part
  71. * of the drop site associated with the previous dragEnter() invocation.
  72. * </UL>
  73. * OR
  74. * <UL>
  75. * <LI>The drop site associated with the previous dragEnter() invocation
  76. * is no longer active.
  77. * </UL>
  78. * OR
  79. * <UL>
  80. * <LI> The drop site associated with the previous dragEnter() invocation
  81. * has rejected the drag.
  82. * </UL>
  83. *
  84. * @param dse the <code>DragSourceEvent</code>
  85. */
  86. void dragExit(DragSourceEvent dse);
  87. /**
  88. * This method is invoked to signify that the Drag and Drop
  89. * operation is complete. The getDropSuccess() method of
  90. * the <code>DragSourceDropEvent</code> can be used to
  91. * determine the termination state. The getDropAction() method
  92. * returns the operation that the drop site selected
  93. * to apply to the Drop operation. Once this method is complete, the
  94. * current <code>DragSourceContext</code> and
  95. * associated resources become invalid.
  96. *
  97. * @param dsde the <code>DragSourceDropEvent</code>
  98. */
  99. void dragDropEnd(DragSourceDropEvent dsde);
  100. }