Arboard

https://docs.rs/arboard/latest/
Admin
Arboard is an OS-independent Rust library providing a unified interface for accessing and...
Tokens:74,041
Snippets:433
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Clear secondary clipboard example

Source: https://docs.rs/arboard/latest/arboard/trait.ClearExtLinux.html

Example usage of the clipboard method to clear the secondary clipboard.

```rust
let mut clipboard = Clipboard::new()?;

clipboard
    .clear_with()
    .clipboard(LinuxClipboardKind::Secondary)?;
```

--------------------------------

### SetExtLinux trait definition and example

Source: https://docs.rs/arboard/latest/arboard/trait.SetExtLinux.html?search=u32+-%3E+bool

The trait definition and an example usage of the SetExtLinux trait.

```rust
pub trait SetExtLinux: Sealed {
    // Required methods
    fn wait(self) -> Self;
    fn wait_until(self, deadline: Instant) -> Self;
    fn clipboard(self, selection: LinuxClipboardKind) -> Self;
    fn exclude_from_history(self) -> Self;
}
```

```rust
use arboard::{Clipboard, SetExtLinux, LinuxClipboardKind};
let mut ctx = Clipboard::new()?;

let clipboard = "This goes in the traditional (ex. Copy & Paste) clipboard.";
ctx.set().clipboard(LinuxClipboardKind::Clipboard).text(clipboard.to_owned())?;

let primary = "This goes in the primary keyboard. It's typically used via middle mouse click.";
ctx.set().clipboard(LinuxClipboardKind::Primary).text(primary.to_owned())?;
```

--------------------------------

### Linux-specific test block start

Source: https://docs.rs/arboard/latest/src/arboard/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts a platform-specific test block for Linux (excluding macOS, Android, and Emscripten). It imports Linux-specific extensions and defines a constant text string.

```rust
#[cfg(all(
    unix,
    not(any(target_os = "macos", target_os = "android", target_os = "emscripten")),
))]
{
    use crate::{LinuxClipboardKind, SetExtLinux};
    use std::sync::atomic::{self, AtomicBool};

    let mut ctx = Clipboard::new().unwrap();

    const TEXT1: &str = "I'm a little teapot,";
```

--------------------------------

### Clipboard::get

Source: https://docs.rs/arboard/latest/arboard/struct.Clipboard.html?search=

Begins a 'get' operation to retrieve data from the clipboard, returning a builder for further configuration.

```APIDOC
## Clipboard::get

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

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

### Parameters
- `&mut self` - Mutable reference to the clipboard instance.

### Returns
- `Get<'_>` - A builder for the get operation.
```

--------------------------------

### Clipboard::get()

Source: https://docs.rs/arboard/latest/arboard/struct.Clipboard.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Begins a 'get' operation to retrieve data from the clipboard.

```APIDOC
```markdown
Clipboard::get()
```

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

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

### Parameters
- `self` (`&mut self`) - Mutable reference to the `Clipboard` instance.

### Return
- `Get<'_>` - A `Get` operation builder to retrieve data from the clipboard.
```

--------------------------------

### Test Unicode text set/get

Source: https://docs.rs/arboard/latest/src/arboard/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Tests setting and getting Unicode text on the clipboard.

```rust
let mut ctx = Clipboard::new().unwrap();
let text = "Some utf8: 🤓 ∑φ(n)<ε 🐔";
ctx.set_text(text).unwrap();
assert_eq!(ctx.get_text().unwrap(), text);
```

--------------------------------

### Test file list set/get

Source: https://docs.rs/arboard/latest/src/arboard/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Tests setting and getting a file list on the clipboard. The file list contains paths to README.md and Cargo.toml from the crate's manifest directory.

```rust
let mut ctx = Clipboard::new().unwrap();

let this_dir = env!("CARGO_MANIFEST_DIR");

let paths = &[
    PathBuf::from(this_dir).join("README.md"),
    PathBuf::from(this_dir).join("Cargo.toml"),
];

ctx.set().file_list(paths).unwrap();
assert_eq!(ctx.get().file_list().unwrap().as_slice(), paths);
```

--------------------------------

### Get file list from clipboard

Source: https://docs.rs/arboard/latest/src/arboard/platform/linux/x11.rs.html?search=std%3A%3Avec

Reads the URI_LIST format from the clipboard and converts the raw bytes into a vector of file paths.

```rust
pub(crate) fn get_file_list(&self, selection: LinuxClipboardKind) -> Result<Vec<PathBuf>> {
	let result = self.inner.read(&[self.inner.atoms.URI_LIST], selection)?;

	Ok(paths_from_uri_list(result.bytes))
}
```

--------------------------------

### Using clipboard() with LinuxClipboardKind

Source: https://docs.rs/arboard/latest/arboard/trait.SetExtLinux.html

Shows how to use the clipboard method to set data to either the traditional clipboard or the primary selection. Requires the SetExtLinux trait in scope. The example uses the ? operator, so it must be run in a function that returns a Result.

```rust
use arboard::{Clipboard, SetExtLinux, LinuxClipboardKind};
let mut ctx = Clipboard::new()?;

let clipboard = "This goes in the traditional (ex. Copy & Paste) clipboard.";
ctx.set().clipboard(LinuxClipboardKind::Clipboard).text(clipboard.to_owned())?;

let primary = "This goes in the primary keyboard. It's typically used via middle mouse click.";
ctx.set().clipboard(LinuxClipboardKind::Primary).text(primary.to_owned())?;
```

--------------------------------

### Get::html

Source: https://docs.rs/arboard/latest/arboard/struct.Get.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Completes the get operation by fetching HTML from the clipboard.

```APIDOC
## Get::html

