# Class NativeDragOperation

java.lang.Object
com.codename1.ui.NativeDragOperation

public class NativeDragOperation extends Object

Everything the operating system needs in order to drag something out of a Codename One component: what is being dragged, what the receiver is allowed to do with it, and what the user should see under the cursor while dragging.

The payload is a `ClipboardContent`, the same object a copy publishes, so a component that can already be copied can be made draggable by handing the very same content to `Component#setNativeDragOperation(com.codename1.ui.NativeDragOperation)`. Offering several representations is what lets one drag land correctly in unrelated applications: a text editor takes `ClipboardContent#MIME_HTML`, a plain text field takes `ClipboardContent#MIME_TEXT` and the desktop or a file manager takes `ClipboardContent#MIME_FILE`.

Representations that are expensive to produce -- the file that only exists if the user actually drops on the desktop -- should be registered with `ClipboardContent#setDataProvider(java.lang.String, com.codename1.ui.ClipboardDataProvider)` rather than built when the drag starts.

##### Moving rather than copying

`#ACTION_MOVE` means the receiver takes ownership and the source is expected to delete its copy. The source only learns whether that happened once the operating system has finished the transfer, which is why the outcome arrives asynchronously through `#addCompletionListener(com.codename1.ui.events.ActionListener)` and not from the call that started the drag.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `ACTION_COPY`
  The receiver takes a copy and the source keeps its own.
  `static final int`
  `ACTION_LINK`
  The receiver stores a reference rather than the data, the way a shortcut or an alias does.
  `static final int`
  `ACTION_MOVE`
  The receiver takes ownership; the source should delete its copy when the drag completes with this action.
  `static final int`
  `ACTION_NONE`
  No transfer, which is what a rejected or cancelled drag reports.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `NativeDragOperation(ClipboardContent content)`
  Creates a drag carrying the given representations.
  `NativeDragOperation(String text)`
  Creates a plain text drag, the shorthand for the common case.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addCompletionListener(ActionListener l)`
  Adds a listener notified on the event dispatch thread once the operating system has finished with this drag, whether it was dropped or abandoned.
  `static NativeDragOperation`
  `createFileDrag(String[] paths)`
  Creates a drag carrying files, which is what a drop onto the desktop or a file manager consumes.
  `int`
  `getAllowedActions()`
  Returns the bit set of actions the source is willing to allow, `#ACTION_COPY` by default.
  `ClipboardContent`
  `getContent()`
  Returns the payload.
  `Image`
  `getDragImage()`
  Returns the image drawn under the cursor during the drag, or null to let the port draw the component itself.
  `int`
  `getDragImageOffsetX()`
  Returns the x offset of the cursor within the drag image.
  `int`
  `getDragImageOffsetY()`
  Returns the y offset of the cursor within the drag image.
  `String`
  `getLabel()`
  Returns the human readable label some platforms show beside the drag image.
  `int`
  `getPerformedAction()`
  Returns the action the receiver actually performed, valid once the drag has completed.
  `Component`
  `getSource()`
  Returns the component the drag started from, or null when the drag was started through `NativeDragAndDrop#startDrag(com.codename1.ui.Component, com.codename1.ui.NativeDragOperation)` without one.
  `void`
  `removeCompletionListener(ActionListener l)`
  Removes a listener added by `#addCompletionListener(com.codename1.ui.events.ActionListener)`.
  `NativeDragOperation`
  `setAllowedActions(int allowedActions)`
  Sets the bit set of actions the source is willing to allow.
  `NativeDragOperation`
  `setDragImage(Image dragImage)`
  Sets the image drawn under the cursor during the drag.
  `NativeDragOperation`
  `setDragImageOffset(int x, int y)`
  Places the cursor at a specific point of the drag image, so the image keeps the position it had relative to the finger or pointer when the drag began.
  `NativeDragOperation`
  `setLabel(String label)`
  Sets the human readable label some platforms show beside the drag image, such as the file name of a dragged document.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### ACTION_NONE

    public static final int ACTION_NONE
    No transfer, which is what a rejected or cancelled drag reports.
    See Also:
      - Constant Field Values

  - ### ACTION_COPY

    public static final int ACTION_COPY
    The receiver takes a copy and the source keeps its own.
    See Also:
      - Constant Field Values

  - ### ACTION_MOVE

    public static final int ACTION_MOVE
    The receiver takes ownership; the source should delete its copy when the drag completes with this action.
    See Also:
      - Constant Field Values

  - ### ACTION_LINK

    public static final int ACTION_LINK
    The receiver stores a reference rather than the data, the way a shortcut or an alias does.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### NativeDragOperation

    public NativeDragOperation(ClipboardContent content)

    Creates a drag carrying the given representations.

    ###### Parameters

    - `content`: the payload, which must not be null

  - ### NativeDragOperation

    public NativeDragOperation(String text)

    Creates a plain text drag, the shorthand for the common case.

    ###### Parameters

    - `text`: the text being dragged

