You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* docs: document DragSource#setDragImage
Adds chapter in DragSource article explaining new DnD API to set a drag image component.
RelatedTo: vaadin/flow#6793
* Initial edits of added section.
* Additional minor edits and formatting changes.
---------
Co-authored-by: russelljtdyer <6652767+russelljtdyer@users.noreply.github.com>
Copy file name to clipboardExpand all lines: articles/flow/create-ui/dnd/drag-source.adoc
+46-28Lines changed: 46 additions & 28 deletions
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
---
2
2
title: Drag Source
3
-
description: Make any component draggable by the user and configure the drag operation.
3
+
description: Making any component draggable, and configuring the drag operation.
4
4
order: 20
5
5
---
6
6
@@ -38,10 +38,10 @@ When a component is set draggable on the server side, the `draggable` attribute
38
38
}
39
39
----
40
40
41
-
== Exposing the Drag Source API on your Component
42
41
43
-
As the [interfacename]`DragSource` is an interface, it can also be used as a "mix-in interface", which gives an easy way to add its API to your custom component.
44
-
This useful when you want to reuse the component in many places for drag operations.
42
+
== Exposing Drag Source API to a Component
43
+
44
+
As the [interfacename]`DragSource` is an interface, it can also be used as a "mix-in interface", which gives an easy way to add its API to your custom component. This useful when you want to reuse the component in many places for drag operations.
45
45
46
46
[source,java]
47
47
----
@@ -54,12 +54,12 @@ public class CardComponent extends Div implements DragSource<CardComponent>, Has
54
54
}
55
55
----
56
56
57
+
57
58
[drag.data]
58
-
== Assigning Server-Side Data to the Drag Source
59
+
== Assigning Server-Side Data to Drag Source
59
60
60
61
It's possible to set any Java object as the server-side drag data for the drag
61
-
source.
62
-
This data is provided on the [classname]`DropEvent` when the drop occurs on a valid drop target, if it's inside the same UI (browser window / tab) as the drag source component.
62
+
source. This data is provided on the [classname]`DropEvent` when the drop occurs on a valid drop target, if it's inside the same UI (browser window / tab) as the drag source component.
63
63
64
64
[source,java]
65
65
----
@@ -75,12 +75,10 @@ The data isn't sent to the browser, as it's stored in the component instance as
75
75
76
76
It isn't possible to configure the client-side drag data, the `dataTransfer` object, from the server side.
77
77
78
-
== Drag Start and End Events
79
78
80
-
The [interfacename]`DragSource` provides a way to react when the user starts and stops dragging a component.
81
-
The [classname]`DragStartEvent` is fired when the drag starts in the browser, which means that you can't cancel the drag.
82
-
You should avoid doing any heavy synchronous processing there, since this blocks the user from dragging the component further in the browser.
83
-
This has a negative effect on the UX.
79
+
== Drag Start & End Events
80
+
81
+
The [interfacename]`DragSource` provides a way to react when the user starts and stops dragging a component. The [classname]`DragStartEvent` is fired when the drag starts in the browser, which means that you can't cancel the drag. You should avoid doing any heavy synchronous processing there, since this blocks the user from dragging the component further in the browser. This has a negative effect on the UX.
When the user stops dragging the component by either dropping it or by canceling the drag with, for example, the escape key, the [classname]`DragEndEvent` is fired.
101
-
The [methodname]`isSuccessful()` method returns `true` if the drop occurred on a drop target that accepted the drop, but only for Chrome and Firefox (read the note after the sample).
98
+
When the user stops dragging the component by either dropping it or by canceling the drag with, for example, the escape key, the [classname]`DragEndEvent` is fired. The [methodname]`isSuccessful()` method returns `true` if the drop occurred on a drop target that accepted the drop, but only for Chrome and Firefox (read the note after the sample).
Edge and Safari don't report whether the drop occurred successfully or not in the [classname]`DragEnd` event.
118
-
You need to take this into account if your users are using any of these browsers, and do any logic in the [classname]`DropEvent` handler of the [classname]`DropTarget` instead.
119
-
For Chrome and Firefox, it works correctly.
114
+
Edge and Safari don't report whether the drop occurred successfully or not in the [classname]`DragEnd` event. You need to take this into account if your users are using any of these browsers, and do any logic in the [classname]`DropEvent` handler of the [classname]`DropTarget` instead. For Chrome and Firefox, it works correctly.
120
115
121
-
=== The Effect Allowed and Drop Effect
122
116
123
-
It's possible to customize the `effectAllowed` for the drag source.
124
-
This has an effect on what the browser visually presents to the user and should match what's set in the drop target as the `dropEffect`.
125
-
The [classname]`DragEndEvent` reports the `dropEffect` for the drop event.
117
+
=== Effect Allowed & Drop Effect
118
+
119
+
It's possible to customize the `effectAllowed` for the drag source. This has an effect on what the browser visually presents to the user and should match what's set in the drop target as the `dropEffect`. The [classname]`DragEndEvent` reports the `dropEffect` for the drop event.
126
120
127
121
The value is determined in priority order by:
128
122
129
-
* the desired action `dropEffect` set by the drop target;
130
-
* the `effectAllowed` set for the drag source;
131
-
* the modifier keys the user presses and holds when dropping.
123
+
- the desired action `dropEffect` set by the drop target;
124
+
- the `effectAllowed` set for the drag source;
125
+
- the modifier keys the user presses and holds when dropping.
126
+
127
+
When the drop effect is `MOVE`, you should move / remove the drag source component from its original location. When the drop effect is `NONE`, the drop didn't occur and [methodname]`dropEvent.isSuccessful()` returns `false`.
132
128
133
-
When the drop effect is `MOVE`, you should move / remove the drag source component from its original location.
134
-
When the drop effect is `NONE`, the drop didn't occur and [methodname]`dropEvent.isSuccessful()` returns `false`.
135
129
136
130
=== Customizing the Draggable Element
137
131
@@ -159,7 +153,31 @@ public class DraggableRouteItem extends RouteItem implements DragSource<RouteIte
159
153
----
160
154
161
155
Changing the draggable element also changes the drag image that the browser shows under the cursor.
162
-
HTML 5 has an API for setting a custom drag image element, but it isn't yet available from the server-side API, because it works unreliably in some browsers (Edge / Safari).
163
156
164
157
158
+
=== [since:com.vaadin:vaadin@V24.6]#Drag-Image#
159
+
160
+
With the [interfacename]`DragSource` interface's [methodname]`setDragImage` methods, it's possible to customize a drag-image that the browser shows under the cursor when dragging a component.
161
+
162
+
<<../../application/resources#the-image-component, [classname]`Image`>> is applied in the next drag start event in the browser. The [classname]`Image` component is fully supported as a drag image. Other components can be used as well, but the support may vary between browsers. If a given component is a visible element in the viewport, the browser can show it as a drag image.
163
+
164
+
[source,java]
165
+
----
166
+
// continuing from the previous example
167
+
CardComponent card = new CardComponent();
168
+
169
+
card.setDragImage(new Image("/cards/ace_of_spades.png", "Ace of Spades"));
170
+
----
171
+
172
+
The [classname]`Image` component supports <<../../advanced/dynamic-content#using-streamresource, StreamResource>> to generate the image, dynamically.
173
+
174
+
Any optional coordinates define the offset of the pointer location from the top left corner of the image. The following example sets the x offset to 20 pixels and the y offset to 0 pixels:
175
+
176
+
[source,java]
177
+
----
178
+
card.setDragImage(new Image("/cards/queen_of_hearts.png", "Queen of Hearts"), 20, 0)
179
+
----
180
+
181
+
For more information about the drag image, see link:https://developer.mozilla.org/en-US/docs/Web/API/DataTransfer/setDragImage[HTML5 drag and drop API].
0 commit comments