LCL Drag Drop/fr: what changed

Old	New		Line
1		-	~~<h2>~~
2		-
3	1		Guide de DoDi pour glisser(drag), déplacer(drop), déposer(Dock)
4		-
5		-	~~</h2>~~
6	2
7	3		Les contrôles dans un GUI peut être attrapée avec la souris, déplacés vers d'autres endroits, et déposés par dessus d'autres contrôles ou sur le bureau. Lorsque le contrôle glissé est déplacé vers un emplacement différent, l'opération est appelée [[LCL Drag Dock\|"glisser déposer"]]. Par ailleurs, le contrôle source et le contrôle cible peuvent échanger des informations ou interagir de toute autre manière, ce qu'on appelle une opération de "glisser-déposer".
8	4
9	5		Mais tout cela ne fonctionne pas de lui-même, une application doit configurer les opérations permises de sorte que la bibliothèque LCL puisse savoir ce qu'il faut faire avec chaque contrôle simple dans un GUI. Les opérations sophistiquées exigent davantage de code pour la gestion du retour visuel à l'utilisateur de l'application, et ce qui va se passer quand le contrôle glissé sera finalement déposé.
10	6
11	7		## Glisser Déplacer
12	8
13	9		C'est seulement une action de glisser simple et originale. Les acteurs sont:
14	10
15	11		- Un contrôle d'origine que l'on peut glisser dans le GUI
16	12		- Un objet qui glisse, dérivés de TDragObject
17	13		- des fonctions d'aide
18	14		- des événements
19	15
20	16		Maintenant, jetons un œil à la manière dont ils travaillent ensemble, basé sur l'implémentation initiale en Delphi pour plus de clarté. L'implémentation de la bibliothèque LCL est quelque peu différente dans l'utilisation des objets d'aide, les détails seront discutés plus loin.
21	17
22	18		### La source de glissement
23	19
24	20		Un contrôle peut être rendu déplaçable en fixant sa propriété DragMode à dmAutomatic. Lorsque l'utilisateur appuie avec le bouton gauche de la souris sur un tel contrôle, le pointeur de la souris change en un indicateur de glissement jusqu'à ce que l'utilisateur relâche le bouton, ou annule l'opération en appuyant sur la touche Escape. L'indicateur suit désormais les mouvements de la souris et change sa forme, conformément à ce qui se passera lorsque le contrôle sera déplacé sur l'emplacement du moment.
25	21
26	22		Le glissement peut également être lancé dans le code, en appelant la source.BeginDrag. Dans les deux cas, la procédure d'aide DragInitControl est appelé pour démarrer le glissement. Le contrôle initial lève un évènement StartDrag, là où l'application peut fournir un objet de glissement usuel. En cas d'absence d'un tel objet, un objet par défaut est créé. Des structures de données internes pour la rétroaction visuelle et plus sont initialisées. Alors DragTo et appelée pour montrer que le glissement a commencé.
27	23
28	24		### L'objet qui glisse
29	25
30	26		A drag object receives all user input while dragging. In the default implementation it reacts by calling either DragTo or finally DragDone.
31	27
32	28		The drag object also is responsible for the visual feedback:
33	29
34	30		- GetDragCursor returns the mouse pointer shape.
35	31		- GetDragImages returns a list of drag images, to be attached to the mouse pointer.
36	32		- ShowDragImage and HideDragImage implement the visual feedback.
37	33
38	34		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.
39	35
40	36		#### LCL Modifications
41	37
42	38		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 :-(
43	39
44	40		Also the drag object is bypassed in the presentation of the visual feedback.
45	41
46	42		### Helper Functions
47	43
48	44		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.
49	45
50	46		#### General Helpers
51	47
52	48		DragTo 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.
53	49
54	50		DragDone terminates dragging, either with a drop or cancel of the operation.
55	51
56	52		CancelDrag is protected against false calls, otherwise it defers further actions to DragDone.
57	53
58	54		#### Special Helpers
59	55
60	56		Some more public helper procedures exist, which are undocumented in Delphi and are not required for customized dragging operations.
61	57
62	58		DragFindWindow searches for a drag target window (platform specific).
63	59
64	60		DragInit initializes the internal management, like mouse capture, and the visual feedback.
65	61
66	62		DragInitControl creates the drag object, then calls DragInit.
67	63
68	64		SetCaptureControl handles the mouse capture.
69	65
70	66		### Events
71	67
72	68		#### OnStartDrag/Dock
73	69
74	70		This event occurs when the operation starts. The handler can provide a custom DockObject for the operation.
75	71
76	72		#### OnDrag/DockOver
77	73
78	74		This event notifies a possible target, when an object is dragged over it. The handler can signal to accept or reject an drop.
79	75
80	76		The event signals not only mouse moves, but also when the mouse enters or leaves a target control.
81	77
82	78		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.
83	79
84	80		#### OnDrag/DockDrop
85	81
86	82		This event notifies the target control of the end of a drag operation.
87	83
88	84		#### OnEndDrag/Dock
89	85
90	86		This event notifies the source control of the end of a drag operation.
91	87
92	88		### Docking specific Events
93	89
94	90		(this section should be moved to docking topic)
95	91
96	92		#### OnGetSiteInfo
97	93
98	94		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.
99	95
100	96		#### OnUnDock
101	97
102	98		This event occurs when the dragged control has to be removed from its host dock site.
103	99
104	100		It's unclear what should happen when the handler denies to undock the control.
105	101
106	102		## LCL Implementation
107	103
108	104		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 copied from 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.
109	105
110	106		The current LCL implementation uses a DragManager object and drag/dock performers instead of helper functions. The reason for this breaking change is unclear - who can explain?
111	107
112	108		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.
113	109
114	110		### DragManager
115	111
116	112		This object handles the captured input, provides helper methods, and stores dragging and docking parameters.
117	113
118	114		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.
119	115
120	116		The helper methods require different calls, but this is harmless as long as they are only called from LCL components.
121	117
122	118		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 :-(
123	119
124	120		### Drag Performers
125	121
126	122		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.
127	123
128	124		## Message Sequence Chart or UML Sequence Diagram
129	125
130	126		Provided by Tom Verhoeff
131	127
132	128		Something along the lines (this is for Delphi; view with monospaced font):
133	129
134	130		` Main Drag (Optional) Drag`\
135	131		` User Event Source Drag Target`\
136	132		` (Mouse) Loop Control Object Control`\
137	133		` = = = =`\
138	134		` \| \| \| \|`\
139	135		` 1\|--MouseDown--->\| \| \|`\
140	136		` \| 2#--OnMouseDown->\| \|`\
141	137		` \| \| 3# \|`\
142	138		` \| 4#<-BeginDrag()--# \|`\
143	139		` \| # # \|`\
144	140		` \| \| \| \|`\
145	141		` \| 5#--OnStartDrag->\| \|`\
146	142		` \| # 6#----Create---->= \|`\
147	143		` \| \| # \| \|`\
148	144		` 7\|--MouseMove--->\| \| \| \|`\
149	145		` \| 8#-----------------------------------OnDragOver->\|`\
150	146		` \| # \| \| 9#`\
151	147		` \| # \| \| #`\
152	148		` \| \| \| \| \|`\
153	149		` 10\|---MouseUp---->\| \| \| \|`\
154	150		` \| 11#-----------------------------------OnDragDrop->\|`\
155	151		` \| # \| \| 12#`\
156	152		` \| # \| \| #`\
157	153		` \| #---OnEndDrag-->\| \| \|`\
158	154		` \| \| 13#----Destroy--->= \|`\
159	155		` \| \| \| \|`
160	156
161	157		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.
162	158
163	159		4 somehow triggers 5 (there is a delay depending on the Boolean parameter Immediate to BeginDrag).
164	160
165	161		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.
166	162
167	163		The chain 7, 8, 9 can occur repeatedly; 9 indicates acceptability of a drop at this target via the Boolean var parameter Accepted.
168	164
169	165		12 is called only if the immediately preceding OnDragOver of this target returned Accepted = True; i.e. Accepted is a precondition of 12.
170	166
171	167		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.
172	168
173	169		Only one drag can be active at any moment; it either ends in a drop or is canceled.
174	170
175	171		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).)
176	172
177	173		I hope this is helpful. Tom
178	174
179	175		---
180	176		From the Free Pascal wiki, page "LCL Drag Drop/fr", as it stood on 2009-07-15 after a change by Paulatreides, 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

