Package org.zkoss.zkforge.clipboard

Class ClipboardHelper

  • public class ClipboardHelper
extends Object
    Static helper class that provides Java access to the browser's Clipboard API.

    This class wraps the native browser Clipboard API and provides static methods to read from and write to the system clipboard. All operations are asynchronous and require user interaction due to browser security restrictions.

    Important: Clipboard operations must be triggered from user interactions (click, keypress, etc.) as they will fail if called outside of event handlers.

    Security Note: When handling clipboard content, sanitize user input to prevent potential security vulnerabilities.

    Example usage:

    
 // Reading from clipboard (results delivered via desktop events)
 ClipboardHelper.readText();
 
 // Writing to clipboard
 ClipboardHelper.writeText("Hello World");

    Results are delivered asynchronously via ClipboardEvent posted to the desktop. Components can listen for these events to handle clipboard results.

    Based on MDN Clipboard API

    • Constructor Detail

      • ClipboardHelper

        public ClipboardHelper()

    • Method Detail

      • writeText

        public static void writeText​(String text)
        Write text to the system clipboard. Results are delivered asynchronously via ClipboardEvent.
        Parameters:
        text - the text to write to the clipboard
        Throws:
        IllegalStateException - if called outside an execution context

      • writeTextTo

        public static void writeTextTo​(org.zkoss.zk.ui.Component targetComponent,
                               String text)
        Write text to the system clipboard and deliver confirmation event to a specific component. Results are delivered asynchronously via ClipboardEvent to the target component only. If target is null, broadcasts to the desktop.
        Parameters:
        targetComponent - the component that will receive the clipboard write confirmation event, or null to broadcast to the desktop
        text - the text to write to the clipboard
        Throws:
        IllegalStateException - if called outside an execution context

      • readText

        public static void readText()
        Read text from the system clipboard. Results are delivered asynchronously via ClipboardEvent.
        Throws:
        IllegalStateException - if called outside an execution context

      • readTextTo

        public static void readTextTo​(org.zkoss.zk.ui.Component targetComponent)
        Read text from the system clipboard and deliver the result event to a specific component. Results are delivered asynchronously via ClipboardEvent to the target component only. If target is null, broadcasts to the desktop.
        Parameters:
        targetComponent - the component that will receive the clipboard read result event, or null to broadcast to the desktop
        Throws:
        IllegalStateException - if called outside an execution context

      • readImage

        public static void readImage()
        Read image from the system clipboard. Results are delivered asynchronously via ClipboardEvent.
        Throws:
        IllegalStateException - if called outside an execution context

      • readImageTo

        public static void readImageTo​(org.zkoss.zk.ui.Component targetComponent)
        Read image from the system clipboard and deliver the result event to a specific component. Results are delivered asynchronously via ClipboardEvent to the target component only. If target is null, broadcasts to the desktop.
        Parameters:
        targetComponent - the component that will receive the clipboard image read result event, or null to broadcast to the desktop
        Throws:
        IllegalStateException - if called outside an execution context

      • init

        public static void init()
        Initialize clipboard helper for the current desktop if not already initialized. This method ensures the AU service and JavaScript are properly set up. You should call this method before you call any action like writeText(String) or readText(). You should call this method in a Composer's life cycle method e.g. Composer.doAfterCompose(Component).

      • addHelperScript

        protected static void addHelperScript()

      • dispose

        public static void dispose()
        Dispose clipboard helper for the current desktop. Removes the AU service listener and JavaScript helper for this desktop.
        Throws:
        IllegalStateException - if called outside an execution context

      • ensureExecutionAvailable

        protected static void ensureExecutionAvailable()