Interface ClipboardDataProvider

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.

  • Method Summary

    Modifier and Type
    Method
    Description
    Object
    getClipboardData(String mimeType)
    Produces the value for one representation.

  • Method Details

    • getClipboardData

      Object getClipboardData(String mimeType)

      Produces the value for one representation.

      Parameters
      • mimeType: the MIME type being requested, always one this provider was registered for
      Returns

      the value, normally a String, a String[] of file paths or a byte[], or null when the representation turned out to be unavailable