DragHandler (JNA API)

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

All Implemented Interfaces:

java.awt.dnd.DragGestureListener, java.awt.dnd.DragSourceListener, java.awt.dnd.DragSourceMotionListener, java.util.EventListener
```
public abstract class DragHandler
extends java.lang.Object
implements java.awt.dnd.DragSourceListener, java.awt.dnd.DragSourceMotionListener, java.awt.dnd.DragGestureListener
```
Provides simplified drag handling for a component. Usage:
```
 int actions = DnDConstants.MOVE_OR_COPY;
 Component component = ...;
 DragHandler handler = new DragHandler(component, actions);
 
```
- Supports painting an arbitrary Icon with transparency to represent the item being dragged (restricted to the Window of the drag source if the platform doesn't support drag images).
- Disallow starting a drag if the user requests an unsupported action.
- Adjusts the cursor on drags with no modifier for which the default action is disallowed but where one or more non-default actions are allowed, e.g. a drag (with no modifiers) to a target which supports "link" should change the cursor to "link" (prior to 1.6, the JRE behavior is to display a "not allowed" cursor, even though the action actually depends on how the drop target responds). The bug is fixed in java 1.6.
- Disallow drops to targets if the non-default (user-requested) action is not supported by the target, e.g. the user requests a "copy" when the target only supports "move". This is generally the responsibility of the drop handler, which decides whether or not to accept a drag. The DragHandler provides static modifier state information since the drop handler doesn't have access to it.
NOTE: Fundamentally, the active action is determined by the drop handler in DropTargetDragEvent.acceptDrag(int), but often client code simply relies on DropTargetDragEvent.getDropAction().

Field Summary

Fields
Modifier and Type	Field and Description
`protected static int`	`COPY` Convenience to reference `DnDConstants.ACTION_COPY`.
`(package private) static int`	`COPY_MASK` Modifier mask for a user-requested copy.
`static float`	`DEFAULT_GHOST_ALPHA` Default transparency for ghosting.
`(package private) static int`	`KEY_MASK` Modifier mask for any user-requested action.
`protected static int`	`LINK` Convenience to reference `DnDConstants.ACTION_LINK`.
`(package private) static int`	`LINK_MASK` Modifier mask for a user-requested link.
`static java.awt.Dimension`	`MAX_GHOST_SIZE` Default maximum size for ghosted images.
`protected static int`	`MOVE` Convenience to reference `DnDConstants.ACTION_MOVE`.
`(package private) static int`	`MOVE_MASK` Modifier mask for a user-requested move.
`protected static int`	`NONE` Convenience to reference `DnDConstants.ACTION_NONE`.
`(package private) static boolean`	`OSX`
`static int`	`UNKNOWN_MODIFIERS` `getModifiers()` returns this value when the current modifiers state is unknown.
`static java.awt.datatransfer.Transferable`	`UNKNOWN_TRANSFERABLE` `getTransferable(java.awt.dnd.DropTargetEvent)` returns this value when the current `Transferable` is unknown.

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`DragHandler(java.awt.Component dragSource, int actions)` Enable drags from the given component, supporting the actions in the given action mask.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`(package private) static java.lang.String`	`actionString(int action)`
`protected int`	`adjustDropAction(java.awt.dnd.DragSourceEvent ev)` Pick a different drop action if the target doesn't support the current one and there are no modifiers.
`protected boolean`	`canDrag(java.awt.dnd.DragGestureEvent e)` Override to control whether a drag is started.
`protected java.awt.Image`	`createDragImage(java.awt.GraphicsConfiguration gc, javax.swing.Icon icon)` Create an image from the given icon.
`void`	`dragDropEnd(java.awt.dnd.DragSourceDropEvent e)`
`void`	`dragEnter(java.awt.dnd.DragSourceDragEvent e)`
`void`	`dragExit(java.awt.dnd.DragSourceEvent e)`
`void`	`dragGestureRecognized(java.awt.dnd.DragGestureEvent e)` Called when a user drag gesture is recognized.
`void`	`dragMouseMoved(java.awt.dnd.DragSourceDragEvent e)`
`void`	`dragOver(java.awt.dnd.DragSourceDragEvent e)`
`protected void`	`dragStarted(java.awt.dnd.DragGestureEvent e)` Override to perform any decoration of the target at the start of a drag, if desired.
`void`	`dropActionChanged(java.awt.dnd.DragSourceDragEvent e)`
`protected int`	`getAcceptableDropAction(int targetActions)` Returns the first available action supported by source and target.
`protected java.awt.Cursor`	`getCursorForAction(int actualAction)`
`protected javax.swing.Icon`	`getDragIcon(java.awt.dnd.DragGestureEvent e, java.awt.Point srcOffset)` Override this to provide a custom image.
`protected int`	`getDropAction(java.awt.dnd.DragSourceEvent ev)` Get the currently requested drop action.
`(package private) static int`	`getModifiers()` Used to communicate modifier state to `DropHandler`.
`protected abstract java.awt.datatransfer.Transferable`	`getTransferable(java.awt.dnd.DragGestureEvent e)` Override to provide an appropriate `Transferable` representing the data being dragged.
`static java.awt.datatransfer.Transferable`	`getTransferable(java.awt.dnd.DropTargetEvent e)` Used to communicate the current `Transferable` during a drag, if available.
`protected javax.swing.Icon`	`scaleDragIcon(javax.swing.Icon icon, java.awt.Point imageOffset)` Change the size of the given drag icon, if appropriate.
`protected void`	`setModifiers(int mods)` Update the modifiers hint.
`protected void`	`updateCursor(java.awt.dnd.DragSourceEvent ev)` Hook to update the cursor on various `DragSourceEvent` updates.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - MAX_GHOST_SIZE
```
public static final java.awt.Dimension MAX_GHOST_SIZE
```
    Default maximum size for ghosted images.
  - DEFAULT_GHOST_ALPHA
```
public static final float DEFAULT_GHOST_ALPHA
```
    Default transparency for ghosting.
    
    See Also:
    
    Constant Field Values
  - UNKNOWN_MODIFIERS
```
public static final int UNKNOWN_MODIFIERS
```
    getModifiers() returns this value when the current modifiers state is unknown.
    
    See Also:
    
    Constant Field Values
  - UNKNOWN_TRANSFERABLE
```
public static final java.awt.datatransfer.Transferable UNKNOWN_TRANSFERABLE
```
    getTransferable(java.awt.dnd.DropTargetEvent) returns this value when the current Transferable is unknown.
  - MOVE
```
protected static final int MOVE
```
    Convenience to reference DnDConstants.ACTION_MOVE.
    
    See Also:
    
    Constant Field Values
  - COPY
```
protected static final int COPY
```
    Convenience to reference DnDConstants.ACTION_COPY.
    
    See Also:
    
    Constant Field Values
  - LINK
```
protected static final int LINK
```
    Convenience to reference DnDConstants.ACTION_LINK.
    
    See Also:
    
    Constant Field Values
  - NONE
```
protected static final int NONE
```
    Convenience to reference DnDConstants.ACTION_NONE.
    
    See Also:
    
    Constant Field Values
  - MOVE_MASK
```
static final int MOVE_MASK
```
    Modifier mask for a user-requested move.
    
    See Also:
    
    Constant Field Values
  - OSX
```
static final boolean OSX
```
  - COPY_MASK
```
static final int COPY_MASK
```
    Modifier mask for a user-requested copy.
  - LINK_MASK
```
static final int LINK_MASK
```
    Modifier mask for a user-requested link.
  - KEY_MASK
```
static final int KEY_MASK
```
    Modifier mask for any user-requested action.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - DragHandler
```
protected DragHandler(java.awt.Component dragSource,
                      int actions)
```
    Enable drags from the given component, supporting the actions in the given action mask.
    
    Parameters:
    
    dragSource - source of the drag.
    
    actions - actions which should be supported.
- Method Detail
  - getModifiers
```
static int getModifiers()
```
    Used to communicate modifier state to DropHandler. Note that this field will only be accurate when a DragHandler in the same VM started the drag. Otherwise, UNKNOWN_MODIFIERS will be returned.
    
    Returns:
    
    Current drag modifiers.
  - getTransferable
```
public static java.awt.datatransfer.Transferable getTransferable(java.awt.dnd.DropTargetEvent e)
```
    Used to communicate the current Transferable during a drag, if available. Work around absence of access to the data when dragging pre-1.5.
    
    Parameters:
    
    e - event
    
    Returns:
    
    Transferable representation of the item being dragged.
  - canDrag
```
protected boolean canDrag(java.awt.dnd.DragGestureEvent e)
```
    Override to control whether a drag is started. The default implementation disallows the drag if the user is applying modifiers and the user-requested action is not supported.
    
    Parameters:
    
    e - event
    
    Returns:
    
    Whether to allow a drag
  - setModifiers
```
protected void setModifiers(int mods)
```
    Update the modifiers hint.
    
    Parameters:
    
    mods - Current modifiers
  - getTransferable
```
protected abstract java.awt.datatransfer.Transferable getTransferable(java.awt.dnd.DragGestureEvent e)
```
    Override to provide an appropriate Transferable representing the data being dragged.
    
    Parameters:
    
    e - event
    
    Returns:
    
    Transferable representation of item being dragged.
  - getDragIcon
```
protected javax.swing.Icon getDragIcon(java.awt.dnd.DragGestureEvent e,
                                       java.awt.Point srcOffset)
```
    Override this to provide a custom image. The Icon returned by this method by default is null, which results in no drag image.
    
    Parameters:
    
    e - event
    
    srcOffset - set this to be the offset from the drag source component's upper left corner to the image's upper left corner. For example, when dragging a row from a list, the offset would be the row's bounding rectangle's (x,y) coordinate.
    The default value is (0,0), so if unchanged, the image is will use the same origin as the drag source component.
    
    Returns:
    
    drag icon (defaults to none)
  - dragStarted
```
protected void dragStarted(java.awt.dnd.DragGestureEvent e)
```
    Override to perform any decoration of the target at the start of a drag, if desired.
    
    Parameters:
    
    e - event
  - dragGestureRecognized
```
public void dragGestureRecognized(java.awt.dnd.DragGestureEvent e)
```
    Called when a user drag gesture is recognized. This method is responsible for initiating the drag operation.
    
    Specified by:
    
    dragGestureRecognized in interface java.awt.dnd.DragGestureListener
    
    Parameters:
    
    e - event
  - scaleDragIcon
```
protected javax.swing.Icon scaleDragIcon(javax.swing.Icon icon,
                                         java.awt.Point imageOffset)
```
    Change the size of the given drag icon, if appropriate. When using a differently-sized drag icon, we also need to adjust the cursor offset within the icon.
    
    Parameters:
    
    icon - Icon to be scaled.
    
    imageOffset - Modified to account for the new icon's size.
    
    Returns:
    
    Scaled Icon, or the original if there was no change.
  - createDragImage
```
protected java.awt.Image createDragImage(java.awt.GraphicsConfiguration gc,
                                         javax.swing.Icon icon)
```
    Create an image from the given icon. The image is provided to the native handler if drag images are supported natively.
    
    Parameters:
    
    gc - current graphics configuration.
    
    icon - Icon on which to base the drag image.
    
    Returns:
    
    image based on the given icon.
  - getCursorForAction
```
protected java.awt.Cursor getCursorForAction(int actualAction)
```
  - getAcceptableDropAction
```
protected int getAcceptableDropAction(int targetActions)
```
    Returns the first available action supported by source and target.
    
    Parameters:
    
    targetActions - current actions requested
    
    Returns:
    
    subset of actions supported based on the input
  - getDropAction
```
protected int getDropAction(java.awt.dnd.DragSourceEvent ev)
```
    Get the currently requested drop action.
    
    Parameters:
    
    ev - event
    
    Returns:
    
    effective drop action
  - adjustDropAction
```
protected int adjustDropAction(java.awt.dnd.DragSourceEvent ev)
```
    Pick a different drop action if the target doesn't support the current one and there are no modifiers.
    
    Parameters:
    
    ev - event
    
    Returns:
    
    effective drop action
  - updateCursor
```
protected void updateCursor(java.awt.dnd.DragSourceEvent ev)
```
    Hook to update the cursor on various DragSourceEvent updates.
    
    Parameters:
    
    ev - event
  - actionString
```
static java.lang.String actionString(int action)
```
  - dragDropEnd
```
public void dragDropEnd(java.awt.dnd.DragSourceDropEvent e)
```
    Specified by:
    
    dragDropEnd in interface java.awt.dnd.DragSourceListener
  - dragEnter
```
public void dragEnter(java.awt.dnd.DragSourceDragEvent e)
```
    Specified by:
    
    dragEnter in interface java.awt.dnd.DragSourceListener
  - dragMouseMoved
```
public void dragMouseMoved(java.awt.dnd.DragSourceDragEvent e)
```
    Specified by:
    
    dragMouseMoved in interface java.awt.dnd.DragSourceMotionListener
  - dragOver
```
public void dragOver(java.awt.dnd.DragSourceDragEvent e)
```
    Specified by:
    
    dragOver in interface java.awt.dnd.DragSourceListener
  - dragExit
```
public void dragExit(java.awt.dnd.DragSourceEvent e)
```
    Specified by:
    
    dragExit in interface java.awt.dnd.DragSourceListener
  - dropActionChanged
```
public void dropActionChanged(java.awt.dnd.DragSourceDragEvent e)
```
    Specified by:
    
    dropActionChanged in interface java.awt.dnd.DragSourceListener

Class DragHandler

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MAX_GHOST_SIZE

DEFAULT_GHOST_ALPHA

UNKNOWN_MODIFIERS

UNKNOWN_TRANSFERABLE

MOVE

COPY

LINK

NONE

MOVE_MASK

OSX

COPY_MASK

LINK_MASK

KEY_MASK

Constructor Detail

DragHandler

Method Detail

getModifiers

getTransferable

canDrag

setModifiers

getTransferable

getDragIcon

dragStarted

dragGestureRecognized

scaleDragIcon

createDragImage

getCursorForAction

getAcceptableDropAction

getDropAction

adjustDropAction

updateCursor

actionString

dragDropEnd

dragEnter

dragMouseMoved

dragOver

dragExit

dropActionChanged