Package com.sun.jna.platform.dnd

# Class DragHandler

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

All Implemented Interfaces:
  `DragGestureListener`, `DragSourceListener`, `DragSourceMotionListener`, `EventListener`

public abstract class DragHandler extends Object implements DragSourceListener, DragSourceMotionListener, 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
Description
`protected static final int`
`COPY`
Convenience to reference `DnDConstants.ACTION_COPY`.
`(package private) static final int`
`COPY_MASK`
Modifier mask for a user-requested copy.
`static final float`
`DEFAULT_GHOST_ALPHA`
Default transparency for ghosting.
`(package private) static final int`
`KEY_MASK`
Modifier mask for any user-requested action.
`protected static final int`
`LINK`
Convenience to reference `DnDConstants.ACTION_LINK`.
`(package private) static final int`
`LINK_MASK`
Modifier mask for a user-requested link.
`static final Dimension`
`MAX_GHOST_SIZE`
Default maximum size for ghosted images.
`protected static final int`
`MOVE`
Convenience to reference `DnDConstants.ACTION_MOVE`.
`(package private) static final int`
`MOVE_MASK`
Modifier mask for a user-requested move.
`protected static final int`
`NONE`
Convenience to reference `DnDConstants.ACTION_NONE`.
`(package private) static final boolean`
`OSX`
`static final int`
`UNKNOWN_MODIFIERS`
`getModifiers()` returns this value when the current modifiers state is unknown.
`static final Transferable`
`UNKNOWN_TRANSFERABLE`
`getTransferable(java.awt.dnd.DropTargetEvent)` returns this value when the current `Transferable` is unknown.

## Constructor Summary

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

## Method Summary

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

### MAX_GHOST_SIZE

public static final 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 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 Details

### DragHandler

protected DragHandler(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 Details

### 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 Transferable getTransferable(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(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 Transferable getTransferable(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 Icon getDragIcon(DragGestureEvent e, 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(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(DragGestureEvent e)
Called when a user drag gesture is recognized. This method is responsible for initiating the drag operation.

Specified by:
  `dragGestureRecognized` in interface `DragGestureListener`
Parameters:
  `e` - event

### scaleDragIcon

protected Icon scaleDragIcon(Icon icon, 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 Image createDragImage(GraphicsConfiguration gc, 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 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(DragSourceEvent ev)
Get the currently requested drop action.

Parameters:
  `ev` - event
Returns:
  effective drop action

### adjustDropAction

protected int adjustDropAction(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(DragSourceEvent ev)
Hook to update the cursor on various `DragSourceEvent` updates.

Parameters:
  `ev` - event

### actionString

static String actionString(int action)

### dragDropEnd

public void dragDropEnd(DragSourceDropEvent e)

Specified by:
  `dragDropEnd` in interface `DragSourceListener`

### dragEnter

public void dragEnter(DragSourceDragEvent e)

Specified by:
  `dragEnter` in interface `DragSourceListener`

### dragMouseMoved

public void dragMouseMoved(DragSourceDragEvent e)

Specified by:
  `dragMouseMoved` in interface `DragSourceMotionListener`

### dragOver

public void dragOver(DragSourceDragEvent e)

Specified by:
  `dragOver` in interface `DragSourceListener`

### dragExit

public void dragExit(DragSourceEvent e)

Specified by:
  `dragExit` in interface `DragSourceListener`

### dropActionChanged

public void dropActionChanged(DragSourceDragEvent e)

Specified by:
  `dropActionChanged` in interface `DragSourceListener`