Struct arboard::Clipboard

pub struct Clipboard { /* private fields */ }

The OS independent struct for accessing the clipboard.

Any number of Clipboard instances are allowed to exist at a single point in time. Note however that all Clipboards must be ‘dropped’ before the program exits. In most scenarios this happens automatically but there are frameworks (for example, winit) that take over the execution and where the objects don’t get dropped when the application exits. In these cases you have to make sure the object is dropped by taking ownership of it in a confined scope when detecting that your application is about to quit.

It is also valid to have these multiple Clipboards on separate threads at once but note that executing multiple clipboard operations in parallel might fail with a ClipboardOccupied error.

Platform-specific behavior

arboard does its best to abstract over different platforms, but sometimes the platform-specific behavior leaks through unsolvably. These differences, depending on which platforms are being targeted, may affect your app’s clipboard architecture (ex, opening and closing a Clipboard every time or keeping one open in some application/global state).

Linux

Using either Wayland and X11, the clipboard and its content is “hosted” inside of the application that last put data onto it. This means that when the last Clipboard instance is dropped, the contents may become unavailable to other apps. See [SetExtLinux] for more details.

Windows

The clipboard on Windows is a global object, which may only be opened on one thread at once. This means that arboard only truly opens the clipboard during each operation to prevent multiple Clipboards from existing at once.

This means that attempting operations in parallel has a high likelihood to return an error or deadlock. As such, it is recommended to avoid creating/operating clipboard objects on >1 thread.

Implementations

impl Clipboard

pub fn new() -> Result<Self, Error>

Creates an instance of the clipboard.

Errors

On some platforms or desktop environments, an error can be returned if clipboards are not supported. This may be retried.

pub fn get_text(&mut self) -> Result<String, Error>

Fetches UTF-8 text from the clipboard and returns it.

Errors

Returns error if clipboard is empty or contents are not UTF-8 text.

pub fn set_text<'a, T: Into<Cow<'a, str>>>( &mut self, text: T, ) -> Result<(), Error>

Places the text onto the clipboard. Any valid UTF-8 string is accepted.

Errors

Returns error if text failed to be stored on the clipboard.

pub fn set_html<'a, T: Into<Cow<'a, str>>>( &mut self, html: T, alt_text: Option<T>, ) -> Result<(), Error>

Places the HTML as well as a plain-text alternative onto the clipboard.

Any valid UTF-8 string is accepted.

Errors

Returns error if both html and alt_text failed to be stored on the clipboard.

pub fn get_image(&mut self) -> Result<ImageData<'static>, Error>

Fetches image data from the clipboard, and returns the decoded pixels.

Any image data placed on the clipboard with set_image will be possible read back, using this function. However it’s of not guaranteed that an image placed on the clipboard by any other application will be of a supported format.

Errors

Returns error if clipboard is empty, contents are not an image, or the contents cannot be converted to an appropriate format and stored in the ImageData type.

pub fn set_image(&mut self, image: ImageData<'_>) -> Result<(), Error>

Places an image to the clipboard.

The chosen output format, depending on the platform is the following:

• On macOS: NSImage object
• On Linux: PNG, under the atom image/png
• On Windows: In order of priority CF_DIB and CF_BITMAP

Errors

Returns error if image cannot be converted to an appropriate format or if it failed to be stored on the clipboard.

pub fn clear(&mut self) -> Result<(), Error>

Clears any contents that may be present from the platform’s default clipboard, regardless of the format of the data.

Errors

Returns error on Windows or Linux if clipboard cannot be cleared.

pub fn clear_with(&mut self) -> Clear<'_>

Begins a “clear” option to remove data from the clipboard.

pub fn get(&mut self) -> Get<'_>

Begins a “get” operation to retrieve data from the clipboard.

pub fn set(&mut self) -> Set<'_>

Begins a “set” operation to set the clipboard’s contents.