dymokomi/luce-clipboard
Source of release 0.7.0
0.7.0 / src / clipboard / module.lucb
#==============================================================================================
#
# clipboard - The desktop clipboard: text and images
#
# DESCRIPTION:
# Desktop text and image clipboard. Values returned to Base or Luce own their bytes.
# Access belongs to the UI thread; clipboard contention is a recoverable error.
# Images go out as PNG (and on Windows also as a bitmap, which most programs there
# read) and come back as PNG or TIFF bytes, or as RGBA pixels from a bitmap. On Linux
# the clipboard is X11's CLIPBOARD selection (linux/service).
#
#==============================================================================================
import c
import interop
import memory
import platform
import sync
import thread
import time
from luce_std import collections, utf8
from luce_window import window
import windows_text
from dib import dib_to_bitmap, bitmap_to_dib
from latin1 import latin1_to_utf8, utf8_length_of_latin1, utf8_to_latin1
## Clipboard access failed, or its text was rejected.
pub let failed: ErrorCode = ErrorCode.package(117)
let text_limit: usize = 1048576
## The clipboard's text, owning its bytes; fails off the UI thread or on an unsupported target.
pub func read_text() -> interop.Owned[str]!:
try check_access()
if platform.macos:
return try mac_read()
elif platform.windows:
return try win_read()
elif platform.linux:
return try linux_read()
else:
error(window.unsupported, "the desktop clipboard is unavailable on this target")
## Publish `text` (valid UTF-8, no NUL, at most 1 MiB) to the clipboard from the UI thread.
pub func write_text(text: str) -> !:
try check_access()
if text.length > text_limit or not utf8.valid(text.bytes):
error(failed, "clipboard text must be valid UTF-8 within 1 MiB")
for byte in text.bytes:
if byte == 0:
error(failed, "clipboard text cannot contain NUL")
if platform.macos:
try mac_write(text)
elif platform.windows:
try win_write(text)
elif platform.linux:
try linux_write(text)
else:
error(window.unsupported, "the desktop clipboard is unavailable on this target")
## An image read from the clipboard: encoded bytes (PNG or TIFF, told apart by
## their signature), or 8-bit sRGB RGBA pixels, top-down, when the clipboard held
## a bitmap. Both are heap storage the holder frees with `destroy`.
pub struct ClipboardImage:
pub var encoded: u8[]
pub var rgba: u8[]
pub var width: u32
pub var height: u32
pub func destroy():
if self.encoded.length > 0:
free(self.encoded) in memory.heap
if self.rgba.length > 0:
free(self.rgba) in memory.heap
var empty: u8[]
self.encoded = empty
self.rgba = empty
## The largest image the clipboard takes or gives, in bytes either way.
let image_limit: usize = 536870912
## The clipboard's image, or none when it holds none; UI thread only.
pub func read_image() -> ClipboardImage?!:
try check_access()
if platform.macos:
return try mac_read_image()
elif platform.windows:
return try win_read_image()
elif platform.linux:
return try linux_read_image()
else:
error(window.unsupported, "the desktop clipboard is unavailable on this target")
## Publish an image, replacing what the clipboard held: `png` is it encoded, and
## `rgba` its 8-bit sRGB RGBA pixels, `width` by `height`, top-down, for
## programs that read bitmaps (Windows). UI thread only.
pub func write_image(png: const u8[], width: u32, height: u32, rgba: const u8[]) -> !:
try check_access()
if png.length == 0 or png.length > image_limit or width == 0 or height == 0 or (usize)width * (usize)height * 4 != rgba.length:
error(failed, "a clipboard image needs its PNG and width * height RGBA pixels")
if platform.macos:
try mac_write_image(png)
elif platform.windows:
try win_write_image(png, width, height, rgba)
elif platform.linux:
try linux_write_image(png)
else:
error(window.unsupported, "the desktop clipboard is unavailable on this target")
func check_access() -> !:
if not window.supported():
error(window.unsupported, "the desktop clipboard is unavailable on this target")
if not thread.is_main():
error(interop.wrong_thread, "clipboard access requires the UI thread")