fix: browser drag completion lifecycle (#192)

Author: dsh0416

crates/gdcef/src/browser.rs

@@ -465,6 +465,7 @@ pub struct DragState {
     pub is_drag_over: bool,
     pub is_dragging_from_browser: bool,
     pub allowed_ops: u32,
+    pub source_position: Option<(i32, i32)>,
 }
 
 /// Rendering mode for the CEF browser.
@@ -667,13 +668,15 @@ mod tests {
             app.drag_state.is_drag_over = true;
             app.drag_state.is_dragging_from_browser = true;
             app.drag_state.allowed_ops = u32::MAX;
+            app.drag_state.source_position = Some((10, 20));
 
             app.clear_runtime_state();
 
             assert!(app.state.is_none());
             assert!(!app.drag_state.is_drag_over);
             assert!(!app.drag_state.is_dragging_from_browser);
             assert_eq!(app.drag_state.allowed_ops, 0);
+            assert_eq!(app.drag_state.source_position, None);
         }
     }
 

crates/gdcef/src/cef_texture/mod.rs

@@ -769,17 +769,33 @@ impl CefTexture {
             let Some(host) = app.host() else {
                 return;
             };
+            if !app.drag_state.is_dragging_from_browser {
+                return;
+            }
             host.drag_source_ended_at(position.x as i32, position.y as i32, op);
+            host.drag_source_system_drag_ended();
             app.drag_state.is_dragging_from_browser = false;
+            app.drag_state.source_position = None;
+            app.drag_state.allowed_ops = 0;
         });
     }
 
     #[func]
     pub fn drag_source_system_ended(&mut self) {
-        self.with_app(|app| {
-            if let Some(host) = app.host() {
-                host.drag_source_system_drag_ended();
+        self.with_app_mut(|app| {
+            let Some(host) = app.host() else {
+                return;
+            };
+            if !app.drag_state.is_dragging_from_browser {
+                return;
             }
+            let (x, y) = app.drag_state.source_position.unwrap_or((0, 0));
+            let op = cef::DragOperationsMask::from(cef::sys::cef_drag_operations_mask_t(0));
+            host.drag_source_ended_at(x, y, op);
+            host.drag_source_system_drag_ended();
+            app.drag_state.is_dragging_from_browser = false;
+            app.drag_state.source_position = None;
+            app.drag_state.allowed_ops = 0;
         });
     }
 

crates/gdcef/src/cef_texture/signals.rs

@@ -288,17 +288,18 @@ impl CefTexture {
                 } => {
                     let drag_info = DragDataInfo::from_internal(drag_data);
                     let position = Vector2::new(*x as f32, *y as f32);
+                    self.with_app_mut(|app| {
+                        app.drag_state.is_dragging_from_browser = true;
+                        app.drag_state.allowed_ops = *allowed_ops;
+                        app.drag_state.source_position = Some((*x, *y));
+                    });
                     emit_signal_variants!(
                         self,
                         "drag_started",
                         drag_info,
                         position,
                         *allowed_ops as i32
                     );
-                    self.with_app_mut(|app| {
-                        app.drag_state.is_dragging_from_browser = true;
-                        app.drag_state.allowed_ops = *allowed_ops;
-                    });
                 }
                 DragEvent::UpdateCursor { operation } => {
                     emit_signal_variants!(self, "drag_cursor_updated", *operation as i32);

docs/api/drag-and-drop.md

@@ -172,11 +172,11 @@ func _on_drag_entered(drag_data: DragDataInfo, mask: int):
 
 ### Notifying CEF When Browser Drag Ends
 
-When a drag that started from the browser ends (either dropped somewhere or cancelled), you should notify CEF:
+When a drag that started from the browser ends, notify CEF exactly once:
 
 #### `drag_source_ended(position: Vector2, operation: int)`
 
-Call when a browser-initiated drag ends with a specific result.
+Call when a browser-initiated drag ends with a specific drop result. This completes the browser drag operation.
 
 ```gdscript
 func _on_drop_completed(drop_position: Vector2, was_accepted: bool):
@@ -187,7 +187,7 @@ func _on_drop_completed(drop_position: Vector2, was_accepted: bool):
 
 #### `drag_source_system_ended()`
 
-Call when the system drag operation ends (cleanup).
+Call when a browser-initiated drag is cancelled or ends without a drop result. This completes the browser drag operation with `DragOperation.NONE`.
 
 ```gdscript
 func _notification(what):
@@ -253,6 +253,7 @@ func _drop_data(at_position: Vector2, data):
     if data is DragDataInfo and data.is_link:
         _add_item_from_url(data.link_url)
         cef_texture.drag_source_ended(at_position, DragOperation.COPY)
+        browser_drag_data = null
 
 func _notification(what):
     if what == NOTIFICATION_DRAG_END:

docs/api/methods.md

@@ -442,15 +442,15 @@ func _drop_data(at_position: Vector2, data):
 
 ### `drag_source_ended(position: Vector2, operation: int)`
 
-Notifies CEF that a browser-initiated drag has ended. Call this when handling drops from the browser into your game.
+Notifies CEF that a browser-initiated drag ended with a drop result. This completes the browser drag operation, so do not call `drag_source_system_ended()` afterward.
 
 ```gdscript
 cef_texture.drag_source_ended(drop_position, DragOperation.COPY)
 ```
 
 ### `drag_source_system_ended()`
 
-Notifies CEF that the system drag operation has ended. Call this for cleanup after browser-initiated drags.
+Notifies CEF that a browser-initiated drag was cancelled or ended without a drop result. This completes the browser drag operation with `DragOperation.NONE`.
 
 ```gdscript
 cef_texture.drag_source_system_ended()

docs/zh_CN/api/drag-and-drop.md

@@ -172,11 +172,11 @@ func _on_drag_entered(drag_data: DragDataInfo, mask: int):
 
 ### 通知 CEF 浏览器拖动结束
 
-当从浏览器发起的拖动结束（被放下或取消）时，您应该通知 CEF：
+当从浏览器发起的拖动结束时，只通知 CEF 一次：
 
 #### `drag_source_ended(position: Vector2, operation: int)`
 
-当浏览器发起的拖动以特定结果结束时调用。
+当浏览器发起的拖动以特定放置结果结束时调用。此方法会完成浏览器拖动操作。
 
 ```gdscript
 func _on_drop_completed(drop_position: Vector2, was_accepted: bool):
@@ -187,7 +187,7 @@ func _on_drop_completed(drop_position: Vector2, was_accepted: bool):
 
 #### `drag_source_system_ended()`
 
-当系统拖动操作结束时调用（清理）。
+当浏览器发起的拖动被取消，或没有放置结果就结束时调用。此方法会以 `DragOperation.NONE` 完成浏览器拖动操作。
 
 ```gdscript
 func _notification(what):
@@ -253,6 +253,7 @@ func _drop_data(at_position: Vector2, data):
     if data is DragDataInfo and data.is_link:
         _add_item_from_url(data.link_url)
         cef_texture.drag_source_ended(at_position, DragOperation.COPY)
+        browser_drag_data = null
 
 func _notification(what):
     if what == NOTIFICATION_DRAG_END:

docs/zh_CN/api/methods.md

@@ -342,15 +342,15 @@ func _drop_data(at_position: Vector2, data):
 
 ### `drag_source_ended(position: Vector2, operation: int)`
 
-通知 CEF 浏览器发起的拖动已结束。在处理从浏览器拖放到游戏中时调用此方法。
+通知 CEF 浏览器发起的拖动已用放置结果结束。此方法会完成浏览器拖动操作，因此之后不要再调用 `drag_source_system_ended()`。
 
 ```gdscript
 cef_texture.drag_source_ended(drop_position, DragOperation.COPY)
 ```
 
 ### `drag_source_system_ended()`
 
-通知 CEF 系统拖动操作已结束。在浏览器发起的拖动后用于清理。
+通知 CEF 浏览器发起的拖动已取消，或没有放置结果就结束。此方法会以 `DragOperation.NONE` 完成浏览器拖动操作。
 
 ```gdscript
 cef_texture.drag_source_system_ended()