Struct druid_shell::Clipboard[][src]

pub struct Clipboard(_);
Expand description

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

Put a string onto the system clipboard.

Put multi-format data on the system clipboard.

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

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.

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

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Performs the conversion.

Performs the conversion.

Performs the conversion.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more