1TkDND(n)                     Tk Built-In Commands                     TkDND(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       TkDND - Tk Drag and Drop Interface
9

SYNOPSIS

11       tkdnd::drop_target register window ?type-list?
12       tkdnd::drop_target unregister window
13
14       tkdnd::drag_source register window ?type-list? ?mouse-button?
15       tkdnd::drag_source unregister window
16
17       tkdnd::platform_specific_types type-list
18       tkdnd::platform_independent_types type-list
19
20       tkdnd::GetDropFileTempDirectory
21       tkdnd::SetDropFileTempDirectory directory
22
23

INTRODUCTION

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
32       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
37       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
44       The legal forms for the TkDND commands are:
45
46       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
52              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
61       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
68       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
74              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
85              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
91       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
98       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
105       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
112       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
120       tkdnd::SetDropFileTempDirectory directory
121              This  command  will change the temporary directory used by TkDND
122              for storing temporary files to directory.
123

SUPPORTED TYPES

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
133       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
140       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
148       Additionally to the platform independent types, TkDND supports the fol‐
149       lowing platform specific types:
150
151       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
177       Unix:
178
179       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

EVENTS

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
193       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

DROP TARGET EVENTS

208       A window registered as a drop target, is expected to have bindings  for
209       the following virtual events:
210
211       <<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
222       <<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
235       <<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
243       <<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
253       <<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

DRAG SOURCE EVENTS

268       A window registered as a drag source, is expected to have bindings  for
269       the following virtual events:
270
271       <<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
286       <<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

BINDING SCRIPTS AND SUBSTITUTIONS

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
299       If the binding script contains any  %  characters,  then  substitutions
300       will  be  made,  like  in normal Tk binding scripts. Valid % specifiers
301       are:
302
303       %%   Replaced with a single percent.
304
305       %A   The current action of the drag/drop operation.
306
307       %a   The action list supported by the drag source.
308
309       %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
313       %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
317       %C   The code (in octal format) of the current type  of  the  drag  and
318            drop operation.
319
320       %CTT The  list  of types from the drop target type list that are common
321            to the drag source type list.
322
323       %CST The list of types from the drag source type list that  are  common
324            to the drop target type list.
325
326       %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
330       %e   The  name  of  the  current  virtual  event. One of <<DropEnter>>,
331            <<DropPosition>>,    <<DropLeave>>,    <<Drop:type>>,    <<Drop>>,
332            <<DragInitCmd>>, <<DragEndCmd>>.
333
334       %L   The list of types supported by the drag source.
335
336       %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
343       %ST  The list of types supported by the drag source.
344
345       %t   The list of types supported by the drag source.
346
347       %T   The current type of the drag and drop operation.
348
349       %TT  The list of types supported by the drop target.
350
351       %W   The window that the event is delivered to.
352
353       %X   The mouse pointer x coordinate, relative to the root window.
354
355       %Y   The mouse pointer y coordinate, relative to the root window.
356

SPECIFYING DROP TARGETS

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
375       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

SPECIFYING DRAG SOURCES

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

SPECIFYING DRAG SOURCES WITH MULTIPLE DATA TYPES

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

BUGS

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

KEYWORDS

419       dnd, drag and drop
420
421
422
423Tk                                    8.4                             TkDND(n)
Impressum