Package com.vaadin.flow.component.clipboard

Class ClipboardBinding

java.lang.Object
com.vaadin.flow.component.clipboard.ClipboardBinding
All Implemented Interfaces:
Serializable
public final class ClipboardBinding extends Object implements Serializable
Fluent surface returned from Clipboard.onClick(T), used to declare what a click should write to or read from the clipboard. The write* methods copy a value (literal text, a field's value, HTML, or an image) to the clipboard; the read* methods read the clipboard contents back. The action runs in the browser at click time, while the user gesture required for clipboard access is still valid.

Write actions come in two flavours: fire-and-forget (one argument) and observed (with onCopied/onError callbacks). onCopied receives the string that was copied; onError receives the browser's error. Both consumers are required in the observed form ? pass s -> {} or err -> {} to opt out of one.

Read actions always take both an onPayload consumer (receiving the clipboard contents or null if empty) and an onError consumer (receiving the browser's error, typically "NotAllowedError" when the user denied the clipboard-read permission). 


 Button copy = new Button("Copy");
 Clipboard.onClick(copy).writeText(textField);

 Clipboard.onClick(copy).writeText(textField,
         copied -> Notification.show("Copied " + copied),
         err -> Notification.show("Failed: " + err.message()));

 Button paste = new Button("Paste");
 Clipboard.onClick(paste).readText(
         text -> Notification.show("Pasted " + text),
         err -> Notification.show("Failed: " + err.message()));
Since:
25.2
See Also:

  • Method Details

    • writeText

      public void writeText(String literal)
      Copies a literal string to the clipboard as text/plain when the underlying trigger fires.
      Parameters:
      literal - the value to copy, not null

    • writeText

      public void writeText(String literal, SerializableConsumer<@Nullable String> onCopied, SerializableConsumer<PromiseAction.Error> onError)
      Like writeText(String) but reports the outcome of the write promise back to the server.
      Parameters:
      literal - the value, not null
      onCopied - UI-thread callback receiving the copied string, not null
      onError - UI-thread callback receiving the browser's error, not null

    • writeText

      public <C extends Component & HasValue<?, String>> void writeText(C source)
      Copies the current value property of the given component (typically an input field) to the clipboard as text/plain when the underlying trigger fires. The value is read on the client at the moment the trigger fires, so subsequent edits are reflected without any server round-trip.
      Type Parameters:
      C - component type implementing HasValue<?, String>
      Parameters:
      source - the component whose value should be copied, not null

    • writeText

      public <C extends Component & HasValue<?, String>> void writeText(C source, SerializableConsumer<@Nullable String> onCopied, SerializableConsumer<PromiseAction.Error> onError)
      Like writeText(Component) but reports the outcome back to the server.
      Type Parameters:
      C - component type implementing HasValue<?, String>
      Parameters:
      source - the component whose value should be copied, not null
      onCopied - UI-thread callback receiving the copied string, not null
      onError - UI-thread callback receiving the browser's error, not null

    • writeHtml

      public void writeHtml(String literal)
      Copies a literal HTML string to the clipboard as text/html when the underlying trigger fires.
      Parameters:
      literal - the HTML, not null

    • writeHtml

      public void writeHtml(String literal, SerializableConsumer<@Nullable String> onCopied, SerializableConsumer<PromiseAction.Error> onError)
      Like writeHtml(String) but reports the outcome back to the server.
      Parameters:
      literal - the HTML, not null
      onCopied - UI-thread callback receiving the copied HTML, not null
      onError - UI-thread callback receiving the browser's error, not null

    • writeImage

      public void writeImage(Component source)
      Copies the given component's root <img> element to the clipboard as image/png when the underlying trigger fires. The image is drawn on a canvas and exported as PNG on the client, so the source can be any rasterisable format (image/png, image/jpeg, image/svg+xml, ...) as long as it has intrinsic dimensions.

      Cross-origin images need crossorigin="anonymous" on the <img> plus matching CORS headers; otherwise the canvas is tainted and the write fails. Same-origin and data: URLs always work.

      Parameters:
      source - the component whose root <img> should be copied, not null
      Throws:
      IllegalArgumentException - if the source's root element is not an <img>

    • writeImage

      public void writeImage(Component source, SerializableRunnable onCopied, SerializableConsumer<PromiseAction.Error> onError)
      Like writeImage(Component) but reports the outcome back to the server. An image-only write has no string value, so success is reported as a plain SerializableRunnable rather than a value callback.
      Parameters:
      source - the component whose root <img> should be copied, not null
      onCopied - UI-thread callback invoked once the write resolves, not null
      onError - UI-thread callback receiving the browser's error, not null
      Throws:
      IllegalArgumentException - if the source's root element is not an <img>

    • writeImage

      public void writeImage(DownloadHandler handler)
      Copies the image served by the given DownloadHandler to the clipboard as image/png when the underlying trigger fires.

      A hidden <img> bound to the handler is appended to the trigger host, so the browser begins downloading the image as soon as this method is called ? well before the user can click. At fire time the image is already decoded (or finishes decoding inside the canvas converter's load listener), drawn onto a canvas, and exported as PNG.

      Cross-origin concerns do not apply because the handler is served by the same origin as the application.

      Parameters:
      handler - the download handler producing the image bytes, not null

    • writeImage

      public void writeImage(DownloadHandler handler, SerializableRunnable onCopied, SerializableConsumer<PromiseAction.Error> onError)
      Like writeImage(DownloadHandler) but reports the outcome back to the server. An image-only write has no string value, so success is reported as a plain SerializableRunnable rather than a value callback.
      Parameters:
      handler - the download handler producing the image bytes, not null
      onCopied - UI-thread callback invoked once the write resolves, not null
      onError - UI-thread callback receiving the browser's error, not null

    • write

      public void write(ClipboardContent content)
      Copies a multi-format payload to the clipboard, packed into a single ClipboardItem.
      Parameters:
      content - the content, not null; must have at least one slot set
      Throws:
      IllegalArgumentException - if content has no slots set

    • write

      public void write(ClipboardContent content, SerializableConsumer<@Nullable String> onCopied, SerializableConsumer<PromiseAction.Error> onError)
      Like write(ClipboardContent) but reports the outcome back to the server.
      Parameters:
      content - the content, not null; must have at least one slot set
      onCopied - UI-thread callback receiving the text/plain value if present, otherwise the text/html value, not null
      onError - UI-thread callback receiving the browser's error, not null

    • read

      public void read(SerializableConsumer<@Nullable ClipboardPayload> onPayload, SerializableConsumer<PromiseAction.Error> onError)
      Reads the user's clipboard via navigator.clipboard.read() when the underlying trigger fires and delivers the contents to onPayload, or routes any failure to onError.

      The Clipboard API requires the call to happen inside a short-lived user gesture AND the user to grant the clipboard-read permission; binding to a click trigger satisfies the gesture, but the browser may still reject the read with "NotAllowedError" when the permission is denied.

      Parameters:
      onPayload - UI-thread callback receiving the clipboard contents, or null if the clipboard was empty; not null
      onError - UI-thread callback receiving the browser's error, not null

    • readText

      public void readText(SerializableConsumer<@Nullable String> onText, SerializableConsumer<PromiseAction.Error> onError)
      Like read(com.vaadin.flow.function.SerializableConsumer<com.vaadin.flow.component.clipboard.ClipboardPayload>, com.vaadin.flow.function.SerializableConsumer<com.vaadin.flow.component.trigger.internal.PromiseAction.Error>) but delivers only the text/plain field of the clipboard payload to onText. onText receives null if the clipboard was empty or had no text/plain representation.
      Parameters:
      onText - UI-thread callback receiving the text/plain value, or null; not null
      onError - UI-thread callback receiving the browser's error, not null

    • readHtml

      public void readHtml(SerializableConsumer<@Nullable String> onHtml, SerializableConsumer<PromiseAction.Error> onError)
      Like read(com.vaadin.flow.function.SerializableConsumer<com.vaadin.flow.component.clipboard.ClipboardPayload>, com.vaadin.flow.function.SerializableConsumer<com.vaadin.flow.component.trigger.internal.PromiseAction.Error>) but delivers only the text/html field of the clipboard payload to onHtml. onHtml receives null if the clipboard was empty or had no text/html representation.
      Parameters:
      onHtml - UI-thread callback receiving the text/html value, or null; not null
      onError - UI-thread callback receiving the browser's error, not null