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:
| Chord | Effect |
|---|---|
| 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()returnsNoneinstead of panicking when no application scope is active.
Next
Keyboard and focus
Make elements focusable, style focus, add shortcuts, move focus from code, trap focus in a dialog, and handle keys in text fields.
Scrolling
Make an element scroll, scroll to an element from code, react to scrolling, build long virtualised lists, and how wheel, trackpad and touch input scroll.