Repository files navigation

Documentation (master)

A safe Rust crate for working with the Wayland clipboard.

This crate is intended to be used by terminal applications, clipboard managers and otherutilities which don't spawn Wayland surfaces (windows). If your application has a window,please use the appropriate Wayland protocols for interacting with the Wayland clipboard(wl_data_device from the core Wayland protocol, theprimary_selection protocol for theprimary selection), for example via thesmithay-clipboard crate.

The protocol used for clipboard interaction isext-data-control orwlr-data-control. Whenusing the regular clipboard, the compositor must support any version of either protocol. Whenusing the "primary" clipboard, the compositor must support any version ofext-data-control,or the second version of thewlr-data-control protocol.

For example applications using these features, seewl-clipboard-rs-tools/src/bin/wl_copy.rsandwl-clipboard-rs-tools/src/bin/wl_paste.rs which implement terminal apps similar towl-clipboard orwl-clipboard-rs-tools/src/bin/wl_clip.rs which implements a Wayland version ofxclip.

The Rust implementation of the Wayland client is used by default; use thenative_lib featureto link tolibwayland-client.so for communication instead. Adlopen feature is alsoavailable for loadinglibwayland-client.so dynamically at runtime rather than linking to it.

The code of the crate itself (and the code of the example utilities) is 100% safe Rust. Thisdoesn't include the dependencies.

Copying to the regular clipboard:

use wl_clipboard_rs::copy::{MimeType,Options,Source};let opts =Options::new();opts.copy(Source::Bytes("Hello world!".to_string().into_bytes().into()),MimeType::Autodetect)?;

Pasting plain text from the regular clipboard:

use std::io::Read;use wl_clipboard_rs::{paste::{get_contents,ClipboardType,Error,MimeType,Seat}};let result =get_contents(ClipboardType::Regular,Seat::Unspecified,MimeType::Text);match result{Ok((mut pipe, _)) =>{letmut contents =vec![];        pipe.read_to_end(&mut contents)?;println!("Pasted: {}",String::from_utf8_lossy(&contents));}Err(Error::NoSeats) |Err(Error::ClipboardEmpty) |Err(Error::NoMimeType) =>{// The clipboard is empty or doesn't contain text, nothing to worry about.}Err(err) =>Err(err)?}

Checking if the "primary" clipboard is supported (note that this might be unnecessary dependingon your crate usage, the regular copying and pasting functions do report if the primaryselection is unsupported when it is requested):

use wl_clipboard_rs::utils::{is_primary_selection_supported,PrimarySelectionCheckError};matchis_primary_selection_supported(){Ok(supported) =>{// We have our definitive result. False means that ext/wlr-data-control is present// and did not signal the primary selection support, or that only wlr-data-control// version 1 is present (which does not support primary selection).},Err(PrimarySelectionCheckError::NoSeats) =>{// Impossible to give a definitive result. Primary selection may or may not be// supported.// The required protocol (ext-data-control, or wlr-data-control version 2) is there,// but there are no seats. Unfortunately, at least one seat is needed to check for the// primary clipboard support.},Err(PrimarySelectionCheckError::MissingProtocol) =>{// The data-control protocol (required for wl-clipboard-rs operation) is not// supported by the compositor.},Err(_) =>{// Some communication error occurred.}}

• wl-paste: implementswl-paste fromwl-clipboard.
• wl-copy: implementswl-copy fromwl-clipboard.
• wl-clip: a Wayland version ofxclip.

Stuff that would be neat to add:

• Utility that mimicsxsel commandline flags.

License: MIT/Apache-2.0