### Description
Completes the get operation by fetching HTML from the clipboard.

### Method
pub fn html(self) -> Result<String, Error>

### Parameters
None

### Returns
- **Result<String, Error>** - The clipboard HTML as a string, or an error if retrieval fails.
```

--------------------------------

### Implement Clipboard methods for text and HTML

Source: https://docs.rs/arboard/latest/src/arboard/platform/linux/x11.rs.html

Implements the Clipboard methods: new() initializes the global clipboard and spawns a worker thread; add_clipboard_exclusions adds a KDE exclusion hint when exclude_from_history is true; clear, get_text, set_text, get_html, and set_html delegate to the inner clipboard. get_text handles ISO Latin-1 conversion for STRING format and returns ConversionFailure on invalid UTF-8.

```rust
impl Clipboard {
	pub(crate) fn new() -> Result<Self> {
		let mut global_cb = CLIPBOARD.lock();
		if let Some(global_cb) = &*global_cb {
			return Ok(Self { inner: Arc::clone(&global_cb.inner) });
		}
		// At this point we know that the clipboard does not exist.
		let ctx = Arc::new(Inner::new()?);
		let join_handle;
		{
			let ctx = Arc::clone(&ctx);
			join_handle = std::thread::spawn(move || {
				if let Err(error) = serve_requests(ctx) {
					error!("Worker thread errored with: {}", error);
				}
			});
		}
		*global_cb = Some(GlobalClipboard { inner: Arc::clone(&ctx), server_handle: join_handle });
		Ok(Self { inner: ctx })
	}

	fn add_clipboard_exclusions(&self, exclude_from_history: bool, data: &mut Vec<ClipboardData>) {
		if exclude_from_history {
			data.push(ClipboardData {
				bytes: KDE_EXCLUSION_HINT.to_vec(),
				format: self.inner.atoms.X_KDE_PASSWORDMANAGERHINT,
			})
		}
	}

	pub(crate) fn clear(&self, selection: LinuxClipboardKind) -> Result<()> {
		self.inner.clear(selection)
	}

	pub(crate) fn get_text(&self, selection: LinuxClipboardKind) -> Result<String> {
		let formats = [
			self.inner.atoms.UTF8_STRING,
			self.inner.atoms.UTF8_MIME_0,
			self.inner.atoms.UTF8_MIME_1,
			self.inner.atoms.STRING,
			self.inner.atoms.TEXT,
			self.inner.atoms.TEXT_MIME_UNKNOWN,
		];
		let result = self.inner.read(&formats, selection)?;
		if result.format == self.inner.atoms.STRING {
			// ISO Latin-1
			// See: https://stackoverflow.com/questions/28169745/what-are-the-options-to-convert-iso-8859-1-latin-1-to-a-string-utf-8
			Ok(result.bytes.into_iter().map(|c| c as char).collect())
		} else {
			String::from_utf8(result.bytes).map_err(|_| Error::ConversionFailure)
		}
	}

	pub(crate) fn set_text(
		&self,
		message: Cow<'_, str>,
		selection: LinuxClipboardKind,
		wait: WaitConfig,
		exclude_from_history: bool,
	) -> Result<()> {
		let mut data = Vec::with_capacity(if exclude_from_history { 2 } else { 1 });
		data.push(ClipboardData {
			bytes: message.into_owned().into_bytes(),
			format: self.inner.atoms.UTF8_STRING,
		});

		self.add_clipboard_exclusions(exclude_from_history, &mut data);

		self.inner.write(data, selection, wait)
	}

	pub(crate) fn get_html(&self, selection: LinuxClipboardKind) -> Result<String> {
		let formats = [self.inner.atoms.HTML];
		let result = self.inner.read(&formats, selection)?;
		String::from_utf8(result.bytes).map_err(|_| Error::ConversionFailure)
	}

