Struct druid_shell::Clipboard

pub struct Clipboard(_);

A handle to the system clipboard.

To get access to the global clipboard, call Application::clipboard().

Working with text

Copying and pasting text is simple, using Clipboard::put_string and Clipboard::get_string. If this is all you need, you’re in luck.

Advanced usage

When working with data more complicated than plaintext, you will generally want to make that data available in multiple formats.

For instance, if you are writing an image editor, you may have a preferred private format, that preserves metadata or layer information; but in order to interoperate with your user’s other programs, you might also make your data available as an SVG, for other editors, and a bitmap image for applications that can accept general image data.

FormatIdentifiers

In order for other applications to find data we put on the clipboard, (and for us to use data from other applications) we need to use agreed-upon identifiers for our data types. On macOS, these should be Universal Type Identifiers; on other platforms they appear to be mostly MIME types. Several common types are exposed as constants on ClipboardFormat, these consts are set per-platform.

When defining custom formats, you should use the correct identifier for the current platform.

Setting custom data

To put custom data on the clipboard, you create a ClipboardFormat for each type of data you support. You are responsible for ensuring that the data is already correctly serialized.

ClipboardFormat for text

If you wish to put text on the clipboard in addition to other formats, take special care to use ClipboardFormat::TEXT as the FormatId. On windows, we treat this identifier specially, and make sure the data is encoded as a wide string; all other data going into and out of the clipboard is treated as an array of bytes.

Examples

Getting and setting text:

use druid_shell::{Application, Clipboard};

let mut clipboard = Application::global().clipboard();
clipboard.put_string("watch it there pal");
if let Some(contents) = clipboard.get_string() {
    assert_eq!("what it there pal", contents.as_str());
}

Copying multi-format data

use druid_shell::{Application, Clipboard, ClipboardFormat};

let mut clipboard = Application::global().clipboard();

let custom_type_id = "io.xieditor.path-clipboard-type";

let formats = [
   ClipboardFormat::new(custom_type_id, make_custom_data()),
   ClipboardFormat::new(ClipboardFormat::SVG, make_svg_data()),
   ClipboardFormat::new(ClipboardFormat::PDF, make_pdf_data()),
];

clipboard.put_formats(&formats);

Supporting multi-format paste

use druid_shell::{Application, Clipboard, ClipboardFormat};

let clipboard = Application::global().clipboard();

let custom_type_id = "io.xieditor.path-clipboard-type";
let supported_types = &[custom_type_id, ClipboardFormat::SVG, ClipboardFormat::PDF];
let best_available_type = clipboard.preferred_format(supported_types);

if let Some(format) = best_available_type {
    let data = clipboard.get_format(format).expect("I promise not to unwrap in production");
    do_something_with_data(format, data)
}

Implementations

impl Clipboard

pub fn put_string(&mut self, s: impl AsRef<str>)

Put a string onto the system clipboard.

pub fn put_formats(&mut self, formats: &[ClipboardFormat])

Put multi-format data on the system clipboard.

pub fn get_string(&self) -> Option<String>

Get a string from the system clipboard, if one is available.

pub fn preferred_format(&self, formats: &[FormatId]) -> Option<FormatId>

Given a list of supported clipboard types, returns the supported type which has highest priority on the system clipboard, or None if no types are supported.

pub fn get_format(&self, format: FormatId) -> Option<Vec<u8>>

Return data in a given format, if available.

It is recommended that the FormatId argument be a format returned by Clipboard::preferred_format.

Trait Implementations

impl Clone for Clipboard

fn clone(&self) -> Clipboard

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Clipboard

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.