Package limn.transfer

Class Transfer

java.lang.Object
limn.transfer.Transfer
public final class Transfer extends Object
One item, offered in several formats at once: what a copy puts on the clipboard and what a drag carries. The taker picks the richest format it understands, so offer the same thing every way it can usefully be had: 

 Transfer rows = Transfer.of(DataFormat.TEXT, tabSeparated)
         .with(DataFormat.HTML, htmlTable)
         .with(ORDERS, selectedOrders);
 scene.clipboard().set(rows);

Immutable: with(limn.transfer.DataFormat<T>, T) answers a new transfer. The formats keep the order they were added in, which is the order of preference a taker is shown.

  • Field Details

    • EMPTY

      public static final Transfer EMPTY
      A transfer of nothing: what empties the clipboard.

  • Method Details

    • of

      public static <T> Transfer of(DataFormat<T> format, T value)
      A transfer of one value in one format.
      Type Parameters:
      T - the type of the value
      Parameters:
      format - the format
      value - the value
      Returns:
      the transfer

    • with

      public <T> Transfer with(DataFormat<T> format, T value)
      This transfer and one more format. A format already there keeps its place and takes the new value.
      Type Parameters:
      T - the type of the value
      Parameters:
      format - the format
      value - the value
      Returns:
      the new transfer

    • withLazy

      public <T> Transfer withLazy(DataFormat<T> format, Supplier<? extends T> value)
      This transfer and one more format, whose value is made only if somebody asks for it: a large picture costs nothing to copy until it is pasted. The supplier is called on the UI thread, at most once, and must not answer null. If nobody asks before the application ends, it is never called.
      Type Parameters:
      T - the type of the value
      Parameters:
      format - the format
      value - what makes the value
      Returns:
      the new transfer

    • withImageAsFile

      public Transfer withImageAsFile(String name)
      Offers the picture this transfer carries as a file too: a PNG, written to the temporary directory the first time a taker asks for files, and not before. It is for the programs that take a picture only as a file: the desktop, a file manager's folder.

      Not what a transfer of a picture does by itself: a file is written to disk for it, and where a system asks for a drag's files as the drag begins (macOS does) that is at every drag. The files go in one directory made for this run of the program, under the system's temporary directory. The file of the transfer before is deleted when the next one is written, so that a program left running does not fill the disk one picture a drag, and the directory with whatever is left in it when the program ends. A taker that wants the picture for longer copies it, as a file manager does.

      Parameters:
      name - the file's name, without a directory: "logo.png"
      Returns:
      the new transfer
      Throws:
      IllegalStateException - if this transfer carries no DataFormat.IMAGE
      IllegalArgumentException - if the name is empty or names a directory

    • formats

      public Set<DataFormat<?>> formats()
      Returns:
      the formats, in the order they were added

    • has

      public boolean has(DataFormat<?> format)
      Parameters:
      format - a format
      Returns:
      whether this transfer has it

    • isReady

      public boolean isReady(DataFormat<?> format)
      Parameters:
      format - a format
      Returns:
      whether the value is at hand: the transfer has the format, and it is not a lazy value still waiting to be made

    • isEmpty

      public boolean isEmpty()
      Returns:
      whether this transfer carries nothing

    • needsUiThread

      public boolean needsUiThread(DataFormat<?> format)
      Whether a format's value has still to be made, and by the UI thread: what an application's withLazy(limn.transfer.DataFormat<T>, java.util.function.Supplier<? extends T>) value is. A backend handing a transfer to another program reads this to know that asking from another thread means waiting for the UI thread.
      Parameters:
      format - the format
      Returns:
      false when the value is at hand, or can be made on the thread that asks

    • get

      public <T> @Nullable T get(DataFormat<T> format)
      The value in one format, making a lazy one now. UI thread when the value is lazy.
      Type Parameters:
      T - the type of its value
      Parameters:
      format - the format
      Returns:
      the value, or null when this transfer does not have the format

    • asOffer

      public Offer asOffer()
      This transfer as something to take from: every read completes at once.
      Returns:
      the offer

    • toString

      public String toString()
      Overrides:
      toString in class Object