Skip to content

Commit fddefda

Browse files
tltvrusselljtdyer
andauthored
docs: document DragSource#setDragImage (vaadin#3761)
* 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>
1 parent 0a62efc commit fddefda

File tree

1 file changed

+46
-28
lines changed

1 file changed

+46
-28
lines changed

articles/flow/create-ui/dnd/drag-source.adoc

Lines changed: 46 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
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.
44
order: 20
55
---
66

@@ -38,10 +38,10 @@ When a component is set draggable on the server side, the `draggable` attribute
3838
}
3939
----
4040

41-
== Exposing the Drag Source API on your Component
4241

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.
4545

4646
[source,java]
4747
----
@@ -54,12 +54,12 @@ public class CardComponent extends Div implements DragSource<CardComponent>, Has
5454
}
5555
----
5656

57+
5758
[drag.data]
58-
== Assigning Server-Side Data to the Drag Source
59+
== Assigning Server-Side Data to Drag Source
5960

6061
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.
6363

6464
[source,java]
6565
----
@@ -75,12 +75,10 @@ The data isn't sent to the browser, as it's stored in the component instance as
7575

7676
It isn't possible to configure the client-side drag data, the `dataTransfer` object, from the server side.
7777

78-
== Drag Start and End Events
7978

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.
8482

8583
[source,java]
8684
----
@@ -97,8 +95,7 @@ card1.addDragStartListener(event -> {
9795
});
9896
----
9997

100-
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).
10299

103100
[source,java]
104101
----
@@ -112,26 +109,23 @@ card1.addDragEndListener(event -> {
112109
});
113110
----
114111

115-
.Handling drag end in Edge and Safari
112+
.Handling Drag End in Edge & Safari
116113
[NOTE]
117-
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.
120115

121-
=== The Effect Allowed and Drop Effect
122116

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.
126120

127121
The value is determined in priority order by:
128122

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`.
132128

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`.
135129

136130
=== Customizing the Draggable Element
137131

@@ -159,7 +153,31 @@ public class DraggableRouteItem extends RouteItem implements DragSource<RouteIte
159153
----
160154

161155
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).
163156

164157

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].
182+
165183
[discussion-id]`4FFD51BA-4736-44BD-8FCF-0E534A19FB8D`

0 commit comments

Comments
 (0)