- ## Method Details

  - ### createFileDrag

    public static NativeDragOperation createFileDrag(String[] paths)

    Creates a drag carrying files, which is what a drop onto the desktop or a file manager consumes.

    ###### Parameters

    - `paths`: the file paths or `file:` URIs being dragged

    ###### Returns

    the new operation

  - ### getContent

    public ClipboardContent getContent()
    Returns the payload.

  - ### getAllowedActions

    public int getAllowedActions()
    Returns the bit set of actions the source is willing to allow, `#ACTION_COPY` by default.

  - ### setAllowedActions

    public NativeDragOperation setAllowedActions(int allowedActions)

    Sets the bit set of actions the source is willing to allow. The receiver chooses one of them, usually influenced by the modifier keys the user is holding.

    Allowing none of them is allowing nothing to be done with the drag, so no drag begins at all: there is nothing a receiver could accept.

    ###### Parameters

    - `allowedActions`: any combination of `#ACTION_COPY`, `#ACTION_MOVE` and `#ACTION_LINK`

    ###### Returns

    this instance, for chaining

  - ### getDragImage

    public Image getDragImage()
    Returns the image drawn under the cursor during the drag, or null to let the port draw the component itself.

  - ### setDragImage

    public NativeDragOperation setDragImage(Image dragImage)

    Sets the image drawn under the cursor during the drag. When this is left null the port renders the dragged component through `Component#getDragImage()`, so the user sees the thing they grabbed.

    ###### Parameters

    - `dragImage`: the image, or null for the default

    ###### Returns

    this instance, for chaining

  - ### getDragImageOffsetX

    public int getDragImageOffsetX()
    Returns the x offset of the cursor within the drag image.

  - ### getDragImageOffsetY

    public int getDragImageOffsetY()
    Returns the y offset of the cursor within the drag image.

  - ### setDragImageOffset

    public NativeDragOperation setDragImageOffset(int x, int y)

    Places the cursor at a specific point of the drag image, so the image keeps the position it had relative to the finger or pointer when the drag began.

    ###### Parameters

    - `x`: the x offset within the image

    - `y`: the y offset within the image

    ###### Returns

    this instance, for chaining

  - ### getLabel

    public String getLabel()
    Returns the human readable label some platforms show beside the drag image.

  - ### setLabel

    public NativeDragOperation setLabel(String label)

    Sets the human readable label some platforms show beside the drag image, such as the file name of a dragged document. Platforms that have no such affordance ignore it.

    ###### Parameters

    - `label`: the label

    ###### Returns

    this instance, for chaining

  - ### getSource

    public Component getSource()
    Returns the component the drag started from, or null when the drag was started through `NativeDragAndDrop#startDrag(com.codename1.ui.Component, com.codename1.ui.NativeDragOperation)` without one.

  - ### getPerformedAction

    public int getPerformedAction()
    Returns the action the receiver actually performed, valid once the drag has completed. Before that, and for a drag that was cancelled or rejected, this is `#ACTION_NONE`.

  - ### addCompletionListener

    public void addCompletionListener(ActionListener l)

    Adds a listener notified on the event dispatch thread once the operating system has finished with this drag, whether it was dropped or abandoned. Read `#getPerformedAction()` from the listener; a source offering `#ACTION_MOVE` deletes its copy here and nowhere else, because until this fires nothing is known about whether the receiver took it.

    ###### Parameters

    - `l`: the listener

  - ### removeCompletionListener

    public void removeCompletionListener(ActionListener l)

    Removes a listener added by `#addCompletionListener(com.codename1.ui.events.ActionListener)`.

    ###### Parameters

    - `l`: the listener