From 27dd00cc9135f5e42dad16104f126304fe74248a Mon Sep 17 00:00:00 2001
From: Giang <77535212+nvglucifer@users.noreply.github.com>
Date: Fri, 13 Dec 2024 20:03:19 +0700
Subject: [PATCH] docs: Update item-callbacks.rst - drag and drop callback
 (#2430)

* docs: Update item-callbacks.rst - drag and drop callback

Add docs for drag and drop callback (and drag payload)

* docs: Update item-callbacks.rst - drag and drop callback

Add docs for drag and drop callback (and drag payload)

* Update item-callbacks.rst - payload_type being optional

Modify a point about payload_type being optional.
---
 docs/source/documentation/item-callbacks.rst | 52 ++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/docs/source/documentation/item-callbacks.rst b/docs/source/documentation/item-callbacks.rst
index 80eb65f76..052ccf109 100644
--- a/docs/source/documentation/item-callbacks.rst
+++ b/docs/source/documentation/item-callbacks.rst
@@ -88,6 +88,58 @@ User data can be any python object.
     dpg.start_dearpygui()
     dpg.destroy_context()
 
+Drag and Drop callback (and drag payload)
+-----------------------------------------
+
+Drag/Drop callback receive its **app_data** from drag_payload's **drag_data**.
+
+**user_data** (optional) can be specified in both **drag payload** and **target drop item** for further use in Drag/Drop callback.
+
+**payload_type** (optional) can be any string you like. If not specified, **payload_type**'s default value is '$$DPG_PAYLOAD'. 
+
+For drop callback to work, **payload_type** must be specified the same in both **drag payload** and **target drop item**.
+
+.. code-block:: python
+
+    import dearpygui.dearpygui as dpg
+    dpg.create_context()
+    
+    def drag_cb(sender, app_data, user_data):
+        # sender is btn_drag
+        # app_data is btn_drag (value from drag_data)
+        # do some configure(drawing_item), animation
+        ...
+    
+    def drop_cb(sender, app_data, user_data):
+        # sender is group, app_data is btn_drag
+        dpg.move_item(app_data, parent=sender)
+    
+    with dpg.window():
+        with dpg.group(horizontal=True):
+    
+            with dpg.group(width=300, drop_callback=drop_cb, payload_type="int"):  # user_data=??
+                dpg.add_text("Group left")
+                dpg.add_button(label="not drag this")
+    
+            with dpg.group(width=300, drop_callback=drop_cb, payload_type="int"):
+                dpg.add_text("Group right")
+                dpg.add_button(label="not drag this")
+                btn_drag = dpg.add_button(label="drag me to another group then drop", drag_callback=drag_cb)
+    
+            with dpg.drag_payload(parent=btn_drag, drag_data=btn_drag, payload_type="int"):
+                dpg.add_text("dragging a button")
+    
+                # parent=btn_drag     --> this playload will appear if dragged from the btn_drag
+                # drag_data=btn_drag  --> btn_drag will be app_data in the above drag_cb and drop_cb
+                # payload_type="int"  --> btn_drag is an int, specified in this playload and drop target - two group above
+                
+    dpg.create_viewport()
+    dpg.setup_dearpygui()
+    dpg.show_viewport()
+    while dpg.is_dearpygui_running():
+        dpg.render_dearpygui_frame()
+    dpg.destroy_context()
+
 Debugging Callbacks (new in 1.2)
 --------------------------------