Struct DataTransfer 

pub struct DataTransfer { /* private fields */ }

DataTransfer abstracts over the various ways of transferring data within an application and between applications.

The details will depend on the current platform, but the common features are:

• Each DataTransfer contains multiple views over the same data in different formats
• The DataTransfer may contain an in-memory representation of the data, which can be sent and received within the current application
• Serializing to/deserializing from a given format may be done eagerly or lazily¹

Currently, only plaintext and image data is supported. Precisely how this maps to the backend will depend on platform and features. Work to expand this API is ongoing, see the tracking issue for drag-and-drop to follow its progress.

The easiest way to construct this type is with the Default implementation, followed by set_plaintext or set_image. There are also implementations of From<SharedString> and From<Image> which construct a new DataTransfer using those methods respectively. The opposites of these operations are fetch_plaintext and fetch_image.

let message = "Hello, world!";
let data = DataTransfer::from(message.to_shared_string());
assert_eq!(data.fetch_plaintext().unwrap(), message);

---

1. Platforms differ on which formats can and cannot be lazy, but all support it in some capacity. Reading data from a DataTransfer cannot be assumed to be a cheap operation. ↩

Implementations

impl DataTransfer

pub fn set_image(&mut self, image: Image) -> &mut DataTransfer

Sets an image to be transferred by this DataTransfer.

The image can be read using fetch_image. If you only need the DataTransfer to have an image representation, use From<Image>.

Each DataTransfer can only have a single image set at once. If this method is called multiple times, the previous image will be overwritten. However, you can have, for example, both an image representation and a plaintext representation set simultaneously on the same DataTransfer.

pub fn set_plaintext(&mut self, plaintext: SharedString) -> &mut DataTransfer

Sets unstyled, basic text to be transferred by this DataTransfer.

The image can be read using fetch_plaintext. If you only need the DataTransfer to have a plaintext representation, use From<SharedString>.

Each DataTransfer can only have a single plaintext representiation set at once. If this method is called multiple times, the previous text will be overwritten. However, you can have, for example, both an image representation and a plaintext representation set simultaneously on the same DataTransfer.

pub fn has_image(&self) -> bool

Returns true if this data transfer advertises that it is readable as an Image.

This does not necessarily mean that fetch_image will return Ok, as an I/O error may occur.

pub fn has_plaintext(&self) -> bool

Returns true if this data transfer advertises that it is readable as plaintext.

This does not necessarily mean that fetch_plaintext will return Ok, as an I/O error may occur.

pub fn set_user_data(&mut self, value: Rc<dyn Any>) -> &mut DataTransfer

Set the application-internal data represented by this DataTransfer. This can be read with DataTransfer::user_data, and allows circumventing serialize/deserializing the data to bytes when a drag-and-drop or copy-paste operation stays within the application.

pub fn fetch_plaintext(&self) -> Result<SharedString, DataTransferError>

Helper to read this DataTransfer as plaintext, supporting multiple encodings.

The caller should assume that this method call may do I/O.

pub fn fetch_image(&self) -> Result<Image, DataTransferError>

Helper to read this DataTransfer as an image, supporting multiple image types.

The caller should assume that this method call may do I/O.

pub fn user_data(&self) -> Option<Rc<dyn Any>>

Get the application-internal data represented by this DataTransfer, if one exists.

Trait Implementations

impl Clone for DataTransfer

fn clone(&self) -> DataTransfer

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for DataTransfer

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

Formats the value using the given formatter.

impl Default for DataTransfer

fn default() -> DataTransfer

Returns the “default value” for a type.

impl From<DataTransfer> for Value

fn from(v: DataTransfer) -> Self

Converts to this type from the input type.

impl From<Image> for DataTransfer

fn from(value: Image) -> DataTransfer

Converts to this type from the input type.

impl From<SharedString> for DataTransfer

fn from(value: SharedString) -> DataTransfer

Converts to this type from the input type.

impl PartialEq for DataTransfer

fn eq(&self, other: &DataTransfer) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TryFrom<Value> for DataTransfer

type Error = Value

The type returned in the event of a conversion error.

fn try_from(v: Value) -> Result<DataTransfer, Self::Error>

Performs the conversion.