refactor!(core & api): rename drag events for better consistency and clarity (#10170)

* refacotr!(core & api): rename drag events for better consistency and clarity

* more renames

* remove imports

* fix drag over listen

* update example

---------

Co-authored-by: Lucas Nogueira <lucas@tauri.app>

.changes/drag-drop-events-renamed-api.md

@@ -0,0 +1,17 @@
+---
+"@tauri-apps/api": "patch:breaking"
+---
+
+Renamed drag and drop events in `TauriEvent` enum to better convey when they are triggered:
+
+- `TauriEvent.DRAG` -> `TauriEvent.DRAG_ENTER`
+- `TauriEvent.DROP_OVER` -> `TauriEvent.DRAG_OVER`
+- `TauriEvent.DROP` -> `TauriEvent.DRAG_DROP`
+- `TauriEvent.DROP_CANCELLED` -> `TauriEvent::DRAG_LEAVE`
+
+Also the `type` field values in `Window/Webview/WebviewWindow.onDropEvent` and `DragDropEvent` have changed:
+
+- `dragged` -> `enter`
+- `dragOver` -> `over`
+- `dropped` -> `drop`
+- `cancelled` -> `leave`

.changes/drag-drop-events-renamed.md

@@ -0,0 +1,17 @@
+---
+"tauri": "patch:breaking"
+---
+
+Renamed `DragDropEvent` enum variants to better convey when they are triggered:
+
+- `DragDropEvent::Dragged` -> `DragDropEvent::Enter`
+- `DragDropEvent::DragOver` -> `DragDropEvent::Over`
+- `DragDropEvent::Dropped` -> `DragDropEvent::Drop`
+- `DragDropEvent::Cancelled` -> `DragDropEvent::Leave`
+
+This also comes with a change in the events being emitted to JS and Rust event listeners:
+
+- `tauri://drag` -> `tauri://drag-enter`
+- `tauri://drop-over` -> `tauri://drag-over`
+- `tauri://drop` -> `tauri://drag-drop`
+- `tauri://drag-cancelled` -> `tauri://drag-leave`

core/tauri-runtime-wry/src/lib.rs

@@ -3865,21 +3865,21 @@ fn create_webview<T: UserEvent>(
         WryDragDropEvent::Enter {
           paths,
           position: (x, y),
-        } => DragDropEvent::Dragged {
+        } => DragDropEvent::Enter {
           paths,
           position: PhysicalPosition::new(x as _, y as _),
         },
-        WryDragDropEvent::Over { position: (x, y) } => DragDropEvent::DragOver {
+        WryDragDropEvent::Over { position: (x, y) } => DragDropEvent::Over {
           position: PhysicalPosition::new(x as _, y as _),
         },
         WryDragDropEvent::Drop {
           paths,
           position: (x, y),
-        } => DragDropEvent::Dropped {
+        } => DragDropEvent::Drop {
           paths,
           position: PhysicalPosition::new(x as _, y as _),
         },
-        WryDragDropEvent::Leave => DragDropEvent::Cancelled,
+        WryDragDropEvent::Leave => DragDropEvent::Leave,
         _ => unimplemented!(),
       };
 

core/tauri-runtime/src/window.rs

@@ -71,27 +71,27 @@ pub enum WebviewEvent {
 #[derive(Debug, Clone)]
 #[non_exhaustive]
 pub enum DragDropEvent {
-  /// A drag operation started.
-  Dragged {
-    /// Paths of the files that are being dragged.
+  /// A drag operation has entered the webview.
+  Enter {
+    /// List of paths that are being dragged onto the webview.
     paths: Vec<PathBuf>,
     /// The position of the mouse cursor.
     position: dpi::PhysicalPosition<f64>,
   },
-  /// The files have been dragged onto the window, but have not been dropped yet.
-  DragOver {
+  /// A drag operation is moving over the webview.
+  Over {
     /// The position of the mouse cursor.
     position: dpi::PhysicalPosition<f64>,
   },
-  /// The user dropped the operation.
-  Dropped {
-    /// Path of the files that were dropped.
+  /// The file(s) have been dropped onto the webview.
+  Drop {
+    /// List of paths that are being dropped onto the window.
     paths: Vec<PathBuf>,
     /// The position of the mouse cursor.
     position: dpi::PhysicalPosition<f64>,
   },
-  /// The drag operation was cancelled.
-  Cancelled,
+  /// The drag operation has been cancelled or left the window.
+  Leave,
 }
 
 /// Describes the appearance of the mouse cursor.

core/tauri/src/manager/webview.rs

@@ -29,10 +29,7 @@ use crate::{
 };
 
 use super::{
-  window::{
-    DragDropPayload, DragOverPayload, DRAG_EVENT, DROP_CANCELLED_EVENT, DROP_EVENT,
-    DROP_HOVER_EVENT,
-  },
+  window::{DragDropPayload, DRAG_DROP_EVENT, DRAG_ENTER_EVENT, DRAG_LEAVE_EVENT, DRAG_OVER_EVENT},
   AppManager,
 };
 
@@ -689,15 +686,21 @@ impl<R: Runtime> Webview<R> {
 fn on_webview_event<R: Runtime>(webview: &Webview<R>, event: &WebviewEvent) -> crate::Result<()> {
   match event {
     WebviewEvent::DragDrop(event) => match event {
-      DragDropEvent::Dragged { paths, position } => {
-        let payload = DragDropPayload { paths, position };
-        webview.emit_to_webview(DRAG_EVENT, payload)?
+      DragDropEvent::Enter { paths, position } => {
+        let payload = DragDropPayload {
+          paths: Some(paths),
+          position,
+        };
+        webview.emit_to_webview(DRAG_ENTER_EVENT, payload)?
       }
-      DragDropEvent::DragOver { position } => {
-        let payload = DragOverPayload { position };
-        webview.emit_to_webview(DROP_HOVER_EVENT, payload)?
+      DragDropEvent::Over { position } => {
+        let payload = DragDropPayload {
+          position,
+          paths: None,
+        };
+        webview.emit_to_webview(DRAG_OVER_EVENT, payload)?
       }
-      DragDropEvent::Dropped { paths, position } => {
+      DragDropEvent::Drop { paths, position } => {
         let scopes = webview.state::<Scopes>();
         for path in paths {
           if path.is_file() {
@@ -706,10 +709,13 @@ fn on_webview_event<R: Runtime>(webview: &Webview<R>, event: &WebviewEvent) -> c
             let _ = scopes.allow_directory(path, false);
           }
         }
-        let payload = DragDropPayload { paths, position };
-        webview.emit_to_webview(DROP_EVENT, payload)?
+        let payload = DragDropPayload {
+          paths: Some(paths),
+          position,
+        };
+        webview.emit_to_webview(DRAG_DROP_EVENT, payload)?
       }
-      DragDropEvent::Cancelled => webview.emit_to_webview(DROP_CANCELLED_EVENT, ())?,
+      DragDropEvent::Leave => webview.emit_to_webview(DRAG_LEAVE_EVENT, ())?,
       _ => unimplemented!(),
     },
   }

core/tauri/src/manager/window.rs

@@ -29,10 +29,10 @@ const WINDOW_FOCUS_EVENT: &str = "tauri://focus";
 const WINDOW_BLUR_EVENT: &str = "tauri://blur";
 const WINDOW_SCALE_FACTOR_CHANGED_EVENT: &str = "tauri://scale-change";
 const WINDOW_THEME_CHANGED: &str = "tauri://theme-changed";
-pub const DRAG_EVENT: &str = "tauri://drag";
-pub const DROP_EVENT: &str = "tauri://drop";
-pub const DROP_HOVER_EVENT: &str = "tauri://drop-over";
-pub const DROP_CANCELLED_EVENT: &str = "tauri://drag-cancelled";
+pub(crate) const DRAG_ENTER_EVENT: &str = "tauri://drag-enter";
+pub(crate) const DRAG_OVER_EVENT: &str = "tauri://drag-over";
+pub(crate) const DRAG_DROP_EVENT: &str = "tauri://drag-drop";
+pub(crate) const DRAG_LEAVE_EVENT: &str = "tauri://drag-leave";
 
 pub struct WindowManager<R: Runtime> {
   pub windows: Mutex<HashMap<String, Window<R>>>,
@@ -144,13 +144,9 @@ impl<R: Runtime> Window<R> {
 }
 
 #[derive(Serialize, Clone)]
-pub struct DragDropPayload<'a> {
-  pub paths: &'a Vec<PathBuf>,
-  pub position: &'a PhysicalPosition<f64>,
-}
-
-#[derive(Serialize, Clone)]
-pub struct DragOverPayload<'a> {
+pub(crate) struct DragDropPayload<'a> {
+  #[serde(skip_serializing_if = "Option::is_none")]
+  pub paths: Option<&'a Vec<PathBuf>>,
   pub position: &'a PhysicalPosition<f64>,
 }
 
@@ -194,28 +190,38 @@ fn on_window_event<R: Runtime>(window: &Window<R>, event: &WindowEvent) -> crate
       },
     )?,
     WindowEvent::DragDrop(event) => match event {
-      DragDropEvent::Dragged { paths, position } => {
-        let payload = DragDropPayload { paths, position };
+      DragDropEvent::Enter { paths, position } => {
+        let payload = DragDropPayload {
+          paths: Some(paths),
+          position,
+        };
 
         if window.is_webview_window() {
-          window.emit_to(EventTarget::labeled(window.label()), DRAG_EVENT, payload)?
+          window.emit_to(
+            EventTarget::labeled(window.label()),
+            DRAG_ENTER_EVENT,
+            payload,
+          )?
         } else {
-          window.emit_to_window(DRAG_EVENT, payload)?
+          window.emit_to_window(DRAG_ENTER_EVENT, payload)?
         }
       }
-      DragDropEvent::DragOver { position } => {
-        let payload = DragOverPayload { position };
+      DragDropEvent::Over { position } => {
+        let payload = DragDropPayload {
+          position,
+          paths: None,
+        };
         if window.is_webview_window() {
           window.emit_to(
             EventTarget::labeled(window.label()),
-            DROP_HOVER_EVENT,
+            DRAG_OVER_EVENT,
             payload,
           )?
         } else {
-          window.emit_to_window(DROP_HOVER_EVENT, payload)?
+          window.emit_to_window(DRAG_OVER_EVENT, payload)?
         }
       }
-      DragDropEvent::Dropped { paths, position } => {
+      DragDropEvent::Drop { paths, position } => {
         let scopes = window.state::<Scopes>();
         for path in paths {
           if path.is_file() {
@@ -224,23 +230,26 @@ fn on_window_event<R: Runtime>(window: &Window<R>, event: &WindowEvent) -> crate
             let _ = scopes.allow_directory(path, true);
           }
         }
-        let payload = DragDropPayload { paths, position };
+        let payload = DragDropPayload {
+          paths: Some(paths),
+          position,
+        };
 
         if window.is_webview_window() {
-          window.emit_to(EventTarget::labeled(window.label()), DROP_EVENT, payload)?
+          window.emit_to(
+            EventTarget::labeled(window.label()),
+            DRAG_DROP_EVENT,
+            payload,
+          )?
         } else {
-          window.emit_to_window(DROP_EVENT, payload)?
+          window.emit_to_window(DRAG_DROP_EVENT, payload)?
         }
       }
-      DragDropEvent::Cancelled => {
+      DragDropEvent::Leave => {
         if window.is_webview_window() {
-          window.emit_to(
-            EventTarget::labeled(window.label()),
-            DROP_CANCELLED_EVENT,
-            (),
-          )?
+          window.emit_to(EventTarget::labeled(window.label()), DRAG_LEAVE_EVENT, ())?
         } else {
-          window.emit_to_window(DROP_CANCELLED_EVENT, ())?
+          window.emit_to_window(DRAG_LEAVE_EVENT, ())?
         }
       }
       _ => unimplemented!(),

examples/api/src-tauri/Cargo.lock

@@ -4035,17 +4035,6 @@ dependencies = [
  "syn 2.0.63",
 ]
 
-[[package]]
-name = "windows-implement"
-version = "0.56.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f6fc35f58ecd95a9b71c4f2329b911016e6bec66b3f2e6a4aad86bd2e99e2f9b"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.52",
-]
-
 [[package]]
 name = "windows-interface"
 version = "0.57.0"
@@ -4057,17 +4046,6 @@ dependencies = [
  "syn 2.0.63",
 ]
 
-[[package]]
-name = "windows-interface"
-version = "0.56.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "08990546bf4edef8f431fa6326e032865f27138718c587dc21bc0265bbcb57cc"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.52",
-]
-
 [[package]]
 name = "windows-result"
 version = "0.1.1"

examples/api/src/App.svelte

@@ -2,6 +2,7 @@
   import { onMount, tick } from 'svelte'
   import { writable } from 'svelte/store'
   import { invoke } from '@tauri-apps/api/core'
+  import { getCurrentWebviewWindow } from '@tauri-apps/api/webviewWindow'
 
   import Welcome from './views/Welcome.svelte'
   import Communication from './views/Communication.svelte'
@@ -17,6 +18,11 @@
     }
   })
 
+  const appWindow = getCurrentWebviewWindow()
+  appWindow.onDragDropEvent((event) => {
+    onMessage(event.payload)
+  })
+
   const userAgent = navigator.userAgent.toLowerCase()
   const isMobile = userAgent.includes('android') || userAgent.includes('iphone')
 

tooling/api/src/event.ts

@@ -57,10 +57,10 @@ enum TauriEvent {
   WINDOW_THEME_CHANGED = 'tauri://theme-changed',
   WINDOW_CREATED = 'tauri://window-created',
   WEBVIEW_CREATED = 'tauri://webview-created',
-  DRAG = 'tauri://drag',
-  DROP = 'tauri://drop',
-  DROP_OVER = 'tauri://drop-over',
-  DROP_CANCELLED = 'tauri://drag-cancelled'
+  DRAG_ENTER = 'tauri://drag-enter',
+  DRAG_OVER = 'tauri://drag-over',
+  DRAG_DROP = 'tauri://drag-drop',
+  DRAG_LEAVE = 'tauri://drag-leave'
 }
 
 /**

tooling/api/src/webview.ts

@@ -32,21 +32,12 @@ import { invoke } from './core'
 import { Window, getCurrentWindow } from './window'
 import { WebviewWindow } from './webviewWindow'
 
-interface DragDropPayload {
-  paths: string[]
-  position: PhysicalPosition
-}
-
-interface DragOverPayload {
-  position: PhysicalPosition
-}
-
 /** The drag and drop event types. */
 type DragDropEvent =
-  | ({ type: 'dragged' } & DragDropPayload)
-  | ({ type: 'dragOver' } & DragOverPayload)
-  | ({ type: 'dropped' } & DragDropPayload)
-  | { type: 'cancelled' }
+  | { type: 'enter'; paths: string[]; position: PhysicalPosition }
+  | { type: 'over'; position: PhysicalPosition }
+  | { type: 'drop'; paths: string[]; position: PhysicalPosition }
+  | { type: 'leave' }
 
 /**
  * Get an instance of `Webview` for the current webview.
@@ -545,13 +536,15 @@ class Webview {
   async onDragDropEvent(
     handler: EventCallback<DragDropEvent>
   ): Promise<UnlistenFn> {
-    const unlistenDrag = await this.listen<DragDropPayload>(
-      TauriEvent.DRAG,
+    type DragPayload = { paths: string[]; position: PhysicalPosition }
+
+    const unlistenDragEnter = await this.listen<DragPayload>(
+      TauriEvent.DRAG_ENTER,
       (event) => {
         handler({
           ...event,
           payload: {
-            type: 'dragged',
+            type: 'enter',
             paths: event.payload.paths,
             position: mapPhysicalPosition(event.payload.position)
           }
@@ -559,45 +552,45 @@ class Webview {
       }
     )
 
-    const unlistenDrop = await this.listen<DragDropPayload>(
-      TauriEvent.DROP,
+    const unlistenDragOver = await this.listen<DragPayload>(
+      TauriEvent.DRAG_OVER,
       (event) => {
         handler({
           ...event,
           payload: {
-            type: 'dropped',
-            paths: event.payload.paths,
+            type: 'over',
             position: mapPhysicalPosition(event.payload.position)
           }
         })
       }
     )
 
-    const unlistenDragOver = await this.listen<DragDropPayload>(
-      TauriEvent.DROP_CANCELLED,
+    const unlistenDragDrop = await this.listen<DragPayload>(
+      TauriEvent.DRAG_DROP,
       (event) => {
         handler({
           ...event,
           payload: {
-            type: 'dragOver',
+            type: 'drop',
+            paths: event.payload.paths,
             position: mapPhysicalPosition(event.payload.position)
           }
         })
       }
     )
 
-    const unlistenCancel = await this.listen<null>(
-      TauriEvent.DROP_CANCELLED,
+    const unlistenDragLeave = await this.listen<null>(
+      TauriEvent.DRAG_LEAVE,
       (event) => {
-        handler({ ...event, payload: { type: 'cancelled' } })
+        handler({ ...event, payload: { type: 'leave' } })
       }
     )
 
     return () => {
-      unlistenDrag()
-      unlistenDrop()
+      unlistenDragEnter()
+      unlistenDragDrop()
       unlistenDragOver()
-      unlistenCancel()
+      unlistenDragLeave()
     }
   }
 }
@@ -682,4 +675,4 @@ interface WebviewOptions {
 
 export { Webview, getCurrentWebview, getAllWebviews }
 
-export type { DragDropEvent, DragDropPayload, WebviewOptions }
+export type { DragDropEvent, WebviewOptions }

tooling/api/src/webviewWindow.ts

@@ -13,7 +13,7 @@ import { Window } from './window'
 import { listen, once } from './event'
 import type { EventName, EventCallback, UnlistenFn } from './event'
 import { invoke } from './core'
-import type { DragDropEvent, DragDropPayload } from './webview'
+import type { DragDropEvent } from './webview'
 
 /**
  * Get an instance of `Webview` for the current webview window.
@@ -236,4 +236,4 @@ function applyMixins(
 }
 
 export { WebviewWindow, getCurrentWebviewWindow, getAllWebviewWindows }
-export type { DragDropEvent, DragDropPayload }
+export type { DragDropEvent }

tooling/api/src/window.ts

@@ -34,7 +34,7 @@ import {
 } from './event'
 import { invoke } from './core'
 import { WebviewWindow } from './webviewWindow'
-import type { DragDropEvent, DragDropPayload } from './webview'
+import type { DragDropEvent } from './webview'
 import { Image, transformImage } from './image'
 
 /**
@@ -1751,13 +1751,15 @@ class Window {
   async onDragDropEvent(
     handler: EventCallback<DragDropEvent>
   ): Promise<UnlistenFn> {
-    const unlistenDrag = await this.listen<DragDropPayload>(
-      TauriEvent.DRAG,
+    type DragPayload = { paths: string[]; position: PhysicalPosition }
+
+    const unlistenDrag = await this.listen<DragPayload>(
+      TauriEvent.DRAG_ENTER,
       (event) => {
         handler({
           ...event,
           payload: {
-            type: 'dragged',
+            type: 'enter',
             paths: event.payload.paths,
             position: mapPhysicalPosition(event.payload.position)
           }
@@ -1765,27 +1767,27 @@ class Window {
       }
     )
 
-    const unlistenDrop = await this.listen<DragDropPayload>(
-      TauriEvent.DROP,
+    const unlistenDragOver = await this.listen<DragPayload>(
+      TauriEvent.DRAG_OVER,
       (event) => {
         handler({
           ...event,
           payload: {
-            type: 'dropped',
-            paths: event.payload.paths,
+            type: 'over',
             position: mapPhysicalPosition(event.payload.position)
           }
         })
       }
     )
 
-    const unlistenDragOver = await this.listen<DragDropPayload>(
-      TauriEvent.DROP_OVER,
+    const unlistenDrop = await this.listen<DragPayload>(
+      TauriEvent.DRAG_DROP,
       (event) => {
         handler({
           ...event,
           payload: {
-            type: 'dragOver',
+            type: 'drop',
+            paths: event.payload.paths,
             position: mapPhysicalPosition(event.payload.position)
           }
         })
@@ -1793,9 +1795,9 @@ class Window {
     )
 
     const unlistenCancel = await this.listen<null>(
-      TauriEvent.DROP_CANCELLED,
+      TauriEvent.DRAG_LEAVE,
       (event) => {
-        handler({ ...event, payload: { type: 'cancelled' } })
+        handler({ ...event, payload: { type: 'leave' } })
       }
     )
 
@@ -2327,6 +2329,5 @@ export type {
   ScaleFactorChanged,
   WindowOptions,
   Color,
-  DragDropEvent,
-  DragDropPayload
+  DragDropEvent
 }