1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
---
title: Drag and Drop
order: 12
layout: page
---
[[advanced.dragndrop]]
= Drag and Drop
((("Drag and Drop", id="term.advanced.dragndrop", range="startofrange")))
IMPORTANT: This feature is currently being developed and only available in the Framework 8.1 prerelease versions, starting from 8.1.0.alpha1.
Dragging an object from one location to another by grabbing it with mouse,
holding the mouse button pressed, and then releasing the button to "drop" it to
the other location is a common way to move, copy, or associate objects. For
example, most operating systems allow dragging and dropping files between
folders or dragging a document on a program to open it. Framework version 8.1 adds support for https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API[HTML5 drag and drop] features. This makes it possible to set components as drag sources that user can drag and drop, or to set them as drop targets to drop things on.
== Drag Source
Any component can be made a drag source that has a set of data that is transferred when it is dragged and dropped.
To make a component a drag source, you apply the [classname]#DragSourceExtension# to it. Then you can define the data to transfer, and the allowed drag effect.
[source, java]
----
Label draggableLabel = new Label("You can grab and drag me");
DragSourceExtension<Label> dragSource = new DragSourceExtension<>(draggableLabel);
// set the allowed effect
dragSource.setEffectAllowed(EffectAllowed.MOVE);
// set the data to transfer
dragSource.setTransferData("text/plain", "hello receiver");
----
The __effect allowed__ specifies the allowed effects that must match the __drop effect__ of the drop target. If these don't match, the drop event is never fired on the target. If multiple effects are allowed, the user can use the modifier keys to switch between the desired effects. The default effect and the modifier keys are system and browser dependent.
The __transfer data__ is a set of data, that the drop target will receive in the __drop event__. The first parameter given is the type of the data, and the second parameter is the actual data as string. The type parameter thus acts as a key for the actual data. For more information about the
type parameter, see https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API/Recommended_drag_types[MDN recommendations].
The [classname]#DragStartEvent# is fired when the drag has started, and the [classname]#DragEndEvent# event when the drag has ended, either in a drop or a cancel.
[source, java]
----
dragSource.addDragStartListener(event ->
event.getComponent().addStyleName("dragged")
);
dragSource.addDragEndListener(event ->
event.getComponent().removeStyleName("dragged")
);
----
[NOTE]
====
The browsers allow the user to select and drag and drop text, which may cause some issues when trying to drag a component that has text. You can fix this by setting the following style rule to the drag source component to prevent dragging of the text instead of the whole component.
[source, css]
----
user-select: none;
----
====
[[advanced.dragndrop.drophandler]]
== Drop Target
The drag operations end when the mouse button is released on a valid drop target. It is then up to the target to react to the drop event and the data associated with the drag, set by the drag source.
To make a component be a drop target, you apply the [classname]#DropTargetExtension# to it. The extension allows you to control when the drop is acceptable and then react to the drop event.
[source, java]
----
VerticalLayout dropTargetLayout = new VerticalLayout();
dropTargetLayout.setCaption("Drop things inside me");
dropTargetLayout.addStyleName(ValoTheme.LAYOUT_CARD);
// make the layout accept drops
DropTargetExtension<VerticalLayout> dropTarget = new DropTargetExtension<>(dropTargetLayout);
// the drop effect must match the allowed effect in the drag source for a successful drop
dropTarget.setDropEffect(DropEffect.MOVE);
// catch the drops
dropTarget.addDropListener(event -> {
// if the drag source is in the same UI as the target
Optional<AbstractComponent> dragSource = event.getDragSourceComponent();
if (dragSource.isPresent() && dragSource.get() instanceof Label) {
// move the label to the layout
dropTargetLayout.addComponent(dragSource.get());
// get possible transfer data
// NOTE that "text" is same as "text/plain" from drag source data,
// see the HTML5 standard for more info
String message = event.getTransferData("text");
Notification.show("DropEvent with data transfer: "+ message);
}
});
----
When data is dragged over a drop target, the __v-drag-over__ class name is applied to the root element of the drop target component automatically.
=== Controlling When The Drop is Acceptable
The __drop effect__ allows you to specify the desired drop effect, and for a succesful drop it must match the allowed effect that has been set for the drag source. Note that you can allow multiple effects, and that you should not rely on the default effect since it may vary between browsers.
The __drag over criteria__ allows you determine whether the current drag source is allowed as a drop target, when the source is moved on top of the target. It is a script that is executed always when the `dragover` event is fired for the first time for this source, and returning `false` will prevent showing any drop effect. The script gets the `dragover` event as a parameter named `event`.
The __drop criteria__ is similar to __drag over criteria__, but it is executed when the user has dropped the data by releasing the mouse button. The script gets the `drop` event as a parameter named `event`. Returning `false` will prevent the drop and no drop event is fired on the server side.
////
TODO Add an example of drag over criteria and drop criteria
////
===
////
TODO add back when supported with new API ?
[[advanced.dragndrop.external]]
== Dragging Files from Outside the Browser
The [classname]#DropTargetExtension# allows dragging files from outside the
browser and dropping them on a target component.
Dropped files are automatically uploaded to the application and can be acquired from the
wrapper with [methodname]#getFiles()#. The files are represented as
[classname]#Html5File# objects as defined in the inner class. You can define an
upload [classname]#Receiver# to receive the content of a file to an
[classname]#OutputStream#.
Dragging and dropping files to browser is supported in HTML 5 and requires a
compatible browser, such as Mozilla Firefox 3.6 or newer.
////
(((range="endofrange", startref="term.advanced.dragndrop")))
|
