1TkDND(n) Tk Built-In Commands TkDND(n)
2______________________________________________________________________________
6
8 TkDND - Tk Drag and Drop Interface
9
11 tkdnd::drop_target register window ?type-list?
12 tkdnd::drop_target unregister window
13 tkdnd::drag_source register window ?type-list? ?mouse-button?
15 tkdnd::drag_source unregister window
16 tkdnd::platform_specific_types type-list
18 tkdnd::platform_independent_types type-list
19 tkdnd::GetDropFileTempDirectory
21 tkdnd::SetDropFileTempDirectory directory
22
25 The TkDND family commands provide a Tcl interface to native, platform
26 specific drag and drop mechanism. Under Unix the drag & drop protocol
27 in use is the XDND protocol version 5 (also used by the Qt toolkit, and
28 the KDE and GNOME desktops). Under Windows, the OLE2 drag & drop
29 interfaces are used. Under Macintosh, the Cocoa drag and drop inter‐
30 faces are used.
31 The TkDND family can be built from source code using the standard con‐
33 figure; make; make install procedure. Cmake is also supported. Some
34 binary package are available from the SourceForge download site, from
35 ActiveState's ActiveTcl distribution, and elsewhere.
36 With the TkDND family commands the user is able to register existing Tk
38 widgets as drag sources or drop targets, that are able to send or
39 receive data during drag and drop operations, encoded in specific
40 types. These types can be platform independent types like DND_Text and
41 DND_Files or platform specific types, like CF_UNICODETEXT or
42 text/plain.
43 The legal forms for the TkDND commands are:
45 tkdnd::drop_target register window ?type-list?
47 This command will register window as a drop target. A drop tar‐
48 get is a widget than can accept a drop action. window must exist
49 when this command is executed and this command can be executed
50 multiple times on a widget.
51 When window is registered as a drop target, and optional type-
53 list can be provided. This type list can contain one or more
54 types that window will accept during a drop action, and it can
55 contain platform independent or platform specific types. Plat‐
56 form independent are DND_Text for dropping text portions and
57 DND_Files for dropping a list of files (which can contain one or
58 multiple files) on window. If type-list is not specified, it
59 defaults to the empty list.
60 tkdnd::drop_target unregister window
62 This command will stop window from being a drop target. Thus,
63 window will stop receiving events related to drop operations.
64 It is an error to use this command for a window that has not
65 been registered as a drop target with tkdnd::drop_target regis‐
66 ter.
67 tkdnd::drag_source register window ?type-list? ?mouse-button?
69 This command will register window as a drag source. A drag
70 source is a widget than can start a drag action. window must
71 exist when this command is executed and this command can be exe‐
72 cuted multiple times on a widget.
73 When window is registered as a drag source, and optional type-
75 list can be provided. This type list can contain one or more
76 types that window will provide during a drag action, and it can
77 contain platform independent or platform specific types. Plat‐
78 form independent are DND_Text for dropping text portions and
79 DND_Files for dropping a list of files (which can contain one or
80 multiple files) on window. However, this type list is indica‐
81 tive/informative. window can initiate a drag action with even a
82 different type list. If type-list is not specified, it defaults
83 to the empty list.
84 Finally, mouse-button is the mouse button that will be used for
86 starting the drag action. It can have any of the values 1 (left
87 mouse button), 2 (middle mouse button - wheel) and 3 (right
88 mouse button). If mouse-button is not specified, it defaults to
89 1.
90 tkdnd::drag_source unregister window
92 This command will stop window from being a drag source. Thus,
93 window will stop receiving events related to drag operations.
94 It is an error to use this command for a window that has not
95 been registered as a drag source with tkdnd::drag_source regis‐
96 ter.
97 tkdnd::platform_specific_types type-list
99 This command will accept a list of types that can contain plat‐
100 form independent or platform specific types. A new list will be
101 returned, where each platform independent type in type-list will
102 be substituted by one or more platform specific types. Thus, the
103 returned list may have more elements than type-list.
104 tkdnd::platform_independent_types type-list
106 This command will accept a list of types that can contain plat‐
107 form independent or platform specific types. A new list will be
108 returned, where each platform specific type in type-list will be
109 substituted by one or more platform independent types. Thus, the
110 returned list may have more elements than type-list.
111 tkdnd::GetDropFileTempDirectory
113 This command will return the temporary directory used by TkDND
114 for storing temporary files. When the package is loaded, this
115 temporary directory will be initialised to a proper directory
116 according to the operating system. This default initial value
117 can be changed to be the value of the following environmental
118 variables: TKDND_TEMP_DIR, TEMP, TMP.
119 tkdnd::SetDropFileTempDirectory directory
121 This command will change the temporary directory used by TkDND
122 for storing temporary files to directory.
123
125 In order to declare the format that the data that will transferred dur‐
126 ing a drag and drop operation, all drag and drop protocols use the
127 notion of types. Unfortunately, each protocol defines its own, usually
128 platform specific, types. TkDND, trying to maintain portability among
129 different platforms, offers some predefined types for some basic kinds
130 of data, like text, and filenames. Currently, the following predefined
131 cross-platform values are available:
132 DND_Text:
134 This type can be used for transferring textual data. Internally,
135 it is translated to the following platform specific formats:
136 Windows: CF_UNICODETEXT, CF_TEXT.
137 Unix: text/plain;charset=UTF-8, text/plain.
138 Mac: NSStringPboardType.
139 DND_Files:
141 This type can be used for transferring a list of file names.
142 Internally, it is translated to the following platform specific
143 formats:
144 Windows: CF_HDROP.
145 Unix: text/uri-list.
146 Mac: NSFilenamesPboardType.
147 Additionally to the platform independent types, TkDND supports the fol‐
149 lowing platform specific types:
150 Windows:
152 CF_UNICODETEXT: Text transfer encoded in Unicode.
153 CF_TEXT: Text transfer with application dependent encoding. If an
154 encoding locale is specified through CF_LOCALE it is used, else
155 the system encoding is used for the conversion.
156 FileGroupDescriptor - FileContents: These two types are used for
157 transferring a set of files that do not appear physically on disk,
158 like files from compressed folders or Outlook e-mail messages.
159 File names are transferred as in the CF_TEXT type, while file con‐
160 tents are transferred in binary. TkDND retrieves both the file
161 names and the file contents, and saves then in a temporary direc‐
162 tory. When the transfer is complete, the file names of the saved
163 files in the temporary folder are returned. Note that TkDND sup‐
164 port this type pair only as drop targets and not as drag sources.
165 FileGroupDescriptorW - FileContents: These two types are used for
166 transferring a set of files that do not appear physically on disk,
167 like files from compressed folders or Outlook e-mail messages.
168 File names are transferred as in the CF_UNICODETEXT type, while
169 file contents are transferred in binary. TkDND retrieves both the
170 file names and the file contents, and saves then in a temporary
171 directory. When the transfer is complete, the file names of the
172 saved files in the temporary folder are returned. Note that TkDND
173 support this type pair only as drop targets and not as drag
174 sources.
175 CF_HDROP: Files transfer encoded in UTF-8.
176 Unix:
178 Finally, format types used for drop types can have wildcards, following
180 the same rules as "string match". For example, registering a drop tar‐
181 get with the type "*", will accept any drop, no matter what the drop
182 format is.
183
185 Windows registered as either drop targets or drag sources, will receive
186 certain events, during drag and drop operations. As a result, the win‐
187 dows are expected to have bindings for some of these events. Some
188 events are mandatory (in the sense that a drag or drop operation can be
189 stopped if the bindings do not exist), while others are not. However,
190 it is a good practice to define bindings for all events, so as the
191 application will behave as expected during drag and drop operations.
192 The TkDND package defines a set of virtual events, that correspond to
194 various phases of a drag and drop operation. All windows that are
195 either a drop target or a drag source are expected to have bindings for
196 (all) these events, created with the bind Tk command. While these event
197 bindings are regular Tk events, they have a small difference from plain
198 Tk events: most of them are expected to return a value. Since Tk bind‐
199 ings cannot return a value, TkDND does not actually generate these
200 events (i.e. through "event generate"). Instead, TkDND locates the
201 script that has been bound to the virtual event, and directly executes
202 it, as a script. Apart from this small difference in how the events are
203 triggered, the events required by TkDND can be viewed as regular
204 events. In the following two sections all virtual events defined by the
205 TkDND package are presented.
206
208 A window registered as a drop target, is expected to have bindings for
209 the following virtual events:
210 <<DropEnter>>:
212 This event is triggered when the mouse enters the window during
213 a drop action. The purpose of this event is to change the visual
214 state of the window, so as to notify the user whether the drop
215 will be accepted or not. The binding script is expected to
216 return a single value that will define the drop action. This
217 returned action can be one of copy, move, link, ask, private and
218 refuse_drop. This event is not mandatory, but if it is defined,
219 it has to return an action. In case an action is not returned,
220 the drop is refused for this window.
221 <<DropPosition>>:
223 This events is triggered when the mouse moves inside the window
224 during a drop action. The purpose of this event is to let window
225 decide if it will accept the drop and the action of the drop, if
226 a drop is going to happen at the specific mouse coordinates.
227 Thus, the script binding for such an event can get the mouse
228 coordinates and the pressed modifier buttons (such as ctrl,
229 shift or alt), and is expected to return the drop action, which
230 again must be one of copy, move, link, ask, private and
231 refuse_drop. This event is not mandatory, but if it is defined,
232 it has to return an action. In case an action is not returned,
233 the drop is refused for this window.
234 <<DropLeave>>:
236 This event is triggered when the mouse leaves outside the area
237 covered by window, without a drop happening. The binding of such
238 an event is expected to restore the visual state of the window
239 to normal (i.e. the visual state the window was in before the
240 <<DropEnter>> event was triggered). The binding for such an
241 event is not expected to return a value.
242 <<Drop>>:
244 This event is triggered by a drop action, and it is expected to
245 handle the dropped data and reset the visual state of the win‐
246 dow. The binding script is expected to return a value, which
247 will be the action that has been performed to the data and must
248 be one of copy, move, link, ask, private and refuse_drop. This
249 event is not mandatory, but if it is defined, it has to return
250 an action. In case an action is not returned, the drop is
251 refused for this window.
252 <<Drop:type>>:
254 This event is a specialisation of the generic <<Drop>> event,
255 augmented with a type. If such a binding exists and the drop
256 type matches type, this event binding will be executed, instead
257 of the generic <<Drop>> event binding. These events allow for
258 easy specialisation of drop bindings, according to the type of
259 the dropped data. type can be either a platform independent or a
260 platform specific type. The binding script of such an event is
261 expected to return a value, which will be the action that has
262 been performed to the data and must be one of copy, move, link,
263 ask, private and refuse_drop. This event is not mandatory, but
264 if it is defined, it has to return an action. In case an action
265 is not returned, the drop is refused for this window.
266
268 A window registered as a drag source, is expected to have bindings for
269 the following virtual events:
270 <<DragInitCmd>>:
272 This event is triggered when a drag action is about to start.
273 This is a mandatory event (whose absence will cancel the drag
274 action), and is responsible for providing three things: the list
275 of actions and format types supported by the drag source, and of
276 course the data to be dropped. Thus, the binding script for such
277 an event must return a list of three elements: the drop actions
278 supported by the drag source (which can be any of copy, move,
279 link, ask, and private), the format type list that the data can
280 be dropped as (which can be any platform independent or platform
281 specific type), and finally the data. A simple example of such a
282 binding, is:
283 bind .drag_source <<DragInitCmd>> \
284 {list copy DND_Text {Hellow world!}}
285 <<DragEndCmd>>:
287 This event is triggered when the drag action has finished
288 (either when the drop was successful or not). Its main purpose
289 is to process the dropped data according to the drop action
290 returned by the drop target. Binding for such an event is not
291 mandatory, and the binding is not expected to return a value.
292
294 All bindings scripts defined for any of the virtual events above will
295 be executed in the same interpreter that was used for creating the win‐
296 dow the event is bound to, and the binding script will executed at the
297 global level (i.e. only global variables will be accessible).
298 If the binding script contains any % characters, then substitutions
300 will be made, like in normal Tk binding scripts. Valid % specifiers
301 are:
302 %% Replaced with a single percent.
304 %A The current action of the drag/drop operation.
306 %a The action list supported by the drag source.
308 %b The mouse button that is pressed during a drag/drop operation.
310 Note that always a single mouse button is reported as pressed,
311 even if more than one mouse buttons are actually pressed.
312 %c The codes of the list of types supported by the drag source. All
314 codes are in octal format and have the same order as the list of
315 types obtained through the %t substitution.
316 %C The code (in octal format) of the current type of the drag and
318 drop operation.
319 %CTT The list of types from the drop target type list that are common
321 to the drag source type list.
322 %CST The list of types from the drag source type list that are common
324 to the drop target type list.
325 %D The data that has been dropped. Under some platforms the data will
327 be available before the drop has occurred. The format of the data
328 is the current type of the drop operation.
329 %e The name of the current virtual event. One of <<DropEnter>>,
331 <<DropPosition>>, <<DropLeave>>, <<Drop:type>>, <<Drop>>,
332 <<DragInitCmd>>, <<DragEndCmd>>.
333 %L The list of types supported by the drag source.
335 %m The list of modifier keyboard keys that are pressed. Modifier
337 keys are some special keys, like Shift, Control or Alt. Valid
338 modifiers are "shift", "ctrl" and "alt". It is useful for binding
339 scripts of drop target events to examine this list of modifiers,
340 as it is quite usual to change the action according to the state
341 of some modifier keys.
342 %ST The list of types supported by the drag source.
344 %t The list of types supported by the drag source.
346 %T The current type of the drag and drop operation.
348 %TT The list of types supported by the drop target.
350 %W The window that the event is delivered to.
352 %X The mouse pointer x coordinate, relative to the root window.
354 %Y The mouse pointer y coordinate, relative to the root window.
356
358 Creating drop targets is easy: we have to only register a window as a
359 drop target with the list of format types it can accept, and add a few
360 bindings. For example, a window that accepts textual drops can be as
361 follows:
362 label .drop_target -text {Text Drop Target!} -bg white
363 tkdnd::drop_target register .drop_target DND_Text
364 bind .drop_target <<DropEnter>> {%W configure -bg yellow; list copy}
365 bind .drop_target <<DropPosition>> {list copy}
366 bind .drop_target <<DropLeave>> {%W configure -bg white}
367 bind .drop_target <<Drop>> {%W configure -text %D; %W configure -bg white}
368 From the above bindings, none is obligatory. However, we usually want
369 to receive dropped data (thus the <<Drop>> event must be handled) and
370 we want to give visual feedback to the users through the <<DropEnter>>
371 and <<DropLeave>> events. Finally, <<DropPosition>> is only necessary
372 if we want to only accept drops on specific areas of the window, or we
373 want to change the drop action according to the pressed modifiers.
374 Now, if we want to also add the ability to receive file drops, we could
376 add:
377 tkdnd::drop_target register .drop_target DND_Files
378 bind .drop_target <<Drop:DND_Files>> \
379 {puts %D; %W configure -bg white}
380 Note that we have added a "specialised" drop binding, for the event
381 <<Drop:DND_Files>>: this means that when a text portion is dropped over
382 the window, the <<Drop>> event binding will be executed. But when a
383 list of files is dropped onto the window, the <<Drop:DND_Files>> event
384 binding will be executed. If we proceed and define a binding for the
385 <<Drop:DND_Text>> event, the binding of the "general" <<Drop>> event
386 will never be executed.
387
389 In order to specify a drag source, we need to register a window as a
390 drag source:
391 tkdnd::drag_source register .text_drag_source
392 The above command defines a drag source with an empty type list (and
393 which will be declared in the <<DragInitCmd>> event binding) and
394 arranges mouse bindings such as a drag will be started with the left
395 mouse button. Then, it is absolutely necessary to define a binding for
396 the <<DragInitCmd>>: this event binding must return the list of
397 actions, the list of format types and the actual data to be dropped:
398 bind .text_drag_source <<DragInitCmd>> \
399 {list {copy move} DND_Text {Hello from Tk!}}
400 Please note that all specified format types must be compatible to each
401 other, as they all characterise the same data.
402
404 In the case the drag source wants to send a set of (incompatible) data
405 types, the result of the <<DragInitCmd>> event binding must be slightly
406 different, as it must return two items (instead of three described in
407 the previous paragraph). The first element is again a list of allow‐
408 able actions. However, the second item is a list of "format type" and
409 "data" pairs: bind .text_drag_source <<DragInitCmd>> \
410 {list {copy move} {DND_Text {Hello from Tk!} DND_Files {/tmp}}}
411 And that was all!
412
414 Unix: Dragging from Tk windows has not yet been implemented. OS X:
415 TkDND under OS X is built on top of the Cocoa framework. Thus, it is
416 compatible with Tk version >= 8.6
417
419 dnd, drag and drop
420Tk 8.4 TkDND(n)