Java Native Access Platform 5.14.0 · com.sun.jna.platform.dnd.DropHandler

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.
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 as soon as the Transferable data is obtained, to avoid making the DnD operation look suspended.

Field Summary

Modifier and Type	Field and Description
private int	acceptedActions
private List<DataFlavor>	acceptedFlavors
private boolean	active
private DropTarget	dropTarget
private String	lastAction
private static final Logger	LOG
private DropTargetPainter	painter

Constructor Summary

Access	Constructor and Description
public	DropHandler(Component target component c, int accepted actions acceptedActions) Create a handler that allows the given set of actions.
public	DropHandler(final Component The component to receive drops c, int Allowed actions for drops acceptedActions, DataFlavor[] Allowed data flavors for drops acceptedFlavors) Enable handling of drops, indicating what actions and flavors are acceptable.
public	DropHandler(final Component The component to receive drops c, int Allowed actions for drops acceptedActions, DataFlavor[] Allowed data flavors for drops acceptedFlavors, DropTargetPainter Painter to handle drop target feedback painter) Enable handling of drops, indicating what actions and flavors are acceptable, and providing a painter for drop target feedback.

Method Summary

Modifier and Type	Method and Description
protected int	Returns: resulting action acceptOrReject(DropTargetDragEvent event e) Accept or reject the drag represented by the given event.
protected boolean	Returns: whether the drop is supported canDrop(DropTargetEvent event e, int requested action action, Point requested drop location location) Indicate whether the given drop action is acceptable at the given location.
private void	describe(String type, DropTargetEvent e)
public void	dragEnter(DropTargetDragEvent the `DropTargetDragEvent` e) Implements java.awt.dnd.DropTargetListener.dragEnter. Called while a drag operation is ongoing, when the mouse pointer enters the operable part of the drop site for the `DropTarget` registered with this listener.
public void	dragExit(DropTargetEvent the `DropTargetEvent` e) Implements java.awt.dnd.DropTargetListener.dragExit. Called while a drag operation is ongoing, when the mouse pointer has exited the operable part of the drop site for the `DropTarget` registered with this listener.
public void	dragOver(DropTargetDragEvent the `DropTargetDragEvent` e) Implements java.awt.dnd.DropTargetListener.dragOver. Called when a drag operation is ongoing, while the mouse pointer is still over the operable part of the drop site for the `DropTarget` registered with this listener.
public void	drop(DropTargetDropEvent the `DropTargetDropEvent` e) Implements java.awt.dnd.DropTargetListener.drop. Indicates the user has initiated a drop.
protected abstract void	drop(DropTargetDropEvent event e, int requested drop type action) Handle an incoming drop with the given action.
public void	dropActionChanged(DropTargetDragEvent the `DropTargetDragEvent` e) Implements java.awt.dnd.DropTargetListener.dropActionChanged. Called if the user has modified the current drop gesture.
protected int	Returns: effective drop action getDropAction(DropTargetEvent `DropTargetEvent` e) Calculate the effective action.
protected int	getDropAction(DropTargetEvent e, int currentAction, int sourceActions, int acceptedActions)
protected int	Returns: currently acceptable actions. getDropActionsForFlavors(DataFlavor[] currently available flavors dataFlavors) Indicate the actions available for the given list of data flavors.
protected DropTarget	getDropTarget()
public boolean	Returns: Whether this drop target is active. isActive()
protected boolean	Returns: whether any of the given flavors are supported isSupported(DataFlavor[] list of transfer flavors to check flavors) Return whether any of the flavors in the given list are accepted.
protected boolean	Returns: whether any modifiers are active. modifiersActive(int requested action. dropAction) Returns whether there are key modifiers active , or false if they can't be determined.
protected void	paintDropTarget(DropTargetEvent The drop target event e, int The action for the drop action, Point The intended drop location, or null if there is none location) Update the appearance of the target component.
public void	setActive(boolean whether this handler should accept drops. active) Set whether this handler (and thus its drop target) will accept any drops.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

acceptedActions	back to summary
private int acceptedActions

acceptedFlavors	back to summary
private List<DataFlavor> acceptedFlavors

active	back to summary
private boolean active

dropTarget	back to summary
private DropTarget dropTarget

lastAction	back to summary
private String lastAction

LOG	back to summary
private static final Logger LOG

painter	back to summary
private DropTargetPainter painter

Constructor Detail

DropHandler back to summary

DropHandler	back to summary
public DropHandler(Component c, int acceptedActions) Create a handler that allows the given set of actions. If using this constructor, you will need to override `isSupported` to indicate which data flavors are allowed. Parameters c:Component target component acceptedActions:int accepted actions

public DropHandler(Component c, int acceptedActions)

