4.2. System clipboard

The clipboard module provides synchronous access to the operating system’s text clipboard. Text is always exchanged as UTF-8, including supplementary Unicode characters such as emoji.

All public symbols are in the clipboard module. Require the promoted wrapper rather than the internal clipboard_core module:

require clipboard/clipboard

[export]
def main() {
    if (clipboard_set_text("Hello, UTF-8") == ClipboardStatus.ok) {
        var text : string
        if (clipboard_get_text(text) == ClipboardStatus.ok) {
            print("{text}\n")
        }
    }
}

Use clipboard_capabilities before enabling clipboard UI. Unsupported targets, unavailable desktop sessions, transient contention, and invalid UTF-8 are reported through ClipboardStatus; the API does not substitute a process-local clipboard.

4.2.1. Type aliases

bitfield ClipboardCapabilities

bitfield<read_text;write_text;clear;synchronous;read_rich_text;write_rich_text;read_image;write_image> aka ClipboardCapabilities

bitfield ClipboardFormats

bitfield<plain_text;markdown;html;uri_list;image_rgba8> aka ClipboardFormats

4.2.2. Enumerations

ClipboardStatus

enum ClipboardStatus

4.2.3. Structures

ClipboardImage

Canonical transport image: straight-alpha RGBA8, top-to-bottom rows.

Fields:

• width : int = 0 - Width in pixels.

• height : int = 0 - Height in pixels.

• stride : int = 0 - Bytes per row, at least width * 4.

• rgba8 : array<uint8> - Pixel bytes, RGBA8 straight alpha, rows top to bottom.

ClipboardContent

One atomic offer set. Only fields selected by formats participate.

Fields:

• formats : ClipboardFormats - UTF-8 HTML fragment. Native transports add/remove platform wrappers.

• plain_text : string - Which of the representations below take part in the offer.

• markdown : string - UTF-8 plain text.

• html : string - UTF-8 Markdown source.

• uri_list : string - Newline-separated URIs.

• image : ClipboardImage = struct<clipboard::ClipboardImage>() - The image representation.

ClipboardMemory

Deterministic in-memory transport for tests, tools, and applications that need clipboard semantics without touching the desktop session.

Fields:

• content : ClipboardContent = struct<clipboard::ClipboardContent>() - The offer currently held.

• has_content : bool = false - Whether any offer is held.

• revision : int = 0 - Bumped on every write, so a reader can detect a change.

4.2.4. UTF-8 system clipboard

• clipboard_capabilities () : ClipboardCapabilities

• clipboard_clear () : ClipboardStatus

• clipboard_clone_content (content: ClipboardContent) : ClipboardContent

• clipboard_content_has_data (content: ClipboardContent) : bool

• clipboard_dispose_content (var content: ClipboardContent)

• clipboard_get_content (var content: ClipboardContent) : ClipboardStatus

• clipboard_get_text (var text: string&) : ClipboardStatus

• clipboard_memory_clear (var memory: ClipboardMemory)

• clipboard_memory_dispose (var memory: ClipboardMemory)

• clipboard_memory_read (memory: ClipboardMemory; var content: ClipboardContent) : ClipboardStatus

• clipboard_memory_write (var memory: ClipboardMemory; content: ClipboardContent) : ClipboardStatus

• clipboard_set_content (content: ClipboardContent) : ClipboardStatus

• clipboard_set_text (text: string) : ClipboardStatus

• clipboard_validate_content (content: ClipboardContent) : ClipboardStatus

clipboard_capabilities(): ClipboardCapabilities

def clipboard_capabilities () : ClipboardCapabilities

clipboard_clear(): ClipboardStatus

def clipboard_clear () : ClipboardStatus

clipboard_clone_content(content: ClipboardContent ): ClipboardContent

def clipboard_clone_content (content: ClipboardContent) : ClipboardContent

Arguments:

• content : ClipboardContent

clipboard_content_has_data(content: ClipboardContent ): bool

def clipboard_content_has_data (content: ClipboardContent) : bool

Arguments:

• content : ClipboardContent

clipboard_dispose_content(content: ClipboardContent )

def clipboard_dispose_content (var content: ClipboardContent)

Arguments:

• content : ClipboardContent

clipboard_get_content(content: ClipboardContent ): ClipboardStatus

Take one native snapshot of every supported representation.

Arguments:

• content : ClipboardContent

clipboard_get_text(text: string& ): ClipboardStatus

Read UTF-8 text into text. The output is empty for every non-ok result.

Arguments:

• text : string&

clipboard_memory_clear(memory: ClipboardMemory )

def clipboard_memory_clear (var memory: ClipboardMemory)

Arguments:

• memory : ClipboardMemory

clipboard_memory_dispose(memory: ClipboardMemory )

def clipboard_memory_dispose (var memory: ClipboardMemory)

Arguments:

• memory : ClipboardMemory

clipboard_memory_read(memory: ClipboardMemory; content: ClipboardContent ): ClipboardStatus

def clipboard_memory_read (memory: ClipboardMemory; var content: ClipboardContent) : ClipboardStatus

Arguments:

• memory : ClipboardMemory

• content : ClipboardContent

clipboard_memory_write(memory: ClipboardMemory; content: ClipboardContent ): ClipboardStatus

def clipboard_memory_write (var memory: ClipboardMemory; content: ClipboardContent) : ClipboardStatus

Arguments:

• memory : ClipboardMemory

• content : ClipboardContent

clipboard_set_content(content: ClipboardContent ): ClipboardStatus

Replace the system clipboard with all selected representations while holding one native clipboard lock. An empty offer set clears it.

Arguments:

• content : ClipboardContent

clipboard_set_text(text: string ): ClipboardStatus

Replace the system clipboard with UTF-8 text. Empty text clears it.

Arguments:

• text : string

clipboard_validate_content(content: ClipboardContent ): ClipboardStatus

def clipboard_validate_content (content: ClipboardContent) : ClipboardStatus

Arguments:

• content : ClipboardContent