public class NativeDragOperation

Object
NativeDragOperation

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.

Fields

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

Constructors

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

Methods

`public static` `NativeDragOperation createFileDrag(String[] paths)`	Creates a drag carrying files, which is what a drop onto the desktop or a file manager consumes.
`public` `ClipboardContent getContent()`	Returns the payload.
`public int getAllowedActions()`	Returns the bit set of actions the source is willing to allow, `#ACTION_COPY` by default.
`public` `NativeDragOperation setAllowedActions(int allowedActions)`	Sets the bit set of actions the source is willing to allow.
`public` `Image getDragImage()`	Returns the image drawn under the cursor during the drag, or null to let the port draw the component itself.
`public` `NativeDragOperation setDragImage(Image dragImage)`	Sets the image drawn under the cursor during the drag.
`public int getDragImageOffsetX()`	Returns the x offset of the cursor within the drag image.
`public int getDragImageOffsetY()`	Returns the y offset of the cursor within the drag image.
`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.
`public` `String getLabel()`	Returns the human readable label some platforms show beside the drag image.
`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.
`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.
`public int getPerformedAction()`	Returns the action the receiver actually performed, valid once the drag has completed.
`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.
`public void removeCompletionListener(ActionListener l)`	Removes a listener added by `#addCompletionListener(com.codename1.ui.events.ActionListener)`.

Inherited methods

From Object

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

Field details

ACTION_NONE

public static final int ACTION_NONE = 0

No transfer, which is what a rejected or cancelled drag reports.

ACTION_COPY

public static final int ACTION_COPY = 1

The receiver takes a copy and the source keeps its own.

ACTION_MOVE

public static final int ACTION_MOVE = 2

The receiver takes ownership; the source should delete its copy when the drag completes with this action.

ACTION_LINK

public static final int ACTION_LINK = 4

The receiver stores a reference rather than the data, the way a shortcut or an alias does.

Constructor details

NativeDragOperation

public NativeDragOperation(ClipboardContent content)

Creates a drag carrying the given representations.

Parameters

content ClipboardContent: 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 String: 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 String[]: 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 int: 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 Image: 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 int: the x offset within the image
y int: 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 String: 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 ActionListener: the listener

removeCompletionListener

public void removeCompletionListener(ActionListener l)

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

Parameters

l ActionListener: the listener