public final class NativeDragAndDrop

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.