LCL Drag Drop: what changed

Old	New		Line
1		-	~~<h2>~~
2		-
3	1		DoDi's Guide to Dragging, Dropping and Docking
4		-
5		-	~~</h2>~~
6	2
7	3		Controls in a GUI can be grabbed with the mouse, dragged to other locations, and dropped onto other controls or onto the desktop. When the dragged control is moved to a different location, the operation is called [[LCL Drag Dock\|"docking"]]. Otherwise the source and target control can exchange information or interact in any other way, what's called a "drag-drop" operation.
8	4
9	5		But all that does not work by itself, an application must set up the allowed operations so that the LCL knows what to do with every control in a GUI. Sophisticated operations require further code for managing the visual feedback to the application user, and what will happen when the dragged control finally is dropped.
10	6
11	7		For simple docking support in entire applications you can use either [[EasyDockingManager]] or [[Anchor Docking]], that reduces the required adaptations to a minimum.
12	8
13	9		## Drag Drop
14	10
15	11		This is the simple and originally only dragging action. The players are:
16	12
17	13		- A draggable source control in the GUI
18	14		- A drag object, derived from TDragObject
19	15		- Helper functions
20	16		- Events
21	17
22	18		Now let's have a look at how these are working together.
23	19
24	20		### The Drag Source
25	21
26	22		A control can be made draggable by setting its DragMode property to dmAutomatic. When the user presses the left mouse button over such a control, the mouse pointer changes into an dragging indicator until the user releases the button, or cancels the operation by pressing the Escape key. The indicator now follows the mouse movements and changes its shape, according to what will happen when the control is dropped in the current location.
27	23
28	24		Dragging also can be started in code, by calling SourceControl.BeginDrag. In either case the helper procedure DragManager.DragStart is called to start dragging. The DragManager is a global instance implementing the actual dragging. It is initialized with the default TDragManagerDefault and can be replaced by the programmer (You). Depending on the control's DragKind a drag or a dock operation is started. The source control triggers an OnStartDrag event, where the programmer can provide a custom drag object. If no such object is provided, a default object (TDragControlObject or TDragDockObject) is created. Internal data structures for visual feedback and more are initialized.
29	25
30	26		### The Drag Object (TDragObject defined in unit controls)
31	27
32	28		A drag object receives all user input while dragging. In the default implementation it reacts by calling either DragMove or finally DragStop.
33	29
34	30		The drag object also is responsible for the visual feedback:
35	31
36	32		- GetDragCursor returns the mouse pointer shape.
37	33		- GetDragImages returns a list of drag images, attachable to the mouse pointer.
38	34		- ShowDragImage and HideDragImage implement the visual feedback.
39	35
40	36		The EndDrag method notifies the source control when dragging stops. In case of a cancel'd operation it invokes SourceControl.DragCanceled, followed by SourceControl.DoEndDrag in either case, which raises an OnEndDrag event.
41	37
42	38		### Events
43	39
44	40		#### OnStartDrag/Dock
45	41
46	42		This event occurs when the operation starts. The handler can provide a custom TDragObject or TDragDockObject for the operation.
47	43
48	44		#### OnDrag/DockOver
49	45
50	46		This event notifies a possible target, when an object is dragged over it. The handler can signal to accept or reject a drop.
51	47
52	48		The event signals not only mouse moves, but also when the mouse enters or leaves a target control.
53	49
54	50		An OnDockOver event occurs on the DockSite, not on the target control under the mouse. The handler can signal to deny an drop, and can adjust the visual feedback. The event occurs when the mouse enters or leaves a control, and with every single movement of the mouse.
55	51
56	52		#### OnDrag/DockDrop
57	53
58	54		This event notifies the target control of the end of a drag operation.
59	55
60	56		#### OnEndDrag/Dock
61	57
62	58		This event notifies the source control of the end of a drag operation.
63	59
64	60		## Major Shortcomings
65	61
66	62		- The same flaws as Delphi's VCL.
67	63		- No LCL framework (cross-platform) support for dragging from an LCL application to any other application. For this to work, LCL needs support for the XDND protocol under X11, OLE Drag-n-Drop support under Windows and Mac Drag Manager under macOS.
68	64		- No LCL framework (cross-platform) support for receiving drops inside an LCL application from another application (desktop, file manager, etc). The OnDragDrop event handler always expects the Source of the drop to come through as a TObject descendant which will not be the case when dragging an object from another application to a LCL application.
69	65
70	66		## Delphi
71	67
72	68		### Drag Drop
73	69
74	70		This is the simple and originally only dragging action. The players are:
75	71
76	72		- A draggable source control in the GUI
77	73		- A drag object, derived from TDragObject
78	74		- Helper functions
79	75		- Events
80	76
81	77		Now let's have a look at how these are working together, based on the original Delphi implementation for clarity. The LCL implementation is somewhat different in the use of helper objects, details will be discussed later.
82	78
83	79		#### The Drag Source
84	80
85	81		A control can be made draggable by setting its DragMode property to dmAutomatic. When the user presses the left mouse button over such a control, the mouse pointer changes into an dragging indicator until the user releases the button, or cancels the operation by pressing the Escape key. The indicator now follows the mouse movements and changes its shape, according to what will happen when the control is dropped in the current location.
86	82
87	83		Dragging also can be started in code, by calling source.BeginDrag. In either case the helper procedure DragInitControl is called to start dragging. The source control raises an StartDrag event, where the application can provide a custom drag object. If no such object is provided, a default object is created. Internal data structures for visual feedback and more are initialized. Then DragTo is called to show that dragging has started.
88	84
89	85		#### The Drag Object (TDragObject defined in unit controls)
90	86
91	87		A drag object receives all user input while dragging. In the default implementation it reacts by calling either DragTo or finally DragDone.
92	88
93	89		The drag object also is responsible for the visual feedback:
94	90
95	91		- GetDragCursor returns the mouse pointer shape.
96	92		- GetDragImages returns a list of drag images, to be attached to the mouse pointer.
97	93		- ShowDragImage and HideDragImage implement the visual feedback.
98	94
99	95		The Finished method notifies the source control when dragging stops. In case of a cancel'd operation it invokes source.DragCanceled, followed by source.DoEndDrag in either case, which raises an EndDrag event.
100	96
101	97		#### LCL Modifications
102	98
103	99		The current LCL implementation has removed input processing from the drag object, so that the application can no more customize the UI. And the LCL implementation is far from being okay :-(
104	100
105	101		Also the drag object is bypassed in the presentation of the visual feedback.
106	102
107	103		### Helper Functions
108	104
109	105		Helper functions primarily allow for access to protected properties and methods of the controls and other classes, from outside the Controls unit. They also can perform common tasks, and can encapsulate platform specific and other implementation details.
110	106
111	107		#### General Helpers
112	108
113	109		DragTo (Delphi only, not present in LCL) determines the current drag target, sends notifications to the involved controls, and manages the visual feedback. It also handles the delayed start of a dragging operation, i.e. can wait for the mouse moving away far enough from the starting point.
114	110
115	111		DragDone (Delphi only, not present in LCL) terminates dragging, either with a drop or cancel of the operation.
116	112
117	113		CancelDrag (Delphi only, do not confuse with the LCL global procedure CancelDrag) is protected against false calls, otherwise it defers further actions to DragDone.
118	114
119	115		#### Special Helpers
120	116
121	117		Some more public helper procedures exist, which are undocumented in Delphi and are not required for customized dragging operations.
122	118
123	119		DragFindWindow searches for a drag target window (platform specific).
124	120
125	121		DragInit initializes the internal management, like mouse capture, and the visual feedback.
126	122
127	123		DragInitControl creates the drag object, then calls DragInit.
128	124
129	125		SetCaptureControl handles the mouse capture.
130	126
131	127		### Events
132	128
133	129		#### OnStartDrag/Dock
134	130
135	131		This event occurs when the operation starts. The handler can provide a custom DockObject for the operation.
136	132
137	133		#### OnDrag/DockOver
138	134
139	135		This event notifies a possible target, when an object is dragged over it. The handler can signal to accept or reject an drop.
140	136
141	137		The event signals not only mouse moves, but also when the mouse enters or leaves a target control.
142	138
143	139		An OnDockOver event occurs on the DockSite, not on the target control under the mouse. The handler can signal to deny an drop, and can adjust the visual feedback. The event occurs when the mouse enters or leaves a control, and with every single movement of the mouse.
144	140
145	141		#### OnDrag/DockDrop
146	142
147	143		This event notifies the target control of the end of a drag operation.
148	144
149	145		#### OnEndDrag/Dock
150	146
151	147		This event notifies the source control of the end of a drag operation.
152	148
153	149		### Docking specific Events
154	150
155	151		(this section should be moved to docking topic)
156	152
157	153		#### OnGetSiteInfo
158	154
159	155		This event occurs during the search for a qualifying dock site. Multiple dock sites can overlap each other, reside in overlapping windows, or can be invisible. Every candidate must supply an influence rectangle (catching area), and can signal to reject an drop. The drag manager selects the most appropriate dock site as the target for subsequent OnDockOver events.
160	156
161	157		#### OnUnDock
162	158
163	159		This event occurs when the dragged control has to be removed from its host dock site.
164	160
165	161		It's unclear what should happen when the handler denies to undock the control.
166	162
167	163		## LCL Implementation
168	164
169	165		The Delphi implementation of dragging has many flaws, in detail with regards to docking. Until now nobody seems to understand the details of the Delphi dragging model, most code was modeled after the VCL and consequently implements exactly the same misbehaviour. This section, and more important the docking specific page, shall shed some light on the dragging model in general and the severe design and implementation flaws in the Delphi implementation.
170	166
171	167		The current LCL implementation uses a DragManager object and drag/dock performers instead of helper functions. While the Delphi model must be provided for compatibility reasons, the introduction of a DragManager class and object (singleton) allows for the implementation of an alternative drag manager, with improved behaviour, and allows an application to select the most appropriate manager.
172	168
173	169		### DragManager
174	170
175	171		This object handles the captured input, provides helper methods, and stores dragging and docking parameters.
176	172
177	173		It's questionable whether the drag object shall not be allowed to handle user input. It makes the system safer, but disallows applications to extend the user interface for specific dragging operations.
178	174
179	175		The helper methods require different calls, but this is harmless as long as they are only called from LCL components.
180	176
181	177		More critical is the storage of dragging parameters in the DragManager object, which vanish when a different drag manager is installed. This is fatal in case of the list of registered dock sites :-(
182	178
183	179		### Drag Performers
184	180
185	181		The internal use of different classes for dragging and docking is okay in so far, as the procedures differ significantly between drag-drop and drag-dock operations. Nonetheless common actions should use common code, e.g. inherited from the common base class.
186	182
187	183		## Delphi Message Sequence Chart or UML Sequence Diagram
188	184
189	185		Provided by Tom Verhoeff
190	186
191	187		Something along the lines (this is for Delphi; view with monospaced font):
192	188
193	189		` Main Drag (Optional) Drag`\
194	190		` User Event Source Drag Target`\
195	191		` (Mouse) Loop Control Object Control`\
196	192		` = = = =`\
197	193		` \| \| \| \|`\
198	194		` 1\|--MouseDown--->\| \| \|`\
199	195		` \| 2#--OnMouseDown->\| \|`\
200	196		` \| \| 3# \|`\
201	197		` \| 4#<-BeginDrag()--# \|`\
202	198		` \| # # \|`\
203	199		` \| \| \| \|`\
204	200		` \| 5#--OnStartDrag->\| \|`\
205	201		` \| # 6#----Create---->= \|`\
206	202		` \| \| # \| \|`\
207	203		` 7\|--MouseMove--->\| \| \| \|`\
208	204		` \| 8#-----------------------------------OnDragOver->\|`\
209	205		` \| # \| \| 9#`\
210	206		` \| # \| \| #`\
211	207		` \| \| \| \| \|`\
212	208		` 10\|---MouseUp---->\| \| \| \|`\
213	209		` \| 11#-----------------------------------OnDragDrop->\|`\
214	210		` \| # \| \| 12#`\
215	211		` \| # \| \| #`\
216	212		` \| #---OnEndDrag-->\| \| \|`\
217	213		` \| \| 13#----Destroy--->= \|`\
218	214		` \| \| \| \|`
219	215
220	216		The DragObject is optional. There could be multiple candidate targets. The Main Event Loop determines which event to send to which object, depending on the user action, the cursor location, and the current state of the GUI.
221	217
222	218		4 somehow triggers 5 (there is a delay depending on the Boolean parameter Immediate to BeginDrag).
223	219
224	220		6 determines the location of the MouseDown and may use this to decide on what gets dragged (through GetCursorPos, ScreenToClient, MouseToCell). It can call SetDragImage to visualize a thing being dragged.
225	221
226	222		The chain 7, 8, 9 can occur repeatedly; 9 indicates acceptability of a drop at this target via the Boolean var parameter Accepted.
227	223
228	224		12 is called only if the immediately preceding OnDragOver of this target returned Accepted = True; i.e. Accepted is a precondition of 12.
229	225
230	226		13 receives the parameter Target to know where the drop was accepted; if Target = nil, then the drop was cancelled by the user (MouseUp at an unacceptable location), and OnDragDrop was not performed; if Target \<\> nil, then OnDragDrop was already performed at the Target. The work associated with an actual drop is thus divided over the OnDragDrop (for actions at the target) and OnEndDrag (for actions at the source). Since a Drag Object needs to be destroyed, independent of whether the drop was successful or canceled, it is best to call Free (or Destroy) only in the OnEndDrag handler.
231	227
232	228		Only one drag can be active at any moment; it either ends in a drop or is canceled.
233	229
234	230		There are various other things to be included, but this is the fundamental part. (Maybe also see [Delphi-Central](http://www.delphi-central.com/drag.aspx) or ["Implementing drag-and-drop in controls"](http://www.podgoretsky.com/ftp/Docs/Delphi/D5/dg/controls.html).)
235	231
236	232		I hope this is helpful. Tom
237	233
238	234		## See also
239	235
240	236		- [[Drag and Drop sample]]
241	237
242	238		---
243	239		From the Free Pascal wiki, page "LCL Drag Drop", as it stood on 2023-12-13 after a change by Coz, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

3

1

DoDi's Guide to Dragging, Dropping and Docking

6

2

7

3

Controls in a GUI can be grabbed with the mouse, dragged to other locations, and dropped onto other controls or onto the desktop. When the dragged control is moved to a different location, the operation is called [[LCL Drag Dock|"docking"]]. Otherwise the source and target control can exchange information or interact in any other way, what's called a "drag-drop" operation.

8

4

9

5

But all that does not work by itself, an application must set up the allowed operations so that the LCL knows what to do with every control in a GUI. Sophisticated operations require further code for managing the visual feedback to the application user, and what will happen when the dragged control finally is dropped.

10

6

11

7

For simple docking support in entire applications you can use either [[EasyDockingManager]] or [[Anchor Docking]], that reduces the required adaptations to a minimum.

12

8

13

9

## Drag Drop

14

10

15

11

This is the simple and originally only dragging action. The players are:

16

12

17

13

- A draggable source control in the GUI

18

14

- A drag object, derived from TDragObject

19

15

- Helper functions

20

16

- Events

21

17

22

18

Now let's have a look at how these are working together.

23

19

24

20

### The Drag Source

25

21

26

22

A control can be made draggable by setting its **DragMode** property to **dmAutomatic**. When the user presses the left mouse button over such a control, the mouse pointer changes into an dragging indicator until the user releases the button, or cancels the operation by pressing the Escape key. The indicator now follows the mouse movements and changes its shape, according to what will happen when the control is dropped in the current location.

27

23

28

24

Dragging also can be started in code, by calling *SourceControl*.**BeginDrag**. In either case the helper procedure *DragManager.DragStart* is called to start dragging. The **DragManager** is a global instance implementing the actual dragging. It is initialized with the default *TDragManagerDefault* and can be replaced by the programmer (You). Depending on the control's **DragKind** a drag or a dock operation is started. The source control triggers an **OnStartDrag** event, where the programmer can provide a custom drag object. If no such object is provided, a default object (*TDragControlObject* or *TDragDockObject*) is created. Internal data structures for visual feedback and more are initialized.

29

25

30

26

### The Drag Object (TDragObject defined in unit controls)

31

27

32

28

A drag object receives all user input while dragging. In the default implementation it reacts by calling either DragMove or finally DragStop.

33

29

34

30

The drag object also is responsible for the visual feedback:

35

31

36

32

- **GetDragCursor** returns the mouse pointer shape.

37

33

- **GetDragImages** returns a list of drag images, attachable to the mouse pointer.

38

34

- **ShowDragImage** and **HideDragImage** implement the visual feedback.

39

35

40

36

The **EndDrag** method notifies the source control when dragging stops. In case of a cancel'd operation it invokes *SourceControl*.**DragCanceled**, followed by *SourceControl*.**DoEndDrag** in either case, which raises an **OnEndDrag** event.

41

37

42

38

### Events

43

39

44

40

#### OnStartDrag/Dock

45

41

46

42

This event occurs when the operation starts. The handler can provide a custom TDragObject or TDragDockObject for the operation.

47

43

48

44

#### OnDrag/DockOver

49

45

50

46

This event notifies a possible target, when an object is dragged over it. The handler can signal to accept or reject a drop.

51

47

52

48

The event signals not only mouse moves, but also when the mouse enters or leaves a target control.

53

49

54

50

An OnDockOver event occurs on the DockSite, not on the target control under the mouse. The handler can signal to deny an drop, and can adjust the visual feedback. The event occurs when the mouse enters or leaves a control, and with every single movement of the mouse.

55

51

56

52

#### OnDrag/DockDrop

57

53

58

54

This event notifies the target control of the end of a drag operation.

59

55

60

56

#### OnEndDrag/Dock

61

57

62

58

This event notifies the source control of the end of a drag operation.

63

59

64

60

## Major Shortcomings

65

61

66

62

- The same flaws as Delphi's VCL.

67

63

- No LCL framework (cross-platform) support for dragging from an LCL application to any other application. For this to work, LCL needs support for the XDND protocol under X11, OLE Drag-n-Drop support under Windows and Mac Drag Manager under macOS.

68

64

- No LCL framework (cross-platform) support for receiving drops inside an LCL application from another application (desktop, file manager, etc). The OnDragDrop event handler always expects the Source of the drop to come through as a TObject descendant which will **not** be the case when dragging an object from another application to a LCL application.

69

65

70

66

## Delphi

71

67

72

68

### Drag Drop

73

69

74

70

This is the simple and originally only dragging action. The players are:

75

71

76

72

- A draggable source control in the GUI

77

73

- A drag object, derived from TDragObject

78

74

- Helper functions

79

75

- Events

80

76

81

77

Now let's have a look at how these are working together, based on the original Delphi implementation for clarity. The LCL implementation is somewhat different in the use of helper objects, details will be discussed later.

82

78

83

79

#### The Drag Source

84

80

85

81

A control can be made draggable by setting its **DragMode** property to **dmAutomatic**. When the user presses the left mouse button over such a control, the mouse pointer changes into an dragging indicator until the user releases the button, or cancels the operation by pressing the Escape key. The indicator now follows the mouse movements and changes its shape, according to what will happen when the control is dropped in the current location.

86

82

87

83

Dragging also can be started in code, by calling source.BeginDrag. In either case the helper procedure DragInitControl is called to start dragging. The source control raises an StartDrag event, where the application can provide a custom drag object. If no such object is provided, a default object is created. Internal data structures for visual feedback and more are initialized. Then DragTo is called to show that dragging has started.

88

84

89

85

#### The Drag Object (TDragObject defined in unit controls)

90

86

91

87

A drag object receives all user input while dragging. In the default implementation it reacts by calling either DragTo or finally DragDone.

92

88

93

89

The drag object also is responsible for the visual feedback:

94

90

95

91

- GetDragCursor returns the mouse pointer shape.

96

92

- GetDragImages returns a list of drag images, to be attached to the mouse pointer.

97

93

- ShowDragImage and HideDragImage implement the visual feedback.

98

94

99

95

The Finished method notifies the source control when dragging stops. In case of a cancel'd operation it invokes source.DragCanceled, followed by source.DoEndDrag in either case, which raises an EndDrag event.

100

96

101

97

#### LCL Modifications

102

98

103

99

The current LCL implementation has removed input processing from the drag object, so that the application can no more customize the UI. And the LCL implementation is far from being okay :-(

104

100

105

101

Also the drag object is bypassed in the presentation of the visual feedback.

106

102

107

103

### Helper Functions

108

104

109

105

Helper functions primarily allow for access to protected properties and methods of the controls and other classes, from outside the Controls unit. They also can perform common tasks, and can encapsulate platform specific and other implementation details.

110

106

111

107

#### General Helpers

112

108

113

109

**DragTo** (Delphi only, not present in LCL) determines the current drag target, sends notifications to the involved controls, and manages the visual feedback. It also handles the delayed start of a dragging operation, i.e. can wait for the mouse moving away far enough from the starting point.

114

110

115

111

**DragDone** (Delphi only, not present in LCL) terminates dragging, either with a drop or cancel of the operation.

116

112

117

113

**CancelDrag** (Delphi only, do not confuse with the LCL global procedure CancelDrag) is protected against false calls, otherwise it defers further actions to DragDone.

118

114

119

115

#### Special Helpers

120

116

121

117

Some more public helper procedures exist, which are undocumented in Delphi and are not required for customized dragging operations.

122

118

123

119

**DragFindWindow** searches for a drag target window (platform specific).

124

120

125

121

**DragInit** initializes the internal management, like mouse capture, and the visual feedback.

126

122

127

123

**DragInitControl** creates the drag object, then calls DragInit.

128

124

129

125

**SetCaptureControl** handles the mouse capture.

130

126

131

127

### Events

132

128

133

129

#### OnStartDrag/Dock

134

130

135

131

This event occurs when the operation starts. The handler can provide a custom DockObject for the operation.

136

132

137

133

#### OnDrag/DockOver

138

134

139

135

This event notifies a possible target, when an object is dragged over it. The handler can signal to accept or reject an drop.

140

136

141

137

The event signals not only mouse moves, but also when the mouse enters or leaves a target control.

142

138

143

139

An OnDockOver event occurs on the DockSite, not on the target control under the mouse. The handler can signal to deny an drop, and can adjust the visual feedback. The event occurs when the mouse enters or leaves a control, and with every single movement of the mouse.

144

140

145

141

#### OnDrag/DockDrop

146

142

147

143

This event notifies the target control of the end of a drag operation.

148

144

149

145

#### OnEndDrag/Dock

150

146

151

147

This event notifies the source control of the end of a drag operation.

152

148

153

149

### Docking specific Events

154

150

155

151

(this section should be moved to docking topic)

156

152

157

153

#### OnGetSiteInfo

158

154

159

155

This event occurs during the search for a qualifying dock site. Multiple dock sites can overlap each other, reside in overlapping windows, or can be invisible. Every candidate must supply an influence rectangle (catching area), and can signal to reject an drop. The drag manager selects the most appropriate dock site as the target for subsequent OnDockOver events.

160

156

161

157

#### OnUnDock

162

158

163

159

This event occurs when the dragged control has to be removed from its host dock site.

164

160

165

161

It's unclear what should happen when the handler denies to undock the control.

166

162

167

163

## LCL Implementation

168

164

169

165

The Delphi implementation of dragging has many flaws, in detail with regards to docking. Until now nobody seems to understand the details of the Delphi dragging model, most code was modeled after the VCL and consequently implements exactly the same misbehaviour. This section, and more important the docking specific page, shall shed some light on the dragging model in general and the severe design and implementation flaws in the Delphi implementation.

170

166

171

167

The current LCL implementation uses a DragManager object and drag/dock performers instead of helper functions. While the Delphi model must be provided for compatibility reasons, the introduction of a DragManager class and object (singleton) allows for the implementation of an alternative drag manager, with improved behaviour, and allows an application to select the most appropriate manager.

172

168

173

169

### DragManager

174

170

175

171

This object handles the captured input, provides helper methods, and stores dragging and docking parameters.

176

172

177

173

It's questionable whether the drag object shall not be allowed to handle user input. It makes the system safer, but disallows applications to extend the user interface for specific dragging operations.

178

174

179

175

The helper methods require different calls, but this is harmless as long as they are only called from LCL components.

180

176

181

177

More critical is the storage of dragging parameters in the DragManager object, which vanish when a different drag manager is installed. This is fatal in case of the list of registered dock sites :-(

182

178

183

179

### Drag Performers

184

180

185

181

The internal use of different classes for dragging and docking is okay in so far, as the procedures differ significantly between drag-drop and drag-dock operations. Nonetheless common actions should use common code, e.g. inherited from the common base class.

186

182

187

183

## Delphi Message Sequence Chart or UML Sequence Diagram

188

184

189

185

Provided by Tom Verhoeff

190

186

191

187

Something along the lines (this is for Delphi; view with monospaced font):

192

188

193

189

` Main Drag (Optional) Drag`\

194

190

` User Event Source Drag Target`\

195

191

` (Mouse) Loop Control Object Control`\

196

192

` = = = =`\

197

193

` | | | |`\

198

194

` 1|--MouseDown--->| | |`\

199

195

` | 2#--OnMouseDown->| |`\

200

196

` | | 3# |`\

201

197

` | 4#<-BeginDrag()--# |`\

202

198

` | # # |`\

203

199

` | | | |`\

204

200

` | 5#--OnStartDrag->| |`\

205

201

` | # 6#----Create---->= |`\

206

202

` | | # | |`\

207

203

` 7|--MouseMove--->| | | |`\

208

204

` | 8#-----------------------------------OnDragOver->|`\

209

205

` | # | | 9#`\

210

206

` | # | | #`\

211

207

` | | | | |`\

212

208

` 10|---MouseUp---->| | | |`\

213

209

` | 11#-----------------------------------OnDragDrop->|`\

214

210

` | # | | 12#`\

215

211

` | # | | #`\

216

212

` | #---OnEndDrag-->| | |`\

217

213

` | | 13#----Destroy--->= |`\

218

214

` | | | |`

219

215

220

216

The DragObject is optional. There could be multiple candidate targets. The Main Event Loop determines which event to send to which object, depending on the user action, the cursor location, and the current state of the GUI.

221

217

222

218

4 somehow triggers 5 (there is a delay depending on the Boolean parameter Immediate to BeginDrag).

223

219

224

220

6 determines the location of the MouseDown and may use this to decide on what gets dragged (through GetCursorPos, ScreenToClient, MouseToCell). It can call SetDragImage to visualize a thing being dragged.

225

221

226

222

The chain 7, 8, 9 can occur repeatedly; 9 indicates acceptability of a drop at this target via the Boolean var parameter Accepted.

227

223

228

224

12 is called only if the immediately preceding OnDragOver of this target returned Accepted = True; i.e. Accepted is a precondition of 12.

229

225

230

226

13 receives the parameter Target to know where the drop was accepted; if Target = nil, then the drop was cancelled by the user (MouseUp at an unacceptable location), and OnDragDrop was not performed; if Target \<\> nil, then OnDragDrop was already performed at the Target. The work associated with an actual drop is thus divided over the OnDragDrop (for actions at the target) and OnEndDrag (for actions at the source). Since a Drag Object needs to be destroyed, independent of whether the drop was successful or canceled, it is best to call Free (or Destroy) only in the OnEndDrag handler.

231

227

232

228

Only one drag can be active at any moment; it either ends in a drop or is canceled.

233

229

234

230

There are various other things to be included, but this is the fundamental part. (Maybe also see [Delphi-Central](http://www.delphi-central.com/drag.aspx) or ["Implementing drag-and-drop in controls"](http://www.podgoretsky.com/ftp/Docs/Delphi/D5/dg/controls.html).)

235

231

236

232

I hope this is helpful. Tom

237

233

238

234

## See also

239

235

240

236

- [[Drag and Drop sample]]

241

237

242

238

---

243

239

*From the Free Pascal wiki, page "LCL Drag Drop", as it stood on 2023-12-13 after a change by Coz, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).*