Struct arboard::Clipboard

source ·
pub struct Clipboard {
    pub(crate) platform: Clipboard,
}
Expand description

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.

Fields§

§platform: Clipboard

Implementations§

source§

impl Clipboard

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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

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

source

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

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

source

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

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

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

impl<T> Pointable for T

source§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.