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 plain text 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_plain_text 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 plain_text and image.

let message = "Hello, world!";
let data = DataTransfer::from(message.to_shared_string());
assert_eq!(data.plain_text().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 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 plain text representation set simultaneously on the same DataTransfer.

Passing a default-constructed Image clears the previously-set image instead of storing it, so afterwards has_image returns false. If the resulting DataTransfer carries no plain text, image, or user data, it compares equal to DataTransfer::default().

pub fn set_plain_text(&mut self, plain_text: SharedString) -> &mut DataTransfer

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

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

Each DataTransfer can only have a single plain text representation 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 plain text representation set simultaneously on the same DataTransfer.

Passing an empty string clears the previously-set plain text instead of storing it, so afterwards has_plain_text returns false. If the resulting DataTransfer carries no plain text, image, or user data, it compares equal to DataTransfer::default().

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 image will return Ok, as an I/O error may occur.

pub fn has_plain_text(&self) -> bool

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

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

pub fn is_empty(&self) -> bool

Returns true if this data transfer carries no data: no plain text, no image, and no user data. A DataTransfer constructed via Default::default is empty.

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 plain_text(&self) -> Result<SharedString, DataTransferError>

Helper to read this DataTransfer as plain text, supporting multiple encodings.

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

pub fn 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.