zgui

Clipboard

Copy, read, and clear plain text through the desktop clipboard.

use_clipboard() returns the application's clipboard handle. Use it for clipboard commands outside a text field, such as a copy button or a menu item. field and editor already handle copy, cut and paste themselves.

Copy text

Resolve the handle in a component body, then capture it in a listener:

use zgui::prelude::*;

#[component]
fn CopyButton(value: String) -> impl IntoView {
    let clipboard = use_clipboard();

    view! {
        control(on:click = move |_| {
            clipboard.set_text(ClipboardKind::Standard, value.clone());
        }) {"Copy"}
    }
}

ClipboardKind::Standard is the clipboard used by Copy and Paste. set_text queues the write and returns immediately. An unsupported operation does nothing; it does not fail the frame.

Call clear(kind) to empty a clipboard.

Read text

A read is asynchronous. Use a callback when the answer causes an action:

let clipboard = use_clipboard();

clipboard.read_text(ClipboardKind::Standard, move |text| {
    if let Some(text) = text {
        insert_pasted_text(text);
    }
});

The callback runs later on the UI thread. It receives None when the clipboard is empty, does not contain text, or refuses the request. If the application stops first, zgui drops the callback without calling it.

A clipboard callback is not cancelled when the component that started it unmounts. Capture application-scope state, or another value that stays valid until the answer arrives. Do not capture a window-local signal unless that window is guaranteed to stay open.

When a view only needs to show one read result, use read_text_signal:

let clipboard = use_clipboard();
let text = clipboard.read_text_signal(ClipboardKind::Standard);

view! {
    text() {{move || text.get().unwrap_or_else(|| "No text".into())}}
}

The signal holds None both before the answer arrives and when no text is available. If you need to tell the two apart, use read_text and keep your own loading state.

Use the primary selection

ClipboardKind::Primary is the selection clipboard used by middle-button paste on Linux and BSD. It is separate from the standard clipboard. Other desktops have no equivalent, and operations on it do nothing there.

Check support before showing a primary-selection command:

let supported = use_windows().capabilities().clipboard_primary_selection;

Copy and paste in text fields

field and editor handle the standard editing chords themselves, with Ctrl on Linux and Windows and Cmd on macOS:

ChordEffect
Copy (C)puts the selected text on the standard clipboard
Cut (X)copies the selection and deletes it
Paste (V)reads the standard clipboard and replaces the selection, as one undoable change

The dedicated Copy, Cut and Paste keys do the same. A paste into a single-line field joins the pasted lines; an editor keeps them. A read-only field still selects and copies, but does not cut or paste. A field that becomes disabled before the clipboard answers ignores the answer.

Limits

  • Plain text is the only data type. Rich text, files and images are not supported.
  • The handle, Clipboards, is provided above every window. All windows share it, and a request can complete while another window has focus.
  • The handle is UI-thread state. Background work must post clipboard operations back with task::ui; see Background work.
  • try_use_clipboard() returns None instead of panicking when no application scope is active.

Next

On this page