# Class NativeDragAndDrop

java.lang.Object
com.codename1.ui.NativeDragAndDrop

public final class NativeDragAndDrop extends Object

Drag and drop through the operating system rather than inside the application.

Codename One has always had a lightweight drag and drop -- `Component#setDraggable(boolean)` and `Component#setDropTarget(boolean)` -- which moves a rendered image around inside one form. That never leaves the application, so it cannot drop a file on the desktop, cannot carry text into another application's window, and cannot receive anything from one.

This class is the other half: it hands the drag to the operating system's own drag machinery, using the same `ClipboardContent` a copy publishes as the payload. That is the whole idea -- a drag is a copy that the user aims with the pointer, so anything the application can already put on the clipboard it can already drag out, and anything it can paste it can already accept as a drop.

##### Dragging out

    Label file = new Label("report.pdf");
    file.setNativeDragOperation(NativeDragOperation.createFileDrag(
            new String[] { FileSystemStorage.getInstance().getAppHomePath() + "report.pdf" }));

Dropping that on the desktop, on a mail composer or into a file manager copies the file, because the receiving application asked for `ClipboardContent#MIME_FILE` and the drag offered it. Offer several representations and every receiver takes the best one it understands.

##### Receiving a drop

    Container inbox = new Container();
    inbox.setNativeDropTarget(true);
    inbox.addNativeDropListener(e -> {
        NativeDropEvent drop = (NativeDropEvent)e;
        String[] files = drop.getFiles();
        ...
    });

##### Where it works

Native drag and drop needs the platform to have it. Check `#isSupported()` before offering the affordance, and `#isDragOutsideApplicationSupported()` before promising the user that a drag can leave the application: a desktop can drop onto any other window, a tablet can drop into another application beside it, and a phone in full screen has nowhere for a drag to go even though drags within the application still work. Where nothing is supported the calls here are harmless no-ops and the lightweight drag and drop is unaffected.

##### Threading