Guide de DoDi pour glisser(drag), déplacer(drop), déposer(Dock)

6

2

7

3

Les contrôles dans un GUI peut être attrapée avec la souris, déplacés vers d'autres endroits, et déposés par dessus d'autres contrôles ou sur le bureau. Lorsque le contrôle glissé est déplacé vers un emplacement différent, l'opération est appelée [[LCL Drag Dock|"glisser déposer"]]. Par ailleurs, le contrôle source et le contrôle cible peuvent échanger des informations ou interagir de toute autre manière, ce qu'on appelle une opération de "glisser-déposer".

8

4

9

5

Mais tout cela ne fonctionne pas de lui-même, une application doit configurer les opérations permises de sorte que la bibliothèque LCL puisse savoir ce qu'il faut faire avec chaque contrôle simple dans un GUI. Les opérations sophistiquées exigent davantage de code pour la gestion du retour visuel à l'utilisateur de l'application, et ce qui va se passer quand le contrôle glissé sera finalement déposé.

10

6

11

7

## Glisser Déplacer

12

8

13

9

C'est seulement une action de glisser simple et originale. Les acteurs sont:

14

10

15

11

- Un contrôle d'origine que l'on peut glisser dans le GUI

16

12

- Un objet qui glisse, dérivés de TDragObject

17

13

