diff --git a/docs/resources/ui/widgets/built-in-widgets/draggable.md b/docs/resources/ui/widgets/built-in-widgets/draggable.md index 0a403af2..f3e4b71c 100644 --- a/docs/resources/ui/widgets/built-in-widgets/draggable.md +++ b/docs/resources/ui/widgets/built-in-widgets/draggable.md @@ -14,19 +14,37 @@ For example, in a shopping cart app, you could use these widgets together to all Let's see how to add a drag-and-drop functionality by building an example that allows users to put only plants on the shelf. Here's how it looks: -
- +
+ +
+

The steps to build such an example are as follows: -1. [Create page state variable](#1-create-page-state-variable) -2. [Add Draggable widgets](#2-add-draggable-widgets) -3. [Add DragTarget widget](#3-add-dragtarget-widget) -4. [Get notified on drag events](#4-get-notified-on-drag-events) - ### 1. Create page state variable In this example, we have two images of a shelf: one with empty space for one plant and another @@ -57,10 +75,42 @@ In this example, the draggable items are a plant, a spoon, and a football. Let's 2. Inside the **Draggable** widget, you can add any widget as a child widget. For this example, we use the **Image** widget. 3. To add data to draggable widgets, select the **Draggable widget > Properties Panel > Draggable Properties >** specify the **Type** of the data and its **Value**. -
+
+ +
+

+:::info +The Draggable widget also provides you with various drag events (as [**Action Triggers**](../../../control-flow/functions/action-triggers.md)) that you might want to use to customize the drag experience. These include: +- **On Drag Started**: Gets triggered when the user initiates a drag operation. +- **On Drag Update**: Gets triggered when the drag is currently in progress, allowing you to track its movement or update other UI elements accordingly. +- **On Drag Completed**: Gets triggered when the user successfully drags and drops the widget into [**DragTarget**](#3-add-dragtarget-widget) widget. +- **On Drag Cancelled**: Gets triggered when the drag operation is aborted, such as when the user releases the widget outside a **DragTarget** or the DragTarget rejects the widget. +- **On Drag End**: Gets triggered when the drag operation finishes, regardless of whether it was completed or cancelled. +::: ### 3. Add DragTarget widget @@ -72,10 +122,33 @@ Let's see how to add DragTarget widget: 2. Inside the **DragTarget** widget, add a [**Container**](../../widgets/basic-widgets/container.md) widget, preferably of the same size as the image, and set its background color to transparent. This will serve as the drop zone for draggable items. 3. Now, you need to specify the type of data this target will receive. To do so select the **DragTarget widget > Properties Panel > Draggable Properties >** specify the **Type** of the data. This is crucial for ensuring that only the correct items can be dropped on the target. -
- +
+ +
+

### 4. Get notified on drag events @@ -106,19 +179,35 @@ and click **Open**. This will open an **Action Flow Editor** in a new popup wind 5. From the **set variable** menu, select **Drag Target > Dragged Data**. This captures the data of the draggable item that we added in [step 2](#2-add-draggable-widgets). 8. Check if the captured data matches the expected item, i.e., plant. 11. In the **TRUE** branch, you can add a [snackbar message](../../pages/page-elements.md#snackbar) and [update](../../pages/page-lifecycle.md#page-state) the `isShelfFull` variable to True. This will create an effect like the user has actually dragged and dropped the item onto the shelf. -3. Now, select the **On Drag Exit** andadd an action to [update](../../pages/page-lifecycle.md#page-state) the `isShelfFull` variable to False. This ensures that if the user decides not to drop the item and moves it away, the shelf image reverts to the empty one. - -
-On Drag Accept -
+
+ +
+

-
- -
-On Drag Exit +3. Now, select the **On Drag Exit** andadd an action to [update](../../pages/page-lifecycle.md#page-state) the `isShelfFull` variable to False. This ensures that if the user decides not to drop the item and moves it away, the shelf image reverts to the empty one. -![img_2.png](imgs/img_2.png) -
\ No newline at end of file + ![img_2.png](imgs/img_2.png) \ No newline at end of file