	pub(crate) fn set_html(
		&self,
		html: Cow<'_, str>,
		alt: Option<Cow<'_, str>>,
		selection: LinuxClipboardKind,
		wait: WaitConfig,
		exclude_from_history: bool,
	) -> Result<()> {
		let mut data = {
```

--------------------------------

### Get::text

Source: https://docs.rs/arboard/latest/arboard/struct.Get.html?search=

Completes the get operation by fetching UTF-8 text from the clipboard.

```APIDOC
## Get::text

### Description
Completes the "get" operation by fetching UTF-8 text from the clipboard.

### Method
pub fn text(self) -> Result<String, Error>

### Parameters
None.

### Returns
- `Result<String, Error>` - The clipboard text as a UTF-8 string, or an error if the operation fails.

```

--------------------------------

### Get::text

Source: https://docs.rs/arboard/latest/arboard/struct.Get.html?search=u32+-%3E+bool

Completes the get operation by fetching UTF-8 text from the clipboard.

```APIDOC
## Get::text

### Description
Completes the “get” operation by fetching UTF-8 text from the clipboard.

### Method
`pub fn text(self) -> Result<String, Error>`

### Parameters
- `self` - The Get builder instance.

### Returns
- `Result<String, Error>` - The clipboard text as a UTF-8 string, or an error if retrieval fails.
```

--------------------------------

### X11 clipboard implementation (x11.rs) - imports, atoms, and XContext::new()

Source: https://docs.rs/arboard/latest/src/arboard/platform/linux/x11.rs.html?search=u32+-%3E+bool

The beginning of the X11 clipboard implementation for the arboard crate. It includes the license header, imports, type aliases, atom definitions via x11rb::atom_manager!, thread-local cache, timeout constants, and the initial part of the XContext::new() method that establishes an X11 connection and creates a window.

```rust
1/*
2SPDX-License-Identifier: Apache-2.0 OR MIT
3
4Copyright 2022 The Arboard contributors
5
6The project to which this file belongs is licensed under either of
7the Apache 2.0 or the MIT license at the licensee's choice. The terms
8and conditions of the chosen license apply to this file.
9*/
10
11// More info about using the clipboard on X11:
12// https://tronche.com/gui/x/icccm/sec-2.html#s-2.6
13// https://freedesktop.org/wiki/ClipboardManager/
14
15use std::{
16	borrow::Cow,
17	cell::RefCell,
18	collections::{hash_map::Entry, HashMap},
19	path::{Path, PathBuf},
20	sync::{
21		atomic::{AtomicBool, Ordering},
22		Arc,
23	},
24	thread::JoinHandle,
25	thread_local,
26	time::{Duration, Instant},
27};
28
29use log::{error, trace, warn};
30use parking_lot::{Condvar, Mutex, MutexGuard, RwLock};
31use x11rb::{
32	connection::Connection,
33	protocol::{
34		xproto::{
35			Atom, AtomEnum, ConnectionExt as _, CreateWindowAux, EventMask, PropMode, Property,
			PropertyNotifyEvent, SelectionNotifyEvent, SelectionRequestEvent, Time, WindowClass,
			SELECTION_NOTIFY_EVENT,
		},
		Event,
	},
	rust_connection::RustConnection,
	wrapper::ConnectionExt as _,
	COPY_DEPTH_FROM_PARENT, COPY_FROM_PARENT, NONE,
};

#[cfg(feature = "image-data")]
use super::encode_as_png;
use super::{
	into_unknown, paths_from_uri_list, paths_to_uri_list, LinuxClipboardKind, WaitConfig,
	KDE_EXCLUSION_HINT, KDE_EXCLUSION_MIME,
};
#[cfg(feature = "image-data")]
use crate::ImageData;
use crate::{common::ScopeGuard, Error};

type Result<T, E = Error> = std::result::Result<T, E>;

static CLIPBOARD: Mutex<Option<GlobalClipboard>> = parking_lot::const_mutex(None);

x11rb::atom_manager! {
	pub Atoms: AtomCookies {
		CLIPBOARD,
		PRIMARY,
		SECONDARY,

		CLIPBOARD_MANAGER,
		SAVE_TARGETS,
		TARGETS,
		ATOM,
		INCR,

		UTF8_STRING,
		UTF8_MIME_0: b"text/plain;charset=utf-8",
		UTF8_MIME_1: b"text/plain;charset=UTF-8",
		// Text in ISO Latin-1 encoding
		// See: https://tronche.com/gui/x/icccm/sec-2.html#s-2.6.2
		STRING,
		// Text in unknown encoding
		// See: https://tronche.com/gui/x/icccm/sec-2.html#s-2.6.2
		TEXT,
		TEXT_MIME_UNKNOWN: b"text/plain",

		HTML: b"text/html",
		URI_LIST: b"text/uri-list",

		PNG_MIME: b"image/png",
		X_KDE_PASSWORDMANAGERHINT: KDE_EXCLUSION_MIME.as_bytes(),

		// This is just some random name for the property on our window, into which
		// the clipboard owner writes the data we requested.
		ARBOARD_CLIPBOARD,
	}
}

thread_local! {
	static ATOM_NAME_CACHE: RefCell<HashMap<Atom, &'static str>> = Default::default();
}

// Some clipboard items, like images, may take a very long time to produce a
// `SelectionNotify`. Multiple seconds long.
const LONG_TIMEOUT_DUR: Duration = Duration::from_millis(4000);
const SHORT_TIMEOUT_DUR: Duration = Duration::from_millis(10);

#[derive(Debug, PartialEq, Eq)]
enum ManagerHandoverState {
	Idle,
	InProgress,
	Finished,
}

struct GlobalClipboard {
	inner: Arc<Inner>,

	/// Join handle to the thread which serves selection requests.
	server_handle: JoinHandle<()>,
}

struct XContext {
	conn: RustConnection,
	win_id: u32,
}

struct Inner {
	/// The context for the thread which serves clipboard read
	/// requests coming to us.
	server: XContext,
	atoms: Atoms,

	clipboard: Selection,
	primary: Selection,
	secondary: Selection,

	handover_state: Mutex<ManagerHandoverState>,
	handover_cv: Condvar,

	serve_stopped: AtomicBool,
}

impl XContext {
	fn new() -> Result<Self> {
		// create a new connection to an X11 server
		let (conn, screen_num): (RustConnection, _) =
			RustConnection::connect(None).map_err(|_| {
				Error::unknown("X11 server connection timed out because it was unreachable")
			})?;
		let screen = conn.setup().roots.get(screen_num).ok_or(Error::unknown("no screen found"))?;
		let win_id = conn.generate_id().map_err(into_unknown)?;

		let event_mask =
            // Just in case that some program reports SelectionNotify events
            // with XCB_EVENT_MASK_PROPERTY_CHANGE mask.
            EventMask::PROPERTY_CHANGE |
            // To receive DestroyNotify event and stop the message loop.
            EventMask::STRUCTURE_NOTIFY;
		// create the window
		conn.create_window(
			// copy as much as possible from the parent, because no other specific input is needed
			COPY_DEPTH_FROM_PARENT,
			win_id,
			screen.root,
			0,
			0,
			1,
			1,
			0,
			WindowClass::COPY_FROM_PARENT,
			COPY_FROM_PARENT,
			// don't subscribe to any special events because we are requesting everything we need ourselves
        
```

--------------------------------

### Get::text

Source: https://docs.rs/arboard/latest/arboard/struct.Get.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Completes the get operation by fetching UTF-8 text from the clipboard.

```APIDOC
## Get::text

### Description
Completes the get operation by fetching UTF-8 text from the clipboard.

### Method
pub fn text(self) -> Result<String, Error>

### Parameters
None

### Returns
- **Result<String, Error>** - The clipboard text as a UTF-8 string, or an error if retrieval fails.
```

--------------------------------

### Arboard X11 clipboard implementation (x11.rs)

Source: https://docs.rs/arboard/latest/src/arboard/platform/linux/x11.rs.html?search=

The complete source file for the X11 clipboard backend of arboard-3.6.1. It creates an X11 connection, defines atom aliases via x11rb's atom_manager!, and implements the clipboard serving logic for text, HTML, URIs, images, and KDE hint exclusion. Uses parking_lot for synchronization and x11rb for X11 protocol. Timeouts are set for short and long operations, and a thread_local cache maps atoms to names.

```rust
1/*
2SPDX-License-Identifier: Apache-2.0 OR MIT
3
4Copyright 2022 The Arboard contributors
5
6The project to which this file belongs is licensed under either of
7the Apache 2.0 or the MIT license at the licensee's choice. The terms
8and conditions of the chosen license apply to this file.
9*/
10
11// More info about using the clipboard on X11:
12// https://tronche.com/gui/x/icccm/sec-2.html#s-2.6
13// https://freedesktop.org/wiki/ClipboardManager/
14
15use std::{
16	borrow::Cow,
17	cell::RefCell,
18	collections::{hash_map::Entry, HashMap},
19	path::{Path, PathBuf},
20	sync::{
21		atomic::{AtomicBool, Ordering},
22		Arc,
23	},
24	thread::JoinHandle,
25	thread_local,
26	time::{Duration, Instant},
27};
28
29use log::{error, trace, warn};
30use parking_lot::{Condvar, Mutex, MutexGuard, RwLock};
31use x11rb::{
32	connection::Connection,
33	protocol::{
34		xproto::{
35			Atom, AtomEnum, ConnectionExt as _, CreateWindowAux, EventMask, PropMode, Property,
			PropertyNotifyEvent, SelectionNotifyEvent, SelectionRequestEvent, Time, WindowClass,
			SELECTION_NOTIFY_EVENT,
		},
		Event,
	},
	rust_connection::RustConnection,
	wrapper::ConnectionExt as _,
	COPY_DEPTH_FROM_PARENT, COPY_FROM_PARENT, NONE,
};

#[cfg(feature = "image-data")]
use super::encode_as_png;
use super::{
	into_unknown, paths_from_uri_list, paths_to_uri_list, LinuxClipboardKind, WaitConfig,
	KDE_EXCLUSION_HINT, KDE_EXCLUSION_MIME,
};
#[cfg(feature = "image-data")]
use crate::ImageData;
use crate::{common::ScopeGuard, Error};

pub type Result<T, E = Error> = std::result::Result<T, E>;

static CLIPBOARD: Mutex<Option<GlobalClipboard>> = parking_lot::const_mutex(None);

x11rb::atom_manager! {
	pub Atoms: AtomCookies {
		CLIPBOARD,
		PRIMARY,
		SECONDARY,

		CLIPBOARD_MANAGER,
		SAVE_TARGETS,
		TARGETS,
		ATOM,
		INCR,

		UTF8_STRING,
		UTF8_MIME_0: b"text/plain;charset=utf-8",
		UTF8_MIME_1: b"text/plain;charset=utf-8",
		UTF8_MIME_1: b"text/plain;charset=UTF-8",
		// Text in ISO Latin-1 encoding
		// See: https://tronche.com/gui/x/icccm/sec-2.html#s-2.6.2
		STRING,
		// Text in unknown encoding
		// See: https://tronche.com/gui/x/icccm/sec-2.html#s-2.6.2
		TEXT,
		TEXT_MIME_UNKNOWN: b"text/plain",

		HTML: b"text/html",
		URI_LIST: b"text/uri-list",

		PNG_MIME: b"image/png",
		X_KDE_PASSWORDMANAGERHINT: KDE_EXCLUSION_MIME.as_bytes(),

		// This is just some random name for the property on our window, into which
		// the clipboard owner writes the data we requested.
		ARBOARD_CLIPBOARD,
	}
}

thread_local! {
	static ATOM_NAME_CACHE: RefCell<HashMap<Atom, &'static str>> = Default::default();
}

// Some clipboard items, like images, may take a very long time to produce a
// `SelectionNotify`. Multiple seconds long.
const LONG_TIMEOUT_DUR: Duration = Duration::from_millis(4000);
const SHORT_TIMEOUT_DUR: Duration = Duration::from_millis(10);

#[derive(Debug, PartialEq, Eq)]
enum ManagerHandoverState {
	Idle,
	InProgress,
	Finished,
}

struct GlobalClipboard {
	inner: Arc<Inner>,

	/// Join handle to the thread which serves selection requests.
	server_handle: JoinHandle<()>,
}

struct XContext {
	conn: RustConnection,
	win_id: u32,
}

struct Inner {
	/// The context for the thread which serves clipboard read
	/// requests coming to us.
	server: XContext,
	atoms: Atoms,

	clipboard: Selection,
	primary: Selection,
	secondary: Selection,

	handover_state: Mutex<ManagerHandoverState>,
	handover_cv: Condvar,

	serve_stopped: AtomicBool,
}

impl XContext {
	fn new() -> Result<Self> {
		// create a new connection to an X11 server
		let (conn, screen_num): (RustConnection, _) =
			RustConnection::connect(None).map_err(|_| {
				Error::unknown("X11 server connection was unreachable")
		})?;
		let screen = conn.setup().roots.get(screen_num).ok_or(Error::unknown("no screen found"))?;
		let win_id = conn.generate_id().map_err(into_unknown)?;

		let event_mask =
			// Just in case that some program reports SelectionNotify events
			// with XCB_EVENT_MASK_PROPERTY_CHANGE mask.
			EventMask::PROPERTY_CHANGE |
			// To receive DestroyNotify event and stop the message loop.
			EventMask::STRUCTURE_NOTIFY;
		// create the window
		conn.create_window(
			// copy as much as possible from the parent, because no other specific input is needed
			COPY_DEPTH_FROM_PARENT,
			win_id,
			screen.root,
			0,
			0,
			1,
			1,
			0,
			WindowClass::COPY_FROM_PARENT,
			COPY_FROM_PARENT,
			// don't subscribe to any special events because we are requesting everything we need ourselves
			&event_mask,
		)...
```

--------------------------------

### Get::file_list

Source: https://docs.rs/arboard/latest/arboard/struct.Get.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Completes the get operation by fetching a list of file paths from the clipboard.

```APIDOC
## Get::file_list

### Description
Completes the get operation by fetching a list of file paths from the clipboard.

### Method
pub fn file_list(self) -> Result<Vec<PathBuf>, Error>

### Parameters
None

### Returns
- **Result<Vec<PathBuf>, Error>** - A vector of file paths, or an error if retrieval fails.
```

--------------------------------

### Clipboard::new()

Source: https://docs.rs/arboard/latest/arboard/struct.Clipboard.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates an instance of the clipboard. Returns an error on platforms or desktop environments where clipboards are not supported.

```APIDOC
## Function: Clipboard::new()

### Description
Creates an instance of the clipboard. On some platforms or desktop environments, an error can be returned if clipboards are not supported.

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

### Parameters
None.

### Return
- `Result<Self, Error>` - Returns a `Clipboard` instance on success, or an `Error` if the clipboard is not supported.

### Errors
- Returns an error on platforms where clipboards are not supported. This may be retried.

### Example
```rust
let mut cb = Clipboard::new()?;
```
```

--------------------------------

### Inner::new() - Initialize X11 clipboard context

Source: https://docs.rs/arboard/latest/src/arboard/platform/linux/x11.rs.html?search=

Creates a new Inner instance by establishing an X11 connection and retrieving the required atoms. Initializes the clipboard, primary, and secondary selections, along with handover state and synchronization primitives.

```rust
impl Inner {
	fn new() -> Result<Self> {
		let server = XContext::new()?;
		let atoms =
			Atoms::new(&server.conn).map_err(into_unknown)?.reply().map_err(into_unknown)?;

		Ok(Self {
			server,
			atoms,
			clipboard: Selection::default(),
			primary: Selection::default(),
			secondary: Selection::default(),
			handover_state: Mutex::new(ManagerHandoverState::Idle),
			handover_cv: Condvar::new(),
			serve_stopped: AtomicBool::new(false),
		})
	}
}
```

--------------------------------

### Get

Source: https://docs.rs/arboard/latest/arboard

A builder for an operation that gets a value from the clipboard. Use this to retrieve text, image, or other clipboard data.

```APIDOC
## Get

### Description
A builder for an operation that gets a value from the clipboard. It is used to configure and execute a read operation.

### Operations
- Retrieve text, image, or arbitrary data from the clipboard.

### Platform Extensions
- `GetExtLinux` - Linux-specific extensions for additional clipboard selection options.
```

--------------------------------

### Setting clipboard text in a thread

Source: https://docs.rs/arboard/latest/src/arboard/lib.rs.html?search=u32+-%3E+bool

Shows creating a Clipboard instance and setting text asynchronously in a spawned thread, then storing a flag with atomic ordering.

```rust
let mut ctx = Clipboard::new().unwrap();
ctx.set_text("replacement text".to_owned()).unwrap();
was_replaced.store(true, atomic::Ordering::Release);
```

--------------------------------

### Get::image

Source: https://docs.rs/arboard/latest/arboard/struct.Get.html?search=

Completes the get operation by fetching image data from the clipboard and returning the decoded pixels.

```APIDOC
## Get::image

### Description
Completes the "get" operation by fetching image data from the clipboard and returning 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.

### Method
pub fn image(self) -> Result<ImageData<'static>, Error>

### Parameters
None.

### Returns
- `Result<ImageData<'static>, Error>` - The decoded image data, or an error if the operation fails.

```

--------------------------------

### Setting text to Linux clipboard kinds

Source: https://docs.rs/arboard/latest/src/arboard/lib.rs.html?search=u32+-%3E+bool

Demonstrates setting text to different Linux clipboard kinds (Clipboard, Primary, and conditionally Secondary) using the arboard API.

```rust
const TEXT2: &str = "short and stout,";
const TEXT3: &str = "here is my handle";

ctx.set().clipboard(LinuxClipboardKind::Clipboard).text(TEXT1.to_string()).unwrap();

ctx.set().clipboard(LinuxClipboardKind::Primary).text(TEXT2.to_string()).unwrap();

// The secondary clipboard is not available under wayland
if !cfg!(feature = "wayland-data-control")
	|| std::env::var_os("WAYLAND_DISPLAY").is_none()
{
	ctx.set().clipboard(LinuxClipboardKind::Secondary).text(TEXT3.to_string()).unwrap();
}
```

--------------------------------

### Get::image

Source: https://docs.rs/arboard/latest/arboard/struct.Get.html?search=u32+-%3E+bool

Completes the get operation by fetching image data from the clipboard and returning the decoded pixels.

```APIDOC
## Get::image

### Description
Completes the “get” operation by fetching image data from the clipboard and returning 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.

### Method
`pub fn image(self) -> Result<ImageData<'static>, Error>`

### Parameters
- `self` - The Get builder instance.

### Returns
- `Result<ImageData<'static>, Error>` - The decoded image data, or an error if retrieval fails.
```

--------------------------------

### fn clipboard(self, selection: LinuxClipboardKind) -> Result<(), Error>

Source: https://docs.rs/arboard/latest/arboard/trait.ClearExtLinux.html

Performs the 'clear' operation on the selected clipboard. If wayland support is enabled and available, attempting to use the Secondary clipboard will return an error.

```APIDOC
## fn clipboard(self, selection: LinuxClipboardKind) -> Result<(), Error>

### Description
Performs the "clear" operation on the selected clipboard. If wayland support is enabled and available, attempting to use the Secondary clipboard will return an error.

### Method
clipboard

### Parameters
- **selection** (LinuxClipboardKind) - Required - The clipboard kind to clear.

### Return Value
- **Result<(), Error>** - Ok if the clear operation succeeded, otherwise an Error.

### Example
```rust
let mut clipboard = Clipboard::new()?;

clipboard
    .clear_with()
    .clipboard(LinuxClipboardKind::Secondary)?;
```

### Notes
- This trait is dyn compatible.
- Implemented for `Clear<'_>`.
```

--------------------------------

### Get::image

Source: https://docs.rs/arboard/latest/arboard/struct.Get.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Completes the get operation by fetching image data from the clipboard and returning the decoded pixels.

```APIDOC
## Get::image

### Description
Completes the get operation by fetching image data from the clipboard and returning 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.

### Method
pub fn image(self) -> Result<ImageData<'static>, Error>

### Parameters
None

### Returns
- **Result<ImageData<'static>, Error>** - The decoded image data, or an error if retrieval fails.
```

--------------------------------

### fn clipboard(self, selection: LinuxClipboardKind) -> Self

Source: https://docs.rs/arboard/latest/arboard/trait.GetExtLinux.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Sets the clipboard the operation will retrieve data from. On wayland, attempting to use the Secondary clipboard will return an error.

```APIDOC
## clipborad(self, selection: LinuxClipboardKind) -> Self

### Description
Sets the clipboard the operation will retrieve data from. If wayland support is enabled and available, attempting to use the Secondary clipboard will return an error.

### Required Method
`fn clipboard(self, selection: LinuxClipboardKind) -> Self`

### Parameters
- **selection** (LinuxClipboardKind) - Required - The kind of Linux clipboard to retrieve data from, such as Primary, Secondary, or CLiboard.

### Return Value
Returns `Self` (the `Get` builder) with the specified clipboard selection applied.

### Trait Requirements
This trait is **not** dyn compatible.

### Implementors
- `impl GetExtLinux for Get<'->_`
```

--------------------------------

### Get struct definition

Source: https://docs.rs/arboard/latest/src/arboard/platform/linux/mod.rs.html?search=u32+-%3E+bool

Defines the Get struct that holds a mutable reference to a Clipboard and a selection kind, with a constructor that defaults to LinuxClipboardKind::Clipboard.

```rust
pub(crate) struct Get<'clipboard> {
	clipboard: &'clipboard mut Clipboard,
	selection: LinuxClipboardKind,
}

impl<'clipboard> Get<'clipboard> {
	pub(crate) fn new(clipboard: &'clipboard mut Clipboard) -> Self {
		Self { clipboard, selection: LinuxClipboardKind::Clipboard }
	}
```

--------------------------------

### Get::image

Source: https://docs.rs/arboard/latest/src/arboard/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Completes the 'get' operation by fetching image data from the clipboard and returning the decoded pixels. This method is only available with the 'image-data' feature enabled.

```APIDOC
## Get::image

### Description
Completes the "get" operation by fetching image data from the clipboard and returning 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.

### Method
`pub fn image(self) -> Result<ImageData<'static>, Error>`

### Parameters
None

### Return Value
- `Result<ImageData<'static>, Error>` - The image data from the clipboard, or an error if retrieval fails.

### Example
```rust
let mut clipboard = Clipboard::new()?;
let image = clipboard.get().image()?;
```
```

--------------------------------

### Set text on traditional and primary Linux clipboards

Source: https://docs.rs/arboard/latest/src/arboard/platform/linux/mod.rs.html?search=u32+-%3E+bool

Shows how to use the SetExtLinux::clipboard method to set text on both the traditional clipboard and the primary selection. Requires the SetExtLinux and LinuxClipboardKind traits.

```rust
use arboard::{Clipboard, SetExtLinux, LinuxClipboardKind};
# fn main() -> Result<(), arboard::Error> {
let mut ctx = Clipboard::new()?;

let clipboard = "This goes in the traditional (ex. Copy & Paste) clipboard.";
ctx.set().clipboard(LinuxClipboardKind::Clipboard).text(clipboard.to_owned())?;

let primary = "This goes in the primary keyboard. It's typically used via middle mouse click.";
ctx.set().clipboard(LinuxClipboardKind::Primary).text(primary.to_owned())?;
# Ok(())
# }
```

--------------------------------

### ImageData struct documentation and example

Source: https://docs.rs/arboard/latest/src/arboard/common.rs.html?search=u32+-%3E+bool

Defines the ImageData struct for storing pixel data in row-major order with four channels per pixel. The example shows constructing an ImageData for a 2x1 image with red and green pixels.

```rust
/// Stores pixel data of an image.
///
/// Each element in `bytes` stores the value of a channel of a single pixel.
/// This struct stores four channels (red, green, blue, alpha) so
/// a `3*3` image is going to be stored on `3*3*4 = 36` bytes of data.
///
/// The pixels are in row-major order meaning that the second pixel
/// in `bytes` (starting at the fifth byte) corresponds to the pixel that's
/// sitting to the right side of the top-left pixel (x=1, y=0)
///
/// Assigning a `2*1` image would for example look like this
/// 
/// use arboard::ImageData;
/// use std::borrow::Cow;
/// let bytes = [
///     // A red pixel
///     255, 0, 0, 255,
///
///     // A green pixel
///     0, 255, 0, 255,
/// ];
/// let img = ImageData {
///     width: 2,
///     height: 1,
///     bytes: Cow::from(bytes.as_ref())
/// };
/// 
#[cfg(feature = "image-data")]
#[derive(Debug, Clone)]
```

--------------------------------

### Get::clipboard

Source: https://docs.rs/arboard/latest/arboard/struct.Get.html?search=

Sets the clipboard the operation will retrieve data from.

```APIDOC
## Get::clipboard

### Description
Sets the clipboard the operation will retrieve data from.

### Method
pub fn clipboard(self, selection: LinuxClipboardKind) -> Self

### Parameters
- **selection** (LinuxClipboardKind) - Required - The clipboard selection to use.

### Returns
- `Self` - The builder with the clipboard selection set.

```

--------------------------------

### WaitConfig and Set Builder

Source: https://docs.rs/arboard/latest/src/arboard/platform/linux/mod.rs.html

Configuration for X11 copy event waiting and the internal Set builder implementation for Linux.

```rust
#[derive(Default)]
pub(crate) enum WaitConfig {
	/// Waits until the given [`Instant`] has reached.
	Until(Instant),

	/// Waits forever until a new event is reached.
	Forever,

	/// It shouldn't wait.
	#[default]
	None,
}

pub(crate) struct Set<'clipboard> {
	clipboard: &'clipboard mut Clipboard,
	wait: WaitConfig,
	selection: LinuxClipboardKind,
	exclude_from_history: bool,
}

impl<'clipboard> Set<'clipboard> {
	pub(crate) fn new(clipboard: &'clipboard mut Clipboard) -> Self {
		Self {
			clipboard,
			wait: WaitConfig::default(),
			selection: LinuxClipboardKind::Clipboard,
			exclude_from_history: false,
		}
	}

	pub(crate) fn text(self, text: Cow<'_, str>) -> Result<(), Error> {
		match self.clipboard {
			Clipboard::X11(clipboard) => {
				clipboard.set_text(text, self.selection, self.wait, self.exclude_from_history)
			}

			#[cfg(feature = "wayland-data-control")]
			Clipboard::WlDataControl(clipboard) => {
				clipboard.set_text(text, self.selection, self.wait, self.exclude_from_history)
			}
		}
	}

	pub(crate) fn html(self, html: Cow<'_, str>, alt: Option<Cow<'_, str>>) -> Result<(), Error> {
		match self.clipboard {
			Clipboard::X11(clipboard) => {
				clipboard.set_html(html, alt, self.selection, self.wait, self.exclude_from_history)
			}

			#[cfg(feature = "wayland-data-control")]
			Clipboard::WlDataControl(clipboard) => {
				clipboard.set_html(html, alt, self.selection, self.wait, self.exclude_from_history)
			}
		}
	}

	#[cfg(feature = "image-data")]
	pub(crate) fn image(self, image: ImageData<'_>) -> Result<(), Error> {
		match self.clipboard {
			Clipboard::X11(clipboard) => {
				clipboard.set_image(image, self.selection, self.wait, self.exclude_from_history)
			}

			#[cfg(feature = "wayland-data-control")]
			Clipboard::WlDataControl(clipboard) => {
				clipboard.set_image(image, self.selection, self.wait, self.exclude_from_history)
			}
		}
	}

	pub(crate) fn file_list(self, file_list: &[impl AsRef<Path>]) -> Result<(), Error> {
		match self.clipboard {
			Clipboard::X11(clipboard) => clipboard.set_file_list(
				file_list,
				self.selection,
				self.wait,
				self.exclude_from_history,
			),

			#[cfg(feature = "wayland-data-control")]
			Clipboard::WlDataControl(clipboard) => clipboard.set_file_list(
				file_list,
				self.selection,
				self.wait,
				self.exclude_from_history,
			),
		}
	}
}
```

--------------------------------

### Define Error enum and ImageData construction example

Source: https://docs.rs/arboard/latest/src/arboard/common.rs.html?search=std%3A%3Avec

The first block defines the `Error` enum and its `Display`, `Error`, and `Debug` implementations, plus the `unknown` constructor. The second block is a doc example showing how to construct an `ImageData` for a 2x1 image with red and green pixels, using `Cow::from` for the bytes.

```rust
1/*
2SPDX-License-Identifier: Apache-2.0 OR MIT
3
4Copyright 2022 The Arboard contributors
5
6The project to which this file belongs is licensed under either of
7the Apache 2.0 or the MIT license at the licensee's choice. The terms
8and conditions of the chosen license apply to this file.
9*/
10
11#[cfg(feature = "image-data")]
12use std::borrow::Cow;
13
/// An error that might happen during a clipboard operation.
///
/// Note that both the `Display` and the `Debug` trait is implemented for this type in such a way
/// that they give a short human-readable description of the error; however the documentation
/// gives a more detailed explanation for each error kind.
#[non_exhaustive]
pub enum Error {
	/// The clipboard contents were not available in the requested format.
	/// This could either be due to the clipboard being empty or the clipboard contents having
	/// an incompatible format to the requested one (eg when calling `get_image` on text)
	ContentNotAvailable,

	/// The selected clipboard is not supported by the current configuration (system and/or environment).
	///
	/// This can be caused by a few conditions:
	/// - Using the Primary clipboard with an older Wayland compositor (that doesn't support version 2)
	/// - Using the Secondary clipboard on Wayland
	ClipboardNotSupported,

	/// The native clipboard is not accessible due to being held by another party.
	///
	/// This "other party" could be a different process or it could be within
	/// the same program. So for example you may get this error when trying
	/// to interact with the clipboard from multiple threads at once.
	///
	/// Note that it's OK to have multiple `Clipboard` instances. The underlying
	/// implementation will make sure that the native clipboard is only
	/// opened for transferring data and then closed as soon as possible.
	ClipboardOccupied,

	/// The image or the text that was about the be transferred to/from the clipboard could not be
	/// converted to the appropriate format.
	ConversionFailure,

	/// Any error that doesn't fit the other error types.
	///
	/// The `description` field is only meant to help the developer and should not be relied on as a
	/// means to identify an error case during runtime.
	Unknown { description: String },
}

impl std::fmt::Display for Error {
	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
		match self {
			Error::ContentNotAvailable => f.write_str("The clipboard contents were not available in the requested format or the clipboard is empty."),
			Error::ClipboardNotSupported => f.write_str("The selected clipboard is not supported with the current system configuration."),
			Error::ClipboardOccupied => f.write_str("The native clipboard is not accessible due to being held by another party."),
			Error::ConversionFailure => f.write_str("The image or the text that was about the be transferred to/from the clipboard could not be converted to the appropriate format."),
			Error::Unknown { description } => f.write_fmt(format_args!("Unknown error while interacting with the clipboard: {description}")),
		}
	}
}

impl std::error::Error for Error {}

impl std::fmt::Debug for Error {
	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
		use Error::*;
		macro_rules! kind_to_str {
			($( $e: pat ),*) => {
				match self {
					$(
						$e => stringify!($e),
					)*
				}
			}
		}
		let name = kind_to_str!(
			ContentNotAvailable,
			ClipboardNotSupported,
			ClipboardOccupied,
			ConversionFailure,
			Unknown { .. }
		);
		f.write_fmt(format_args!("{name} - \"{self}\""))
	}
}

impl Error {
	pub(crate) fn unknown<M: Into<String>>(message: M) -> Self {
		Error::Unknown { description: message.into() }
	}
}

/// Stores pixel data of an image.
///
/// Each element in `bytes` stores the value of a channel of a single pixel.
/// This struct stores four channels (red, green, blue, alpha) so
/// a `3*3` image is going to be stored on `3*3*4 = 36` bytes of data.
///
/// The pixels are in row-major order meaning that the second pixel
/// in `bytes` (starting at the fifth byte) corresponds to the pixel that's
/// sitting to the right side of the top-left pixel (x=1, y=0)
///
/// Assigning a `2*1` image would for example look like this

```

```rust
use arboard::ImageData;
use std::borrow::Cow;
let bytes = [
    // A red pixel
    255, 0, 0, 255,

    // A green pixel
    0, 255, 0, 255,
];
let img = ImageData {
    width: 2,
    height: 1,
    bytes: Cow::from(bytes.as_ref())
};
```

--------------------------------

### Get HTML from clipboard

Source: https://docs.rs/arboard/latest/src/arboard/platform/linux/x11.rs.html?search=u32+-%3E+bool

Reads HTML content from the clipboard using the HTML format.

```rust
pub(crate) fn get_html(&self, selection: LinuxClipboardKind) -> Result<String> {
		let formats = [self.inner.atoms.HTML];
		let result = self.inner.read(&formats, selection)?;
		String::from_utf8(result.bytes).map_err(|_| Error::ConversionFailure)
	}
```

--------------------------------

### Create X11 window with event mask

Source: https://docs.rs/arboard/latest/src/arboard/platform/linux/x11.rs.html

Creates an X11 window with a custom event mask, flushes the connection, and returns the connection and window ID. Used in the X11 backend setup.

```rust
// don't subscribe to any special events because we are requesting everything we need ourselves
&CreateWindowAux::new().event_mask(event_mask),
)
.map_err(into_unknown)?;
conn.flush().map_err(into_unknown)?;

Ok(Self { conn, win_id })
}
```
Tokens:
Raw