- des fonctions d'aide

18

14

- des événements

19

15

20

16

Maintenant, jetons un œil à la manière dont ils travaillent ensemble, basé sur l'implémentation initiale en Delphi pour plus de clarté. L'implémentation de la bibliothèque LCL est quelque peu différente dans l'utilisation des objets d'aide, les détails seront discutés plus loin.

21

17

22

18

### La source de glissement

23

19

24

20

Un contrôle peut être rendu déplaçable en fixant sa propriété **DragMode** à **dmAutomatic**. Lorsque l'utilisateur appuie avec le bouton gauche de la souris sur un tel contrôle, le pointeur de la souris change en un indicateur de glissement jusqu'à ce que l'utilisateur relâche le bouton, ou annule l'opération en appuyant sur la touche Escape. L'indicateur suit désormais les mouvements de la souris et change sa forme, conformément à ce qui se passera lorsque le contrôle sera déplacé sur l'emplacement du moment.

25

21

26

22

Le glissement peut également être lancé dans le code, en appelant la source.BeginDrag. Dans les deux cas, la procédure d'aide DragInitControl est appelé pour démarrer le glissement. Le contrôle initial lève un évènement StartDrag, là où l'application peut fournir un objet de glissement usuel. En cas d'absence d'un tel objet, un objet par défaut est créé. Des structures de données internes pour la rétroaction visuelle et plus sont initialisées. Alors DragTo et appelée pour montrer que le glissement a commencé.

27

23

28

24

### L'objet qui glisse

29

25

30

26

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

31

27

32

28

The drag object also is responsible for the visual feedback:

33

29

34

30

- GetDragCursor returns the mouse pointer shape.

35

31

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

36

32

- ShowDragImage and HideDragImage implement the visual feedback.

37

33

38

34

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.

39

35

40

36

#### LCL Modifications

41

37

42

38

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 :-(

43

39

44

40

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

45

41

46

42

### Helper Functions

47

43

48

44

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.

49

45

50

46

#### General Helpers

51

47

52

48

**DragTo** 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.

53

49

54

50

**DragDone** terminates dragging, either with a drop or cancel of the operation.

55

51

56

52

**CancelDrag** is protected against false calls, otherwise it defers further actions to DragDone.

57

53

58

54

#### Special Helpers

59

55

60

56

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

61

57

62

58

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

63

59

64

60

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

65

61

66

62

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

67

63

68

64

**SetCaptureControl** handles the mouse capture.

69

65

70

66

### Events

71

67

72

68

#### OnStartDrag/Dock

73

69

74

70

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

75

71

76

72

#### OnDrag/DockOver

77

73

78

74

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

79

75

80

76

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

81

77

82

78

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.

83

79

84

80

#### OnDrag/DockDrop

85

81

86

82

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

87

83

88

84

#### OnEndDrag/Dock

89

85

90

86

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

91

87

92

88

### Docking specific Events

93

89

94

90

(this section should be moved to docking topic)

95

91

96

92

#### OnGetSiteInfo

97

93

98

94

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.

99

95

100

96

#### OnUnDock

101

97

102

98

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

103

99

104

100

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

105

101

106

102

## LCL Implementation

107

103

108

104

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 copied from 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.

109

105

110

106

The current LCL implementation uses a DragManager object and drag/dock performers instead of helper functions. The reason for this breaking change is unclear - who can explain?

111

107

112

108

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.

113

109

114

110

### DragManager

115

111

116

112

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

117

113

118

114

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.

119

115

120

116

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

121

117

122

118

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 :-(

123

119

124

120

### Drag Performers

125

121

126

122

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.

127

123

128

124

## Message Sequence Chart or UML Sequence Diagram

129

125

130

126

Provided by Tom Verhoeff

131

127

132

128

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

133

129

134

130

` Main Drag (Optional) Drag`\

135

131

` User Event Source Drag Target`\

136

132

` (Mouse) Loop Control Object Control`\

137

133

` = = = =`\

138

134

` | | | |`\

139

135

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

140

136

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

141

137

` | | 3# |`\

142

138

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

143

139

` | # # |`\

144

140

` | | | |`\

145

141

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

146

142

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

147

143

` | | # | |`\

148

144

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

149

145

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

150

146

` | # | | 9#`\

151

147

` | # | | #`\

152

148

` | | | | |`\

153

149

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

154

150

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

155

151

` | # | | 12#`\

156

152

` | # | | #`\

157

153

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

158

154

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

159

155

` | | | |`

160

156

161

157

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.

162

158

163

159

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

164

160

165

161

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.

166

162

167

163

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

168

164

169

165

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

170

166

171

167

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.

172

168

173

169

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

174

170

175

171

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

176

172

177

173

I hope this is helpful. Tom

178

174

179

175

---

180

176

*From the Free Pascal wiki, page "LCL Drag Drop/fr", as it stood on 2009-07-15 after a change by Paulatreides, 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).*