Skip to main content

ClipboardBackend

tilo_app::clipboard

Trait ClipboardBackend 

pub trait ClipboardBackend: Send + Sync {
    // Required methods
    fn set_text(&self, target: ClipboardTarget, text: &str) -> bool;
    fn text(&self, target: ClipboardTarget) -> Option<String>;
    fn name(&self) -> &'static str;

    // Provided methods
    fn request_text(&self, target: ClipboardTarget) -> Receiver<Option<String>> { ... }
    fn rich_text(&self) -> Option<RichTextOffer> { ... }
    fn set_rich_text(&self, html: &str, plain: &str) -> bool { ... }
    fn set_image(&self, width: usize, height: usize, rgba: &[u8]) -> bool { ... }
    fn image(&self) -> Option<ClipboardImage> { ... }
    fn set_shared_text(&self, target: ClipboardTarget, text: &str) -> bool { ... }
    fn set_secret_text(&self, text: &str) -> bool { ... }
    fn copy(&self, content: CopyContent<'_>) -> ClipboardCopy { ... }
    fn reserve_text(&self) -> Option<ReservedCopy> { ... }
}
Expand description

A source of clipboard content for this process.

Implementors must be cheap to call and must never block on the compositor’s event loop from a widget’s event handler — a host backend reads a mirror in memory, and the Wayland backend does its protocol work on its own thread.

Required Methods§

fn set_text(&self, target: ClipboardTarget, text: &str) -> bool

Take ownership of target and offer text on it. Returns false if the backend could not.

fn text(&self, target: ClipboardTarget) -> Option<String>

Read target as UTF-8. None when it is empty, unavailable, or holds something that is not text.

fn name(&self) -> &'static str

Short name for diagnostics, e.g. "compositor-mirror".

Provided Methods§

fn request_text(&self, target: ClipboardTarget) -> Receiver<Option<String>>

Request text for an explicit paste. A native transfer may finish after this call returns; the backend must wake its owner when it answers. No answer may substitute text from an older selection or focus owner.

fn rich_text(&self) -> Option<RichTextOffer>

Read HTML and its plain fallback from one Ctrl+V clipboard offer. Optional: unsupported backends return None without reading plain text. A successful read consumes event-scoped offers; use the captured plain fallback if decoding refuses the HTML. Never reread to recover a stale selection, a permission refusal, or an active composition.

fn set_rich_text(&self, html: &str, plain: &str) -> bool

Take the Ctrl+C clipboard and offer formatted text on it: html as text/html and plain as its plain-text fallback, both from one copy, so an app that reads formatting pastes the formatting and every other app the words. Returns false if the backend could not.

The default offers only plain, for a backend that carries no formatting; every system clipboard overrides it.

fn set_image(&self, width: usize, height: usize, rgba: &[u8]) -> bool

Offer an RGBA8 image on the clipboard. Optional: the default refuses, which is appropriate for backends that only carry text.

fn image(&self) -> Option<ClipboardImage>

The image on the Ctrl+V clipboard, when it holds one: a screenshot, an image copied in a viewer or a browser. Optional: the default reads none, which is right for backends that only carry text.

fn set_shared_text(&self, target: ClipboardTarget, text: &str) -> bool

Offer text only where other processes can read it. Returns false rather than keeping it in a buffer private to this process, so a secret is never reported as copied when it was not. The default is set_text, right for a backend that only reaches a shared clipboard.

fn set_secret_text(&self, text: &str) -> bool

Offer text on the Ctrl+V clipboard marked as a secret: a password, a one-time code, an enrolment token. Other apps can still paste it as plain text, but clipboard managers and Tilo’s own history and device sync are told not to keep it (SECRET_MIME, PASSWORD_MANAGER_HINT_MIME).

Returns false rather than keeping the secret in a buffer private to this process, so it is never reported as copied when it was not. The default refuses: a backend must opt in to carrying secrets.

fn copy(&self, content: CopyContent<'_>) -> ClipboardCopy

Start a Ctrl+C copy without waiting for it, and answer its outcome through the returned ClipboardCopy. A copy through an app’s own Wayland connection waits on compositor roundtrips; this lets the UI thread go on while it does, and wakes the app when it settles.

The default copies now through the methods above, so its outcome is settled before this returns.

fn reserve_text(&self) -> Option<ReservedCopy>

Hold a Ctrl+C copy for text that is not known yet: a link the person’s click asks a host for. A browser copies only inside the click, so a backend with that rule claims the clipboard now and fills it once ReservedCopy::fill hands the text over. None when this backend copies just as well later, or has no way to claim the clipboard now; the text is then copied when it arrives.

Implementors§