clipboard

README

native/clipboard

English | 简体中文

Reads a snapshot of the clipboard independently, without referencing the UI or Gio. Implemented for macOS 14+/cgo, Windows, Linux X11, and (when the app provides the connection) Linux Wayland; other platforms and iOS return native.ErrUnsupported.

clipboard.Read(func(data clipboard.Data, err error) {
    // Background goroutine; modifying the interface requires core.Update.
    // data.Text is text, Images is encoded pictures, and Files is file path.
})

• Read returns immediately and completes the callback by calling the background goroutine after reading from the main queue; nil callback does not read.
• Pictures are preferred PNG, otherwise TIFF, keep the encoded data, do not decode or convert pixels. The file URL is converted into a path; the image preview that comes with the file is not repeatedly counted as an image.
• Maximum of 128 pasteboard items, the total text/path UTF-8 bytes and image encoded data does not exceed 16MiB. native.ErrFailed is returned if the limit is exceeded, serialization fails, or the clipboard version changes during reading, and partial results are not returned.
• Does not write to the clipboard, does not open the referenced file, and does not read the file content; an empty clipboard returns empty Data successfully.
• Linux Wayland: Only the client with the keyboard focus can see the clipboard, so the connection of the focused window: clipboard.UseWaylandDisplay(w.WaylandDisplay()) is passed from the application and is re-passed when the focus changes to the window. Fallback to X11/XWayland when no connection is available or not supported by the synthesizer. This path loads libwayland-client at run time (no cgo); -tags nowayland leaves it out.
• Dependencies: native, native/internal/sys, native/internal/wlclip. The application can adapt the result to core.ClipboardData and connect it to Input/TextArea.PasteReader.

macOS has actually read the picture snapshot; the reading of Windows and Linux has passed the format and protocol test, but has not yet been accepted on the real device.

Documentation

Overview

Package clipboard reads a bounded snapshot of text, encoded images and file paths without linking to the UI. macOS uses AppKit; Windows uses Win32; Linux uses Wayland when given a display (UseWaylandDisplay), else X11.

Index

• func Read(done func(Data, error))
• func UseWaylandDisplay(display unsafe.Pointer)
• type Data
• type Image

Functions

func Read

func Read(done func(Data, error))

Read asynchronously reads the clipboard on the platform's required thread. done runs once on a background goroutine. UI callers must dispatch UI changes. macOS supports PNG/TIFF and file URLs, up to 128 items and 16MiB encoded data. Windows supports Unicode text, PNG or packed DIB (returned as image/bmp), and file paths, with the same limits. Linux reads text, file URIs and PNG/JPEG/TIFF/BMP/WebP over Wayland or X11. Other platforms return native.ErrUnsupported. Nil done is ignored.

func UseWaylandDisplay

func UseWaylandDisplay(display unsafe.Pointer)

UseWaylandDisplay makes Read use a Wayland connection, the wl_display of the application's focused window (window.Window.WaylandDisplay). Wayland shows the clipboard only to the focused client, so Read cannot open a connection of its own. Nil, or a display without a data device, falls back to X11 (XWayland). Pass the display again when focus moves to another window; it must stay open until Read completes.

Types

type Data

type Data struct {
	Text   string   `json:"text"`
	Images []Image  `json:"images"`
	Files  []string `json:"files"`
}

Data is one clipboard snapshot. Files are paths, not opened file contents.

type Image

type Image struct {
	MIME string `json:"mime"`
	Data []byte `json:"data"`
}

Image contains owned encoded image bytes, without decoding pixel data.