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.
FormatId
entifiers
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 Identifier
s; on other platforms they appear to be
mostly MIME types. Several common types are exposed as constants on
ClipboardFormat
, these const
s 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§
source§impl Clipboard
impl Clipboard
sourcepub fn put_string(&mut self, s: impl AsRef<str>)
pub fn put_string(&mut self, s: impl AsRef<str>)
Put a string onto the system clipboard.
sourcepub fn put_formats(&mut self, formats: &[ClipboardFormat])
pub fn put_formats(&mut self, formats: &[ClipboardFormat])
Put multi-format data on the system clipboard.
sourcepub fn get_string(&self) -> Option<String>
pub fn get_string(&self) -> Option<String>
Get a string from the system clipboard, if one is available.
sourcepub fn preferred_format(&self, formats: &[&'static str]) -> Option<&'static str>
pub fn preferred_format(&self, formats: &[&'static str]) -> Option<&'static str>
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.
sourcepub fn get_format(&self, format: &'static str) -> Option<Vec<u8, Global>>
pub fn get_format(&self, format: &'static str) -> Option<Vec<u8, Global>>
Return data in a given format, if available.
It is recommended that the FormatId
argument be a format returned by
Clipboard::preferred_format
.