Create a handler that allows the given set of actions. If using this constructor, you will need to override isSupported to indicate which data flavors are allowed.

Parameters

c:Component: target component
acceptedActions:int: accepted actions

DropHandler back to summary

DropHandler	back to summary
public DropHandler(final Component c, int acceptedActions, DataFlavor[] acceptedFlavors) Enable handling of drops, indicating what actions and flavors are acceptable. Parameters c:Component The component to receive drops acceptedActions:int Allowed actions for drops acceptedFlavors:DataFlavor[] Allowed data flavors for drops See Also `isSupported`

public DropHandler(final Component c, int acceptedActions, DataFlavor[] acceptedFlavors)

Enable handling of drops, indicating what actions and flavors are acceptable.

Parameters

c:Component: The component to receive drops
acceptedActions:int: Allowed actions for drops
acceptedFlavors:DataFlavor[]: Allowed data flavors for drops

See Also

isSupported

DropHandler back to summary

DropHandler	back to summary
public DropHandler(final Component c, int acceptedActions, 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:Component The component to receive drops acceptedActions:int Allowed actions for drops acceptedFlavors:DataFlavor[] Allowed data flavors for drops painter:DropTargetPainter Painter to handle drop target feedback See Also `paintDropTarget`

public DropHandler(final Component c, int acceptedActions, 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:Component: The component to receive drops
acceptedActions:int: Allowed actions for drops
acceptedFlavors:DataFlavor[]: Allowed data flavors for drops
painter:DropTargetPainter: Painter to handle drop target feedback

See Also

paintDropTarget

Method Detail

acceptOrReject back to summary

acceptOrReject	back to summary
protected int acceptOrReject(DropTargetDragEvent e) Accept or reject the drag represented by the given event. Returns the action determined by `getDropAction(DropTargetEvent)`. Parameters e:DropTargetDragEvent event Returns:int resulting action

protected int acceptOrReject(DropTargetDragEvent e)

Accept or reject the drag represented by the given event. Returns the action determined by getDropAction(DropTargetEvent).

Parameters

e:DropTargetDragEvent: event

Returns:int

resulting action

canDrop back to summary

canDrop	back to summary
protected boolean canDrop(DropTargetEvent e, int action, 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:DropTargetEvent event action:int requested action location:Point requested drop location Returns:boolean whether the drop is supported

protected boolean canDrop(DropTargetEvent e, int action, 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:DropTargetEvent: event
action:int: requested action
location:Point: requested drop location

Returns:boolean

whether the drop is supported

describe	back to summary
private void describe(String type, DropTargetEvent e)

dragEnter back to summary

dragEnter	back to summary
public void dragEnter(DropTargetDragEvent e) Implements java.awt.dnd.DropTargetListener.dragEnter. Doc from java.awt.dnd.DropTargetListener.dragEnter. Called while a drag operation is ongoing, when the mouse pointer enters the operable part of the drop site for the `DropTarget` registered with this listener. Parameters e:DropTargetDragEvent the `DropTargetDragEvent` Annotations @Override

public void dragEnter(DropTargetDragEvent e)

Implements java.awt.dnd.DropTargetListener.dragEnter.

Doc from java.awt.dnd.DropTargetListener.dragEnter.

Called while a drag operation is ongoing, when the mouse pointer enters the operable part of the drop site for the DropTarget registered with this listener.

Parameters

e:DropTargetDragEvent: the DropTargetDragEvent

Annotations

@Override

dragExit back to summary

dragExit	back to summary
public void dragExit(DropTargetEvent e) Implements java.awt.dnd.DropTargetListener.dragExit. Doc from java.awt.dnd.DropTargetListener.dragExit. Called while a drag operation is ongoing, when the mouse pointer has exited the operable part of the drop site for the `DropTarget` registered with this listener. Parameters e:DropTargetEvent the `DropTargetEvent` Annotations @Override

public void dragExit(DropTargetEvent e)

Implements java.awt.dnd.DropTargetListener.dragExit.

Doc from java.awt.dnd.DropTargetListener.dragExit.

Called while a drag operation is ongoing, when the mouse pointer has exited the operable part of the drop site for the DropTarget registered with this listener.

Parameters

e:DropTargetEvent: the DropTargetEvent

Annotations

@Override

dragOver back to summary

dragOver	back to summary
public void dragOver(DropTargetDragEvent e) Implements java.awt.dnd.DropTargetListener.dragOver. Doc from java.awt.dnd.DropTargetListener.dragOver. Called when a drag operation is ongoing, while the mouse pointer is still over the operable part of the drop site for the `DropTarget` registered with this listener. Parameters e:DropTargetDragEvent the `DropTargetDragEvent` Annotations @Override

public void dragOver(DropTargetDragEvent e)

Implements java.awt.dnd.DropTargetListener.dragOver.

Doc from java.awt.dnd.DropTargetListener.dragOver.

Called when a drag operation is ongoing, while the mouse pointer is still over the operable part of the drop site for the DropTarget registered with this listener.

Parameters

e:DropTargetDragEvent: the DropTargetDragEvent

Annotations

@Override

drop back to summary

drop	back to summary
public void drop(DropTargetDropEvent e) Implements java.awt.dnd.DropTargetListener.drop. 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. Parameters e:DropTargetDropEvent Doc from java.awt.dnd.DropTargetListener.drop. the `DropTargetDropEvent` Annotations @Override

public void drop(DropTargetDropEvent e)

Implements java.awt.dnd.DropTargetListener.drop.

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.

Parameters

e:DropTargetDropEvent

Doc from java.awt.dnd.DropTargetListener.drop.

the DropTargetDropEvent

Annotations

@Override

drop back to summary

drop	back to summary
protected abstract void drop(DropTargetDropEvent e, int action) throws UnsupportedFlavorException, 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` 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:DropTargetDropEvent event action:int requested drop type Exceptions UnsupportedFlavorException: dropped item has no supported flavors IOException: data access failure

protected abstract void drop(DropTargetDropEvent e, int action) throws UnsupportedFlavorException, 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 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:DropTargetDropEvent: event
action:int: requested drop type

Exceptions

UnsupportedFlavorException:: dropped item has no supported flavors
IOException:: data access failure

dropActionChanged back to summary

dropActionChanged	back to summary
public void dropActionChanged(DropTargetDragEvent e) Implements java.awt.dnd.DropTargetListener.dropActionChanged. Doc from java.awt.dnd.DropTargetListener.dropActionChanged. Called if the user has modified the current drop gesture. Parameters e:DropTargetDragEvent the `DropTargetDragEvent` Annotations @Override

public void dropActionChanged(DropTargetDragEvent e)

Implements java.awt.dnd.DropTargetListener.dropActionChanged.

Doc from java.awt.dnd.DropTargetListener.dropActionChanged.

Called if the user has modified the current drop gesture.

Parameters

e:DropTargetDragEvent: the DropTargetDragEvent

Annotations

@Override

getDropAction back to summary

getDropAction	back to summary
protected int getDropAction(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 `DropTargetEvent` Returns:int effective drop action See Also `isSupported(DataFlavor[])`, `getDropActionsForFlavors`, `getDropAction(DropTargetEvent, int, int, int)`, `canDrop(DropTargetEvent, int, Point)`

protected int getDropAction(DropTargetEvent e)

Calculate the effective action. The default implementation checks whether any DataFlavors 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: DropTargetEvent

Returns:int

effective drop action

getDropAction	back to summary
protected int getDropAction(DropTargetEvent e, int currentAction, int sourceActions, int acceptedActions)

getDropActionsForFlavors back to summary

getDropActionsForFlavors	back to summary
protected int getDropActionsForFlavors(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:DataFlavor[] currently available flavors Returns:int currently acceptable actions. See Also `getDropAction(DropTargetEvent, int, int, int)`, `canDrop(DropTargetEvent, int, Point)`

protected int getDropActionsForFlavors(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:DataFlavor[]: currently available flavors

Returns:int

currently acceptable actions.

getDropTarget	back to summary
protected DropTarget getDropTarget()

isActive	back to summary
public boolean isActive() Returns:boolean Whether this drop target is active.

isSupported	back to summary
protected boolean isSupported(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:DataFlavor[] list of transfer flavors to check Returns:boolean whether any of the given flavors are supported

isSupported

back to summary

protected boolean isSupported(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:DataFlavor[]: list of transfer flavors to check

Returns:boolean

whether any of the given flavors are supported

modifiersActive	back to summary
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:int requested action. Returns:boolean whether any modifiers are active.

modifiersActive

back to summary

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:int: requested action.

Returns:boolean

whether any modifiers are active.

paintDropTarget back to summary

paintDropTarget	back to summary
protected void paintDropTarget(DropTargetEvent e, int action, 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:DropTargetEvent The drop target event action:int The action for the drop location:Point The intended drop location, or null if there is none

protected void paintDropTarget(DropTargetEvent e, int action, 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:DropTargetEvent: The drop target event
action:int: The action for the drop
location:Point: The intended drop location, or null if there is none

setActive	back to summary
public void setActive(boolean active) Set whether this handler (and thus its drop target) will accept any drops. Parameters active:boolean whether this handler should accept drops.

setActive

back to summary

public void setActive(boolean active)

Set whether this handler (and thus its drop target) will accept any drops.

Parameters

active:boolean: whether this handler should accept drops.

public abstract Class DropHandler

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail