clipboard_stream/lib.rs
1//! Async stream of clipboard change events.
2//!
3//! Provides real-time clipboard monitoring through an async [`Stream`] interface.
4//!
5//! The main part of this crate is [`ClipboardStream`].
6//! This struct implements [`Stream`].
7//!
8//! # Example
9//! The following example shows how to receive clipboard items:
10//!
11//! ```no_run
12//! use clipboard_stream::{ClipboardEventListener, Kind};
13//! use futures::stream::StreamExt;
14//!
15//! #[tokio::main]
16//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
17//! // Spawn a clipboard event listener
18//! let mut event_listener = ClipboardEventListener::spawn();
19//!
20//! // Create a new stream for UTF-8 strings
21//! // This may return `Error::AlreadyExists` if the same kind of stream already exists
22//! let mut stream = event_listener.new_stream(Kind::Utf8String, 32)?;
23//!
24//! while let Some(body) = stream.next().await {
25//! if let Ok(v) = body {
26//! println!("{:?}", v);
27//! }
28//! }
29//! Ok(())
30//! }
31//! ```
32//!
33//! # Runtime
34//! Internally, this crate spawns a small dedicated OS thread to listen for clipboard events.
35//! The API itself is `Future`-based and does not depend on any specific async runtime,
36//! so it works with [`tokio`](https://docs.rs/tokio), [`smol`](https://docs.rs/smol), or any runtime compatible with
37//! [`futures`](https://docs.rs/futures).
38//!
39//! # Platforms
40//! - macOS
41//!
42//! Currently supported on **macOS only**. Windows support is planned for a future release.
43//!
44//! [`Stream`]: https://docs.rs/futures/latest/futures/stream/trait.Stream.html
45//! [`ClipboardStream`]: crate::stream::ClipboardStream
46mod body;
47mod driver;
48mod error;
49mod event_listener;
50mod stream;
51mod sys;
52
53pub use crate::body::{Body, Kind};
54pub use crate::error::Error;
55pub use crate::event_listener::ClipboardEventListener;
56pub use crate::stream::ClipboardStream;
57
58pub(crate) type Msg = Result<Body, crate::error::Error>;