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/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'
 }
 
 /**