Skip navigation links
JNA API 5.3.1
com.sun.jna.platform.dnd

Class 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). 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

      All Methods Instance Methods Abstract Methods Concrete 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,
                                    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
JNA API 5.3.1

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