The gesture half runs on the event dispatch thread; the receiving half is called from whatever thread the platform hands the port. All of the shared state below is therefore guarded by one lock, and no callback into component or port code is ever made while holding it -- the framework's own event dispatch thread blocks on the platform's UI thread to paint on some ports, so a lock held across a callback is a deadlock waiting for the first drag.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `NO_HOVER_GENERATION`
  What a port that does not track the hover generation passes, which asks for the recovery to be attempted on whatever hover state is there -- the behaviour every port had before one of them could tell.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `beginTransfer(ClipboardContent content)`
  The same, for a transfer that is not a drag: a clipboard a port keeps lazily, whose content the application may also be dragging.
  `static int`
  `deferredDrop(int windowId, int x, int y, ClipboardContent content, int action, int advertisedActions, boolean local)`
  Delivers a native drop whose action was already decided when the user released.
  `static int`
  `deferredDrop(int windowId, int x, int y, ClipboardContent content, int action, int advertisedActions, boolean local, int hoverGeneration)`
  The same, for a port that took a hover generation when the drop began.
  `static void`
  `dragCompleted(int performedAction)`
  Reports that the session started by `#startDrag(com.codename1.ui.Component, com.codename1.ui.NativeDragOperation)` has finished, whatever the outcome, so that a source offering `NativeDragOperation#ACTION_MOVE` learns whether to delete its copy.
  `static int`
  `dragEnter(int windowId, int x, int y, ClipboardContent content, int allowedActions)`
  Reports that a native drag has entered one of the application's surfaces.
  `static void`
  `dragExit(int windowId)`
  Reports that a native drag has left the application's surfaces without dropping.
  `static int`
  `dragOver(int windowId, int x, int y, ClipboardContent content, int allowedActions)`
  Reports that a native drag has moved over one of the application's surfaces, and answers whether it would be accepted here.
  `static NativeDragOperation`
  `dragSessionStarted()`
  Reports that the platform started a drag session on its own, for the operation the press prepared.
  `static int`
  `drop(int windowId, int x, int y, ClipboardContent content, int action)`
  Delivers a native drop.
  `static int`
  `drop(int windowId, int x, int y, ClipboardContent content, int action, int advertisedActions, boolean local)`
  Delivers a native drop whose origin the port knows.
  `static void`
  `gestureCancelled()`
  Abandons whatever a press staged, because the gesture it belonged to is over or has turned into something else.
  `static NativeDragOperation`
  `getActiveDrag()`
  Returns the drag this application is currently running through the operating system, or null when it is not dragging.
  `static int`
  `hoverGeneration()`
  The generation of the hover state a drop assembled later can quote back; see `#deferredDrop(int, int, int, com.codename1.ui.ClipboardContent, int, int, boolean, int)`.
  `static boolean`
  `isDragOutsideApplicationSupported()`
  Returns true when a drag started here can be dropped outside the application: on the desktop, in a file manager or in another application's window.
  `static boolean`
  `isSupported()`
  Returns true when this platform can drag and drop through the operating system at all.
  `static int`
  `plannedDropAction(int windowId, int x, int y, ClipboardContent content, int action)`
  The action a drop at this position would perform, without dispatching anything or disturbing the drag in progress.
  `static Object`
  `produceDragValue(NativeDragOperation op, String mimeType)`
  Produces one representation of a drag for the session that is reading it, rather than for whichever transfer armed the operation last.
  `static Object`
  `produceTransferValue(ClipboardContent content, String mimeType)`
  `static boolean`
  `startDrag(Component source, NativeDragOperation op)`
  Starts a native drag immediately, for an application that decides on its own that a drag has begun -- from a long press, or a menu item -- rather than letting a component do it through `Component#setNativeDragSource(boolean)`.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### NO_HOVER_GENERATION

    public static final int NO_HOVER_GENERATION
    What a port that does not track the hover generation passes, which asks for the recovery to be attempted on whatever hover state is there -- the behaviour every port had before one of them could tell.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### isSupported

    public static boolean isSupported()
    Returns true when this platform can drag and drop through the operating system at all. Where this is false every method here does nothing and reports failure, so no call site needs to be conditional -- but an application that shows a "drag me" affordance should hide it.

  - ### isDragOutsideApplicationSupported

    public static boolean isDragOutsideApplicationSupported()

    Returns true when a drag started here can be dropped outside the application: on the desktop, in a file manager or in another application's window.

    This is narrower than `#isSupported()`. A platform can route drags between components, and between this application's own windows, while still refusing to let one leave -- which is the normal state of affairs on a phone.

  - ### startDrag

    public static boolean startDrag(Component source, NativeDragOperation op)

    Starts a native drag immediately, for an application that decides on its own that a drag has begun -- from a long press, or a menu item -- rather than letting a component do it through `Component#setNativeDragSource(boolean)`.

    Call this on the event dispatch thread while the pointer is still down; a drag the user is not currently holding cannot be aimed and platforms reject it.

    ###### Parameters

    - `source`: the component the drag comes from, used for the default drag image and reported by `NativeDragOperation#getSource()`. May be null.

    - `op`: what is being dragged

    ###### Returns

    true when the operating system took the drag; false when the platform has no native drag and drop, refused to start a session, or is already running one

  - ### dragSessionStarted

    public static NativeDragOperation dragSessionStarted()

    Reports that the platform started a drag session on its own, for the operation the press prepared. Ports whose operating system owns the drag gesture -- where a long press, not the framework's own threshold, is what begins a drag -- call this instead of returning true from `com.codename1.impl.CodenameOneImplementation#startNativeDrag(com.codename1.ui.NativeDragOperation)`.

    ###### Returns

    the operation the session is carrying, or null when nothing was prepared -- in which case the port should refuse to start a session

  - ### produceDragValue

    public static Object produceDragValue(NativeDragOperation op, String mimeType)

    Produces one representation of a drag for the session that is reading it, rather than for whichever transfer armed the operation last.

    For a port whose platform keeps an older session readable while a newer one runs -- iOS does, for as long as a receiver holds one of its item providers -- and which therefore keeps a memo of its own, one per session. Reading through the operation instead would hand that receiver the newer drag's value, or produce a second one for a drag that had already ended. Every other port reads through `ClipboardContent#getData(java.lang.String)`, whose memory is the running transfer's and is exactly right when only one session can be read at a time.

    ###### Parameters

    - `op`: the operation the session is carrying, which may be null

    - `mimeType`: the representation being read

    ###### Returns

    the value, or null when there is no such operation or representation

  - ### beginTransfer

    public static void beginTransfer(ClipboardContent content)

    The same, for a transfer that is not a drag: a clipboard a port keeps lazily, whose content the application may also be dragging.

    A copy and a drag can share one `ClipboardContent`, and arming a drag forgets what its providers produced. Reading the content's own memory then gave the clipboard whatever the drag had most recently produced -- for a provider that writes a file per transfer, a path belonging to that drag, which its cleanup may since have deleted. A port in that position produces its own value and remembers it itself.

    ###### Parameters

    - `content`: the representations being transferred, which may be null

    - `mimeType`: the representation being read

    ###### Returns

    the value, or null when there is no such representation Ends a content's memory of what its providers produced, because a new transfer of it is beginning.

    A representation registered through `ClipboardContent#setDataProvider(java.lang.String, com.codename1.ui.ClipboardDataProvider)` is resolved once per transfer and remembered, so a consumer that asks twice does not make the provider write its file twice. `Display#copyToClipboard(ClipboardContent)` calls this as a copy is asked for. A port that assembles later, or on another thread, needs more than this -- two overlapping transfers of one content would share the memory this resets -- and reads through a memo of its own instead; see the Android port's clip assembly.

    ###### Parameters

    - `content`: the content about to be published, which may be null

  - ### produceTransferValue

    public static Object produceTransferValue(ClipboardContent content, String mimeType)

  - ### getActiveDrag

    public static NativeDragOperation getActiveDrag()
    Returns the drag this application is currently running through the operating system, or null when it is not dragging. A drop target uses this to tell a drag it started itself from one that arrived from elsewhere, which `NativeDropEvent#isLocal()` reports.

  - ### gestureCancelled

    public static void gestureCancelled()

    Abandons whatever a press staged, because the gesture it belonged to is over or has turned into something else.

    A release is the ordinary way that happens and the framework calls this itself. A port calls it for the ways that are not a release: a touch the platform cancels outright, which delivers no release at all, and anything else that ends a gesture without one. Leaving an operation staged past its gesture is what lets a later, unrelated movement start a drag nobody asked for.

  - ### dragEnter

    public static int dragEnter(int windowId, int x, int y, ClipboardContent content, int allowedActions)

    Reports that a native drag has entered one of the application's surfaces.

    ###### Parameters

    - `windowId`: the id of the window the drag is over, or zero for the main surface

    - `x`: the pointer position within that surface

    - `y`: the pointer position within that surface

    - `content`: the representations the drag is offering

    - `allowedActions`: the actions the source permits

    ###### Returns

    the action a drop would perform right now, or `NativeDragOperation#ACTION_NONE` when nothing under the pointer will take it

  - ### dragOver

    public static int dragOver(int windowId, int x, int y, ClipboardContent content, int allowedActions)

    Reports that a native drag has moved over one of the application's surfaces, and answers whether it would be accepted here.

    ###### Threading

    The operating system needs the answer synchronously, while the framework's callbacks have to run on the event dispatch thread -- and blocking a native drag thread on the event dispatch thread deadlocks, because on some ports the event dispatch thread is itself waiting on that native thread to paint. So the target is resolved here, on the calling thread, from state that does not change under it, while `Component#nativeDragOver(com.codename1.ui.NativeDropEvent)` and the listeners are dispatched asynchronously; the value returned is the one they produced for the previous event on this same target. A target that changes its mind therefore shows the user the new cursor one drag event late, which is a frame, and never blocks.

    A target that refuses a drop outright should say so through `Component#canAcceptNativeDrop(com.codename1.ui.ClipboardContent)` or the accepted MIME list instead, both of which are consulted here and are therefore exact from the first event -- and from every event, including the drop itself. A `NativeDropEvent#reject()` in a callback is a change of mind rather than a refusal: it is honoured from the next event onward, and a drop landing before the callback has run reads what the target declared. `#drop(int, int, int, com.codename1.ui.ClipboardContent, int)` says why that cannot be closed without doing something worse.

    ###### Parameters

    - `windowId`: the id of the window the drag is over, or zero for the main surface

    - `x`: the pointer position within that surface

    - `y`: the pointer position within that surface

    - `content`: the representations the drag is offering

    - `allowedActions`: the actions the source permits

    ###### Returns

    the action a drop would perform right now, or `NativeDragOperation#ACTION_NONE`

  - ### dragExit

    public static void dragExit(int windowId)

    Reports that a native drag has left the application's surfaces without dropping.

    ###### Parameters

    - `windowId`: the id of the window the drag left, or zero for the main surface

  - ### drop

    public static int drop(int windowId, int x, int y, ClipboardContent content, int action)

    Delivers a native drop.

    The content must be fully materialized before this is called: on most platforms the native transfer object is only readable inside the drop callback, so a port that hands over a lazy view of it delivers empty data by the time the event dispatch thread reads it.

    ###### Parameters

    - `windowId`: the id of the window dropped on, or zero for the main surface

    - `x`: the pointer position within that surface

    - `y`: the pointer position within that surface

    - `content`: the dropped representations

    - `action`: the action the operating system settled on

    ###### Returns

    the action actually accepted, or `NativeDragOperation#ACTION_NONE` when nothing under the pointer took the drop and the port should report the transfer as failed

  - ### drop

    public static int drop(int windowId, int x, int y, ClipboardContent content, int action, int advertisedActions, boolean local)

    Delivers a native drop whose origin the port knows.

    A port that assembles a drop asynchronously calls this one, because by the time the assembly finishes the drag it belongs to may no longer be the one running: a drop that arrived from another application, still loading when the user began a drag of their own, would otherwise be reported to the target as local -- and a target that uses `NativeDropEvent#isLocal()` to tell reordering from importing would treat foreign content as an internal move.

    ###### Parameters

    - `advertisedActions`: the mask this drag offered, or `NativeDragOperation#ACTION_NONE` to use whatever the last drag event advertised. Carried for the same reason as the locality beside it: a newer drag has since overwritten what the framework remembers, and giving this drop that newer mask made its event report an action the source never offered -- or, when the newer drag is narrower, report nothing accepted at all while the platform had been told the drop succeeded.

    - `local`: true when the drag being dropped is one this application started

    ###### Returns

    the action actually accepted, or `NativeDragOperation#ACTION_NONE`

  - ### deferredDrop

    public static int deferredDrop(int windowId, int x, int y, ClipboardContent content, int action, int advertisedActions, boolean local)

    Delivers a native drop whose action was already decided when the user released.

    For a port that assembles a drop asynchronously and keeps that session's decision with the session -- iOS does both. The ordinary entry point prefers what the component hovering said last, because a port's action is by construction one drag event behind; but a drop that has been loading is no longer the hovering session, and the framework keeps one hover state. Another drop hovering the same component in the meantime would otherwise lend this one its decision: its rejection would discard a drop the user had actually performed, and its acceptance would change the action this one reports.

    So the caller's action is taken as the answer here, narrowed only by what the target still permits. The hover state is cleared as it is for any drop -- a component holding a highlight for a drag that has moved on is sent an exit and re-entered by its next update, which is a frame that repairs itself, where a discarded drop is work the user did and lost.

    ###### Parameters

    - `action`: the action this drop's own session settled on when it was released

    ###### Returns

    the action actually accepted, or `NativeDragOperation#ACTION_NONE`

  - ### deferredDrop

    public static int deferredDrop(int windowId, int x, int y, ClipboardContent content, int action, int advertisedActions, boolean local, int hoverGeneration)

    The same, for a port that took a hover generation when the drop began.

    The recovery for a target whose position moved reads the hover the drag left behind, and by the time a slow provider has finished that hover can belong to a session that arrived since -- so the payload of one drop was handed to the target of another. A port that quotes back what `#hoverGeneration()` answered when the user released tells this apart: the hover is this drop's while the number still matches, and is somebody else's the moment it does not.

    ###### Parameters

    - `hoverGeneration`: what `#hoverGeneration()` answered when the drop began, or `#NO_HOVER_GENERATION` from a port that does not track it

  - ### hoverGeneration

    public static int hoverGeneration()
    The generation of the hover state a drop assembled later can quote back; see `#deferredDrop(int, int, int, com.codename1.ui.ClipboardContent, int, int, boolean, int)`.

  - ### plannedDropAction

    public static int plannedDropAction(int windowId, int x, int y, ClipboardContent content, int action)

    The action a drop at this position would perform, without dispatching anything or disturbing the drag in progress.

    A port whose platform commits to an action before it can read the transferred data -- AWT does, because a drop has to be accepted before it becomes readable -- asks here first, so that what it commits to is what `#drop(int, int, int, com.codename1.ui.ClipboardContent, int)` will go on to report. Committing the platform's own stale action instead told the source a copy had happened while the target was handed a move.

    ###### Parameters

    - `windowId`: the id of the window the drag is over, or zero for the main surface

    - `x`: the pointer position within that surface

    - `y`: the pointer position within that surface

    - `content`: the representations the drag is offering, which may still be a description rather than the materialized payload

    - `action`: the action the platform is proposing

    ###### Returns

    the action the drop would perform, or `NativeDragOperation#ACTION_NONE`

  - ### dragCompleted

    public static void dragCompleted(int performedAction)

    Reports that the session started by `#startDrag(com.codename1.ui.Component, com.codename1.ui.NativeDragOperation)` has finished, whatever the outcome, so that a source offering `NativeDragOperation#ACTION_MOVE` learns whether to delete its copy.

    ###### Parameters

    - `performedAction`: the action the receiver performed, or `NativeDragOperation#ACTION_NONE` when the drag was cancelled or refused