[![crates.io](https://img.shields.io/crates/v/clippers.svg)](https://crates.io/crates/clippers)
[![docs.rs](https://docs.rs/clippers/badge.svg)](https://docs.rs/clippers/)
[![license](https://img.shields.io/crates/l/clippers)](https://github.com/WilliamVenner/clippers/blob/master/LICENSE)
[![Workflow Status](https://github.com/WilliamVenner/clippers/workflows/ci/badge.svg)](https://github.com/WilliamVenner/clippers/actions?query=workflow%3A%22ci%22)

Cross-platform clipboard management library powered by [`clip`](https://github.com/dacap/clip).

# Features

* Read and write UTF-8 text to/from the clipboard
* Read and write RGBA images to/from the clipboard
* Clipboard clearing

# Platform support

| **Platform**    | Clear | Text (R) | Text (W) | Images (R) | Images (W) |
|-----------------|:-----:|:--------:|:--------:|:----------:|:----------:|
| **Windows**     |   ✅   |     ✅    |     ✅    |      ✅     |      ✅     |
| **macOS**       |   ✅   |     ✅    |     ✅    |      ✅     |      ✅     |
| **Linux (X11)** |   ✅   |     ✅    |     ✅    |      ✅     |      ✅     |

### Linux

Requires the `libx11-dev`/`libX11-devel` and `libpng-dev`/`libpng-devel` packages to be installed.

# Thread Safety

Not all OS clipboard APIs are thread-safe, so whilst the functions in this crate do their best to be thread-safe
by synchronising using an internal mutex, using other clipboard libraries or calling OS clipboard APIs directly
may cause undefined behaviour.

# Examples

### Reading data

```rust
let mut clipboard = clippers::Clipboard::get();
match clipboard.read() {
    Some(clippers::ClipperData::Text(text)) => {
        println!("Clipboard text: {:?}", text);
    }

    Some(clippers::ClipperData::Image(image)) => {
        println!("Clipboard image: {}x{} RGBA", image.width(), image.height());
    }

    Some(data) => {
        println!("Clipboard data is unknown: {data:?}");
    }

    None => {
        println!("Clipboard is empty");
    }
}
```

### Writing text

```rust
let mut clipboard = clippers::Clipboard::get();
clipboard.write_text("Hello, world!").unwrap();
assert_eq!(clipboard.read().unwrap().into_text().unwrap(), "Hello, world!");
```

### Writing an image

```rust
let mut clipboard = clippers::Clipboard::get();
let image = image::ImageBuffer::from_fn(8, 8, |x, y| {
    if (x * y) % 2 == 0 {
        image::Rgba([255, 0, 0, 255])
    } else {
        image::Rgba([0, 255, 0, 255])
    }
});
clipboard.write_image(image.width(), image.height(), image.as_raw()).unwrap();

let clipboard_image = clipboard.read().unwrap();
assert_eq!(clipboard_image.into_image().unwrap().as_raw(), image.as_ref());
```