New drag and drop API

winit-core/src/data_transfer.rs

@@ -0,0 +1,175 @@
+//! Types related to data transfer, used for clipboard and drag-and-drop.
+//!
+//! This module contains types and traits implementing cross-application data transfer.
+//! While the precise implementation depends on platform, there are a set of types which
+//! can be safely transferred between applications on all platforms (see [`TypeHint`]).
+//!
+//! On all platforms, the process looks something like this:
+//!
+//! - A data transfer advertises a set of types which the data can be interpreted as
+//!   - For example, if you copy or drag text from a web page, the browser may advertise the text
+//!     formatted using HTML, the text formatted as RTF, and the text with all formatting removed
+//!     simultaneously.
+//! - An application receiving a data transfer chooses one or more types that it understands and
+//!   requests the data in those formats (in practice, it will usually only request a single
+//!   format).
+//! - The source application converts the data stored in its memory to the requested format and
+//!   asynchronously sends it to the target application
+//!
+//! On some platforms, the data is sometimes available synchronously, but all platforms have at
+//! least some method of sending the data asynchronously and some types of data that may _only_ be
+//! sent using the asynchronous interface. Because of this, the API in winit must be asynchronous.
+//!
+//! The flow for a user application that implements drag-and-drop would look something like this:
+//!
+//! - The application receives a [`DragEnter`](crate::event::WindowEvent::DragEnter) event. This
+//!   event supplies a [`DataTransferId`] which can be used to request information or operations on
+//!   the dragged data by using methods on [`Window`](crate::window::Window).
+//! - As the drag operation continues, the window will receive
+//!   [`DragMoved`](crate::event::WindowEvent::DragEnter) events.
+//! - While `DragMoved` events are being received, the receiving application may mark the data as
+//!   being accepted or rejected. This will update the OS/compositor to display the correct UI to
+//!   the user. Accepting does not "finalize" the drag operation, nor does rejecting cancel it.
+//! - At any point during this operation, the receiving application may request either the available
+//!   types or even the data being transferred. This may be useful in cases where the application
+//!   wants to preload the data. For example, an image editor may want to display the image on the
+//!   canvas during the drag operation.
+//! - When the user tries to drop the data onto the window, that window will receive a
+//!   [`DragDropped`](crate::event::WindowEvent::DragDropped) event. In general, the receiving
+//!   application should assume that calling [`reject_drag`](crate::window::Window::reject_drag)
+//!   after `DragDropped` is received ends the lifecycle of the data transfer.
+//!
+//! If platform-dependent behavior is required, a platform may define internal types
+//! implementing the traits in this module, which can then be accessed in an application
+//! using the methods defined on [`dyn AsAny`]. See each platform's documentation for details.
+
+use std::fmt::{self, Debug};
+use std::io;
+
+use crate::as_any::AsAny;
+
+/// Unique identifier for a data transfer.
+#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct DataTransferId(i64);
+
+impl DataTransferId {
+    /// Convert the [`DataTransferId`] into the underlying integer.
+    ///
+    /// This is useful if you need to pass the ID across an FFI boundary, or store it in an atomic.
+    pub const fn into_raw(self) -> i64 {
+        self.0
+    }
+
+    /// Construct a [`DataTransferId`] from the underlying integer.
+    ///
+    /// This should only be called with integers returned from [`DataTransferId::into_raw`].
+    pub const fn from_raw(id: i64) -> Self {
+        Self(id)
+    }
+}
+
+/// The set of types supported cross-platform.
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+pub enum TypeHint {
+    /// Plain UTF-8 text (see [`TypedData::try_as_plaintext`]).
+    ///
+    /// **Note for platform implementations**: this hint is _only_ for UTF-8 text. If the platform
+    /// returns plaintext in some format other than UTF-8 by default, a [`TypedData`]
+    /// implementation marked with this type hint should convert to UTF-8.
+    Plaintext,
+    /// A list of URIs in the format defined by the `text/uri-list` MIME type, encoded as UTF-8 (see
+    /// [`TypedData::try_as_uris`]).
+    ///
+    /// **Note for platform implementations**: this hint is _only_ for URIs encoded precisely in the
+    /// format specified above. If the platform uses a different format, a [`TypedData`]
+    /// implementation marked with this type hint should convert to that format.
+    UriList,
+    /// A HTML-formatted string
+    Html,
+    /// An RTF-formatted string
+    Rtf,
+    /// Audio
+    Audio {
+        /// An optional hint for the encoding of the supplied bytes, specified using the standard
+        /// file extension for that audio format, lowercase and without the leading `.`.
+        extension_hint: Option<&'static str>,
+    },
+    /// Image data
+    Image {
+        /// An optional hint for the encoding of the supplied bytes, specified using the standard
+        /// file extension for that audio format, lowercase and without the leading `.`.
+        extension_hint: Option<&'static str>,
+    },
+}
+
+/// The type of a data transfer.
+///
+/// [`hint`](TransferType::hint) can be called to get the type in
+/// a cross-platform format (see [`TypeHint`])
+pub trait TransferType: AsAny + Send + Sync + fmt::Debug {
+    /// Get the cross-platform representation of this type.
+    ///
+    /// If this returns `None`, then this is a platform-dependent type that has no cross-platform
+    /// equivalent.
+    fn hint(&self) -> Option<TypeHint>;
+}
+
+impl TransferType for TypeHint {
+    fn hint(&self) -> Option<TypeHint> {
+        Some(*self)
+    }
+}
+
+impl_dyn_casting!(TransferType);
+
+/// Data that has been fetched from a data transfer
+pub trait TypedData: AsAny + Send + Sync + fmt::Debug {
+    /// The type of this `TypedData`.
+    fn type_(&self) -> &dyn TransferType;
+
+    /// If this value is readable as bytes, return a reader than can be used to read those bytes.
+    fn try_read(&mut self) -> Option<Box<dyn io::BufRead + '_>>;
+
+    /// Read this value as a list of URIs.
+    ///
+    /// If this value is not readable as URIs, return `None`.
+    ///
+    /// The format of the returned URIs is simply a vector of strings. No validation is done
+    /// to ensure that the URIs are valid or in the format
+    fn try_as_uris(&mut self) -> Option<Vec<String>>;
+
+    /// Read this value as a plain text string.
+    ///
+    /// If this value is not readable as a string, return `None`.
+    fn try_as_string(&mut self) -> Option<String>;
+}
+
+impl_dyn_casting!(TypedData);
+
+/// Metadata about a data transfer. This does not allow actually receiving data, as that is an
+/// asynchronous operation. To fetch the data from the source application, see
+/// [`Window::fetch_data_transfer`](crate::window::Window::fetch_data_transfer)
+/// and [`WindowEvent::DataTransferResult`](crate::event::WindowEvent::DataTransferResult).
+pub trait DataTransfer: AsAny + Send + Sync + fmt::Debug {
+    /// Display the list of all available types.
+    ///
+    /// This is useful if more-complex type matching is required, but for most cases
+    /// [`has_type`](DataTransfer::has_type) should be used.
+    // TODO: We should be able to do `&dyn TransferType`, but some implementation details in
+    // the platforms make that unnecessarily difficult right now. Specifically, use of `RwLock`.
+    fn available_types(&self) -> Vec<Box<dyn TransferType>>;
+
+    /// Check if the supplied type is provided by this [`DataTransfer`].
+    ///
+    /// Supplying a [`TypeHint`] as the type is supported on all platforms, but if some
+    /// platform-specific type is required then that platform's implementation of `TransferType` can
+    /// be used.
+    fn has_type(&self, type_: &dyn TransferType) -> bool {
+        let available_types = self.available_types();
+        type_.hint().is_some_and(|hint| {
+            available_types.iter().any(|haystack| haystack.hint() == Some(hint))
+        })
+    }
+}
+
+impl_dyn_casting!(DataTransfer);

