public interface ClipboardDataProvider

Produces a clipboard or drag-and-drop representation on demand, so a payload that is expensive to build is only built if something actually asks for it.

This is what makes “drag a file out of the application” workable. A drag that offers ClipboardContent#MIME_FILE has to name the file when the drag starts, but the drop may never happen – the user may let go over nothing – and the target may prefer a different representation entirely. Registering a provider with ClipboardContent#setDataProvider(java.lang.String, com.codename1.ui.ClipboardDataProvider) declares that the representation is available without paying for it up front; the bytes are written, or the temporary file created, at the moment the receiving application reads that MIME type.

A provider is invoked at most once per ClipboardContent and MIME type – the result is cached – and it may be invoked from a native drag or clipboard thread rather than the event dispatch thread, so it must not touch the user interface.

When it actually runs

For a drag, on the desktop and on iOS the provider runs when a receiver reads that representation, so a drag the user abandons costs nothing. Android is the exception: startDragAndDrop takes a complete clip, and a clip carries text or a reference to a file that already exists, so every provider runs as the drag begins. A drag out of an iOS application resolves its file list at the same moment for a related reason – the system needs the number of items the drag carries, and for a file drag that is the number of files.

For a copy, it depends on what the platform’s clipboard is. A desktop clipboard holds a live handle back into this application, so nothing is read until a receiver pastes. The iOS pasteboard and the Android clipboard are system stores that outlive the application: whatever is copied has to survive this process being killed, and a promise that can only be kept while the process is alive is not something to put on a clipboard. So copying resolves every representation there, and it is right that it does – a lazy pasteboard entry would paste as nothing the moment the application went away.

So a provider should be cheap enough to run once per drag or copy, and must not assume it will only run when its data is wanted.