DropHandler (JNA API)

com.sun.jna.platform.dnd

## Class DropHandler

- java.lang.Object
- - com.sun.jna.platform.dnd.DropHandler

- All Implemented Interfaces:
    java.awt.dnd.DropTargetListener, java.util.EventListener

      public abstract class DropHandler
      extends java.lang.Object
      implements java.awt.dnd.DropTargetListener

  Provides simplified drop handling for a component. Usage:

       int actions = DnDConstants.MOVE_OR_COPY;
       Component component = ...;
       DropHandler handler = new DropHandler(component, actions);

  - Accept drops where the action is the default (i.e. no modifiers) but the intersection of source and target actions is not the default. Doing so allows the source to adjust the cursor appropriately.
  - Refuse drops where the user modifiers request an action that is not supported (this works for all cases except when the drag source is not a `DragHandler` and the user explicitly requests a MOVE operation; this is indistinguishable from a drag with no modifiers unless we have access to the key modifiers, which `DragHandler` provides).
  - Drops may be refused based on data flavor, location, intended drop action, or any combination of those, by overriding `canDrop(java.awt.dnd.DropTargetEvent, int, java.awt.Point)`.
  - Custom decoration of the drop area may be performed in `paintDropTarget(DropTargetEvent, int, Point)` or by providing a `DropTargetPainter`.
  The method `getDropAction(DropTargetEvent)` follows these steps to determine the appropriate action (if any).
  - `isSupported(DataFlavor[])` determines if there are any supported flavors
  - `getDropActionsForFlavors(DataFlavor[])` reduces the supported actions based on available flavors. For instance, a text field for file paths might support `DnDConstants.ACTION_COPY_OR_MOVE` on a plain string, but `DnDConstants.ACTION_LINK` might be the only action supported on a file.
  - `getDropAction(DropTargetEvent, int, int, int)` relax the action if it's the default, or restrict it for user requested actions.
  - `canDrop(DropTargetEvent, int, Point)` change the action based on the location in the drop target component, or any other criteria.
  Override `drop(DropTargetDropEvent, int)` to handle the drop. You should invoke `DropTargetDropEvent.dropComplete(boolean)` as soon as the `Transferable` data is obtained, to avoid making the DnD operation look suspended.
  Author:
    twall
  See Also:
    `DragHandler`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DropHandler(java.awt.Component c, int acceptedActions)` Create a handler that allows the given set of actions.
    `DropHandler(java.awt.Component c, int acceptedActions, java.awt.datatransfer.DataFlavor[] acceptedFlavors)` Enable handling of drops, indicating what actions and flavors are acceptable.
    `DropHandler(java.awt.Component c, int acceptedActions, java.awt.datatransfer.DataFlavor[] acceptedFlavors, DropTargetPainter painter)` Enable handling of drops, indicating what actions and flavors are acceptable, and providing a painter for drop target feedback.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected int` | `acceptOrReject(java.awt.dnd.DropTargetDragEvent e)` Accept or reject the drag represented by the given event.
    `protected boolean` | `canDrop(java.awt.dnd.DropTargetEvent e, int action, java.awt.Point location)` Indicate whether the given drop action is acceptable at the given location.
    `void` | `dragEnter(java.awt.dnd.DropTargetDragEvent e)`
    `void` | `dragExit(java.awt.dnd.DropTargetEvent e)`
    `void` | `dragOver(java.awt.dnd.DropTargetDragEvent e)`
    `void` | `drop(java.awt.dnd.DropTargetDropEvent e)` Indicates the user has initiated a drop.
    `protected abstract void` | `drop(java.awt.dnd.DropTargetDropEvent e, int action)` Handle an incoming drop with the given action.
    `void` | `dropActionChanged(java.awt.dnd.DropTargetDragEvent e)`
    `protected int` | `getDropAction(java.awt.dnd.DropTargetEvent e)` Calculate the effective action.
    `protected int` | `getDropAction(java.awt.dnd.DropTargetEvent e, int currentAction, int sourceActions, int acceptedActions)`
    `protected int` | `getDropActionsForFlavors(java.awt.datatransfer.DataFlavor[] dataFlavors)` Indicate the actions available for the given list of data flavors.
    `protected java.awt.dnd.DropTarget` | `getDropTarget()`
    `boolean` | `isActive()`
    `protected boolean` | `isSupported(java.awt.datatransfer.DataFlavor[] flavors)` Return whether any of the flavors in the given list are accepted.
    `protected boolean` | `modifiersActive(int dropAction)` Returns whether there are key modifiers active , or false if they can't be determined.
    `protected void` | `paintDropTarget(java.awt.dnd.DropTargetEvent e, int action, java.awt.Point location)` Update the appearance of the target component.
    `void` | `setActive(boolean active)` Set whether this handler (and thus its drop target) will accept any drops.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### DropHandler

          public DropHandler(java.awt.Component c,
                     int acceptedActions)

      Create a handler that allows the given set of actions. If using this constructor, you will need to override `isSupported(java.awt.datatransfer.DataFlavor[])` to indicate which data flavors are allowed.
      Parameters:
        `c` - target component
        `acceptedActions` - accepted actions

    - #### DropHandler

          public DropHandler(java.awt.Component c,
                     int acceptedActions,
                     java.awt.datatransfer.DataFlavor[] acceptedFlavors)

      Enable handling of drops, indicating what actions and flavors are acceptable.
      Parameters:
        `c` - The component to receive drops
        `acceptedActions` - Allowed actions for drops
        `acceptedFlavors` - Allowed data flavors for drops
      See Also:
        `isSupported(java.awt.datatransfer.DataFlavor[])`

    - #### DropHandler

          public DropHandler(java.awt.Component c,
                     int acceptedActions,
                     java.awt.datatransfer.DataFlavor[] acceptedFlavors,
                     DropTargetPainter painter)

      Enable handling of drops, indicating what actions and flavors are acceptable, and providing a painter for drop target feedback.
      Parameters:
        `c` - The component to receive drops
        `acceptedActions` - Allowed actions for drops
        `acceptedFlavors` - Allowed data flavors for drops
        `painter` - Painter to handle drop target feedback
      See Also:
        `paintDropTarget(java.awt.dnd.DropTargetEvent, int, java.awt.Point)`

  - ### Method Detail

    - #### getDropTarget

          protected java.awt.dnd.DropTarget getDropTarget()

    - #### isActive

          public boolean isActive()

      Returns:
        Whether this drop target is active.

    - #### setActive

          public void setActive(boolean active)

      Set whether this handler (and thus its drop target) will accept any drops.
      Parameters:
        `active` - whether this handler should accept drops.

    - #### getDropActionsForFlavors

          protected int getDropActionsForFlavors(java.awt.datatransfer.DataFlavor[] dataFlavors)

      Indicate the actions available for the given list of data flavors. Override this method if the acceptable drop actions depend on the currently available `DataFlavor`. The default returns the accepted actions passed into the constructor.
      Parameters:
        `dataFlavors` - currently available flavors
      Returns:
        currently acceptable actions.
      See Also:
        `getDropAction(DropTargetEvent, int, int, int)`, `canDrop(DropTargetEvent, int, Point)`

    - #### getDropAction

          protected int getDropAction(java.awt.dnd.DropTargetEvent e)

      Calculate the effective action. The default implementation checks whether any `DataFlavor`s are supported, and if so, will change the current action from `DnDConstants.ACTION_NONE` to something in common between the source and destination. Refuse user-requested actions if they are not supported (rather than silently accepting a non-user-requested action, which is the Java's DnD default behavior). The drop action is forced to `DnDConstants.ACTION_NONE` if there is no supported data flavor.
      Parameters:
        `e` - `DropTargetEvent`
      Returns:
        effective drop action
      See Also:
        `isSupported(DataFlavor[])`, `getDropActionsForFlavors(java.awt.datatransfer.DataFlavor[])`, `getDropAction(DropTargetEvent, int, int, int)`, `canDrop(DropTargetEvent, int, Point)`

    - #### getDropAction

          protected int getDropAction(java.awt.dnd.DropTargetEvent e,
                          int currentAction,
                          int sourceActions,
                          int acceptedActions)

    - #### modifiersActive

          protected boolean modifiersActive(int dropAction)

      Returns whether there are key modifiers active , or false if they can't be determined. We use the DragHandler hint, if available, or fall back to whether the drop action is other than the default (move).
      Parameters:
        `dropAction` - requested action.
      Returns:
        whether any modifiers are active.

    - #### acceptOrReject

          protected int acceptOrReject(java.awt.dnd.DropTargetDragEvent e)

      Accept or reject the drag represented by the given event. Returns the action determined by `getDropAction(DropTargetEvent)`.
      Parameters:
        `e` - event
      Returns:
        resulting action

    - #### dragEnter

          public void dragEnter(java.awt.dnd.DropTargetDragEvent e)

      Specified by:
        `dragEnter` in interface `java.awt.dnd.DropTargetListener`

    - #### dragOver

          public void dragOver(java.awt.dnd.DropTargetDragEvent e)

      Specified by:
        `dragOver` in interface `java.awt.dnd.DropTargetListener`

    - #### dragExit

          public void dragExit(java.awt.dnd.DropTargetEvent e)

      Specified by:
        `dragExit` in interface `java.awt.dnd.DropTargetListener`

    - #### dropActionChanged

          public void dropActionChanged(java.awt.dnd.DropTargetDragEvent e)

      Specified by:
        `dropActionChanged` in interface `java.awt.dnd.DropTargetListener`

    - #### drop

          public void drop(java.awt.dnd.DropTargetDropEvent e)

      Indicates the user has initiated a drop. The default performs all standard drop validity checking and handling, then invokes `drop(DropTargetDropEvent,int)` if the drop looks acceptable.
      Specified by:
        `drop` in interface `java.awt.dnd.DropTargetListener`

    - #### isSupported

          protected boolean isSupported(java.awt.datatransfer.DataFlavor[] flavors)

      Return whether any of the flavors in the given list are accepted. The list is compared against the accepted list provided in the constructor.
      Parameters:
        `flavors` - list of transfer flavors to check
      Returns:
        whether any of the given flavors are supported

    - #### paintDropTarget

          protected void paintDropTarget(java.awt.dnd.DropTargetEvent e,
                             int action,
                             java.awt.Point location)

      Update the appearance of the target component. Normally the decoration should be painted only if the event is an instance of `DropTargetDragEvent` with an action that is not `DragHandler.NONE`. Otherwise the decoration should be removed or hidden.

      For an easy way to highlight the drop target, consider using a single instance of `AbstractComponentDecorator` and moving it according to the intended drop location.

      Parameters:
        `e` - The drop target event
        `action` - The action for the drop
        `location` - The intended drop location, or null if there is none

    - #### canDrop

          protected boolean canDrop(java.awt.dnd.DropTargetEvent e,
                        int action,
                        java.awt.Point location)

      Indicate whether the given drop action is acceptable at the given location. This method is the last check performed by `getDropAction(DropTargetEvent)`. You may override this method to refuse drops on certain areas within the drop target component. The default always returns true.
      Parameters:
        `e` - event
        `action` - requested action
        `location` - requested drop location
      Returns:
        whether the drop is supported

    - #### drop

          protected abstract void drop(java.awt.dnd.DropTargetDropEvent e,
                  int action)
                                throws java.awt.datatransfer.UnsupportedFlavorException,
                                       java.io.IOException

      Handle an incoming drop with the given action. The action passed in might be different from `DropTargetDropEvent.getDropAction()`, for instance, if there are no modifiers and the default action is not supported. Calling `DropTargetDropEvent.dropComplete(boolean)` is recommended as soon as the `Transferable` data is obtained; this allows the drag source to reset the cursor and any drag images which may be in effect.
      Parameters:
        `e` - event
        `action` - requested drop type
      Throws:
        `java.awt.datatransfer.UnsupportedFlavorException` - dropped item has no supported flavors
        `java.io.IOException` - data access failure

Copyright © 2007-2016 Timothy Wall. All Rights Reserved.