winit-core/src/event.rs

@@ -2,7 +2,6 @@
 use std::cell::LazyCell;
 use std::cmp::Ordering;
 use std::f64;
-use std::path::PathBuf;
 use std::sync::{Mutex, Weak};
 
 use dpi::{PhysicalPosition, PhysicalSize};
@@ -11,6 +10,7 @@ use serde::{Deserialize, Serialize};
 use smol_str::SmolStr;
 
 use crate::Instant;
+use crate::data_transfer::DataTransferId;
 use crate::error::RequestError;
 use crate::event_loop::AsyncRequestSerial;
 use crate::keyboard::{self, ModifiersKeyState, ModifiersKeys, ModifiersState};
@@ -77,41 +77,32 @@ pub enum WindowEvent {
 
     /// A file drag operation has entered the window.
     DragEntered {
-        /// List of paths that are being dragged onto the window.
-        paths: Vec<PathBuf>,
-        /// (x,y) coordinates in pixels relative to the top-left corner of the window. May be
-        /// negative on some platforms if something is dragged over a window's decorations (title
-        /// bar, frame, etc).
-        position: PhysicalPosition<f64>,
+        /// Data transfer object specifying the ID and available types.
+        id: DataTransferId,
     },
     /// A file drag operation has moved over the window.
-    DragMoved {
+    DragPosition {
+        /// Data transfer object specifying the ID and available types.
+        id: DataTransferId,
         /// (x,y) coordinates in pixels relative to the top-left corner of the window. May be
         /// negative on some platforms if something is dragged over a window's decorations (title
         /// bar, frame, etc).
         position: PhysicalPosition<f64>,
     },
     /// The file drag operation has dropped file(s) on the window.
     DragDropped {
-        /// List of paths that are being dragged onto the window.
-        paths: Vec<PathBuf>,
-        /// (x,y) coordinates in pixels relative to the top-left corner of the window. May be
-        /// negative on some platforms if something is dragged over a window's decorations (title
-        /// bar, frame, etc).
-        position: PhysicalPosition<f64>,
+        /// Data transfer object specifying the ID and available types.
+        id: DataTransferId,
     },
     /// The file drag operation has been cancelled or left the window.
     DragLeft {
-        /// (x,y) coordinates in pixels relative to the top-left corner of the window. May be
-        /// negative on some platforms if something is dragged over a window's decorations (title
-        /// bar, frame, etc).
-        ///
-        /// ## Platform-specific
-        ///
-        /// - **Windows:** Always emits [`None`].
-        position: Option<PhysicalPosition<f64>>,
+        /// Data transfer object specifying the ID and available types.
+        id: DataTransferId,
     },
 
+    /// The result of a data transfer is available.
+    DataTransferResult { id: DataTransferId, serial: AsyncRequestSerial },
+
     /// The window gained or lost focus.
     ///
     /// The parameter is true if the window has gained focus, and false if it has lost focus.
@@ -1560,16 +1551,19 @@ mod tests {
             use crate::event::Ime::Enabled;
             use crate::event::WindowEvent::*;
             use crate::event::{PointerKind, PointerSource};
+            use crate::data_transfer::DataTransferId;
+
+            let dnd_data = DataTransferId::from_raw(123);
 
             with_window_event(CloseRequested);
             with_window_event(Destroyed);
             with_window_event(Focused(true));
             with_window_event(Moved((0, 0).into()));
             with_window_event(SurfaceResized((0, 0).into()));
-            with_window_event(DragEntered { paths: vec!["x.txt".into()], position: (0, 0).into() });
-            with_window_event(DragMoved { position: (0, 0).into() });
-            with_window_event(DragDropped { paths: vec!["x.txt".into()], position: (0, 0).into() });
-            with_window_event(DragLeft { position: Some((0, 0).into()) });
+            with_window_event(DragEntered { id: dnd_data});
+            with_window_event(DragPosition { id: dnd_data, position: (0, 0).into() });
+            with_window_event(DragDropped { id: dnd_data });
+            with_window_event(DragLeft { id: dnd_data });
             with_window_event(Ime(Enabled));
             with_window_event(PointerMoved {
                 device_id: None,

winit-core/src/event_loop/mod.rs

@@ -3,7 +3,7 @@ pub mod pump_events;
 pub mod register;
 pub mod run_on_demand;
 
-use std::fmt::{self, Debug};
+use std::fmt::{self, Debug, Display};
 use std::sync::Arc;
 use std::sync::atomic::{AtomicUsize, Ordering};
 use std::time::Duration;
@@ -13,10 +13,24 @@ use rwh_06::{DisplayHandle, HandleError, HasDisplayHandle};
 use crate::Instant;
 use crate::as_any::AsAny;
 use crate::cursor::{CustomCursor, CustomCursorSource};
-use crate::error::RequestError;
+use crate::data_transfer::{DataTransfer, DataTransferId, TransferType, TypedData};
+use crate::error::{NotSupportedError, RequestError};
 use crate::monitor::MonitorHandle;
 use crate::window::{Theme, Window, WindowAttributes};
 
+/// An operation was attempted on a data transfer ID, but that ID was invalid.
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+pub struct UnknownDataTransfer(pub DataTransferId);
+
+impl Display for UnknownDataTransfer {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let id = self.0.into_raw();
+        write!(f, "Unknown data transfer with ID {id}")
+    }
+}
+
+impl std::error::Error for UnknownDataTransfer {}
+
 pub trait ActiveEventLoop: AsAny + fmt::Debug {
     /// Creates an [`EventLoopProxy`] that can be used to dispatch user events
     /// to the main event loop, possibly from another thread.
@@ -114,6 +128,93 @@ pub trait ActiveEventLoop: AsAny + fmt::Debug {
 
     /// Get the raw-window-handle handle.
     fn rwh_06_handle(&self) -> &dyn HasDisplayHandle;
+
+    /// Request to fetch a type from a [data transfer](crate::data_transfer::DataTransfer).
+    ///
+    /// This may be called multiple times on the same [`DataTransferId`] with different types.
+    fn fetch_data_transfer(
+        &self,
+        id: DataTransferId,
+        type_: &dyn TransferType,
+    ) -> Result<AsyncRequestSerial, RequestError> {
+        let _ = id;
+        let _ = type_;
+        Err(RequestError::NotSupported(NotSupportedError::new(
+            "Cross-application data transfer (e.g. drag-and-drop, clipboard) is unsupported on \
+             this platform",
+        )))
+    }
+
+    /// Get the resolved data for a data transfer.
+    ///
+    /// Requires first calling [`fetch_data_transfer`](ActiveEventLoop::fetch_data_transfer) and
+    /// waiting for the corresponding `DataTransferResult` event.
+    fn data_transfer_result(
+        &self,
+        serial: AsyncRequestSerial,
+    ) -> Result<Box<dyn TypedData>, RequestError> {
+        let _ = serial;
+        Err(RequestError::NotSupported(NotSupportedError::new(
+            "Cross-application data transfer (e.g. drag-and-drop, clipboard) is unsupported on \
+             this platform",
+        )))
+    }
+
+    /// Get a [data transfer](DataTransfer) by its ID.
+    ///
+    /// If the ID is invalid (e.g. if the lifetime of the data transfer has expired), this will
+    /// return an error.
+    fn data_transfer(
+        &self,
+        id: DataTransferId,
+    ) -> Result<Box<dyn DataTransfer>, UnknownDataTransfer> {
+        Err(UnknownDataTransfer(id))
+    }
+
+    /// Mark a given data transfer ID as being accepted by the window. By default, a drag will be
+    /// rejected.
+    ///
+    /// This allows the OS/compositor to display the correct UI, indicating that the dragged data
+    /// can be dropped.
+    ///
+    /// Note that on some platforms (e.g. Wayland), accepting a data transfer requires specifying
+    /// one or more accepted types. For platforms that require specifying a type, `accept_drag` will
+    /// mark all available types as accepted.
+    ///
+    /// For the most reliable cross-platform behaviour,
+    /// [`accept_drag_type`](Window::accept_drag_type) is preferred.
+    fn accept_drag(&self, id: DataTransferId) -> Result<(), UnknownDataTransfer> {
+        Err(UnknownDataTransfer(id))
+    }
+
+    /// Mark a single type of a given data transfer ID as being accepted by the window. By default,
+    /// a drag will be rejected.
+    ///
+    /// This allows the OS/compositor to display the correct UI, indicating that the dragged data
+    /// can be dropped.
+    ///
+    /// If the window may accept more than one of the advertised types, this method should be
+    /// called multiple times, once for each of the accepted types.
+    fn accept_drag_type(
+        &self,
+        id: DataTransferId,
+        type_: &dyn TransferType,
+    ) -> Result<(), UnknownDataTransfer> {
+        let _ = type_;
+        self.accept_drag(id)
+    }
+
+    /// Mark a given data transfer ID as being rejected by the window. This is the default if
+    /// `accept_drag`/`accept_drag_type` is never called.
+    ///
+    /// This allows the OS/compositor to display the correct UI, indicating that the dragged data
+    /// can _not_ be dropped.
+    ///
+    /// This will ensure that the OS/compositor indicates to the user that dropping the dragged data
+    /// is not possible.
+    fn reject_drag(&self, id: DataTransferId) -> Result<(), UnknownDataTransfer> {
+        Err(UnknownDataTransfer(id))
+    }
 }
 
 impl HasDisplayHandle for dyn ActiveEventLoop + '_ {