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:

    • ACTION_COPY

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

    • 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:

  • 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