1 """Drag-and-drop support for Tkinter.

     2 

     3 This is very preliminary.  I currently only support dnd *within* one

     4 application, between different windows (or within the same window).

     5 

     6 I an trying to make this as generic as possible -- not dependent on

     7 the use of a particular widget or icon type, etc.  I also hope that

     8 this will work with Pmw.

     9 

    10 To enable an object to be dragged, you must create an event binding

    11 for it that starts the drag-and-drop process. Typically, you should

    12 bind <ButtonPress> to a callback function that you write. The function

    13 should call Tkdnd.dnd_start(source, event), where 'source' is the

    14 object to be dragged, and 'event' is the event that invoked the call

    15 (the argument to your callback function).  Even though this is a class

    16 instantiation, the returned instance should not be stored -- it will

    17 be kept alive automatically for the duration of the drag-and-drop.

    18 

    19 When a drag-and-drop is already in process for the Tk interpreter, the

    20 call is *ignored*; this normally averts starting multiple simultaneous

    21 dnd processes, e.g. because different button callbacks all

    22 dnd_start().

    23 

    24 The object is *not* necessarily a widget -- it can be any

    25 application-specific object that is meaningful to potential

    26 drag-and-drop targets.

    27 

    28 Potential drag-and-drop targets are discovered as follows.  Whenever

    29 the mouse moves, and at the start and end of a drag-and-drop move, the

    30 Tk widget directly under the mouse is inspected.  This is the target

    31 widget (not to be confused with the target object, yet to be

    32 determined).  If there is no target widget, there is no dnd target

    33 object.  If there is a target widget, and it has an attribute

    34 dnd_accept, this should be a function (or any callable object).  The

    35 function is called as dnd_accept(source, event), where 'source' is the

    36 object being dragged (the object passed to dnd_start() above), and

    37 'event' is the most recent event object (generally a <Motion> event;

    38 it can also be <ButtonPress> or <ButtonRelease>).  If the dnd_accept()

    39 function returns something other than None, this is the new dnd target

    40 object.  If dnd_accept() returns None, or if the target widget has no

    41 dnd_accept attribute, the target widget's parent is considered as the

    42 target widget, and the search for a target object is repeated from

    43 there.  If necessary, the search is repeated all the way up to the

    44 root widget.  If none of the target widgets can produce a target

    45 object, there is no target object (the target object is None).

    46 

    47 The target object thus produced, if any, is called the new target

    48 object.  It is compared with the old target object (or None, if there

    49 was no old target widget).  There are several cases ('source' is the

    50 source object, and 'event' is the most recent event object):

    51 

    52 - Both the old and new target objects are None.  Nothing happens.

    53 

    54 - The old and new target objects are the same object.  Its method

    55 dnd_motion(source, event) is called.

    56 

    57 - The old target object was None, and the new target object is not

    58 None.  The new target object's method dnd_enter(source, event) is

    59 called.

    60 

    61 - The new target object is None, and the old target object is not

    62 None.  The old target object's method dnd_leave(source, event) is

    63 called.

    64 

    65 - The old and new target objects differ and neither is None.  The old

    66 target object's method dnd_leave(source, event), and then the new

    67 target object's method dnd_enter(source, event) is called.

    68 

    69 Once this is done, the new target object replaces the old one, and the

    70 Tk mainloop proceeds.  The return value of the methods mentioned above

    71 is ignored; if they raise an exception, the normal exception handling

    72 mechanisms take over.

    73 

    74 The drag-and-drop processes can end in two ways: a final target object

    75 is selected, or no final target object is selected.  When a final

    76 target object is selected, it will always have been notified of the

    77 potential drop by a call to its dnd_enter() method, as described

    78 above, and possibly one or more calls to its dnd_motion() method; its

    79 dnd_leave() method has not been called since the last call to

    80 dnd_enter().  The target is notified of the drop by a call to its

    81 method dnd_commit(source, event).

    82 

    83 If no final target object is selected, and there was an old target

    84 object, its dnd_leave(source, event) method is called to complete the

    85 dnd sequence.

    86 

    87 Finally, the source object is notified that the drag-and-drop process

    88 is over, by a call to source.dnd_end(target, event), specifying either

    89 the selected target object, or None if no target object was selected.

    90 The source object can use this to implement the commit action; this is

    91 sometimes simpler than to do it in the target's dnd_commit().  The

    92 target's dnd_commit() method could then simply be aliased to

    93 dnd_leave().

    94 

    95 At any time during a dnd sequence, the application can cancel the

    96 sequence by calling the cancel() method on the object returned by

    97 dnd_start().  This will call dnd_leave() if a target is currently

    98 active; it will never call dnd_commit().

    99 

   100 """

   101 

   102 

   103 import Tkinter

   104 

   105 

   106 # The factory function

   107 

   108 def dnd_start(source, event):

   109     h = DndHandler(source, event)

   110     if h.root:

   111         return h

   112     else:

   113         return None

   114 

   115 

   116 # The class that does the work

   117 

   118 class DndHandler:

   119 

   120     root = None

   121 

   122     def __init__(self, source, event):

   123         if event.num > 5:

   124             return

   125         root = event.widget._root()

   126         try:

   127             root.__dnd

   128             return # Don't start recursive dnd

   129         except AttributeError:

   130             root.__dnd = self

   131             self.root = root

   132         self.source = source

   133         self.target = None

   134         self.initial_button = button = event.num

   135         self.initial_widget = widget = event.widget

   136         self.release_pattern = "<B%d-ButtonRelease-%d>" % (button, button)

   137         self.save_cursor = widget['cursor'] or ""

   138         widget.bind(self.release_pattern, self.on_release)

   139         widget.bind("<Motion>", self.on_motion)

   140         widget['cursor'] = "hand2"

   141 

   142     def __del__(self):

   143         root = self.root

   144         self.root = None

   145         if root:

   146             try:

   147                 del root.__dnd

   148             except AttributeError:

   149                 pass

   150 

   151     def on_motion(self, event):

   152         x, y = event.x_root, event.y_root

   153         target_widget = self.initial_widget.winfo_containing(x, y)

   154         source = self.source

   155         new_target = None

   156         while target_widget:

   157             try:

   158                 attr = target_widget.dnd_accept

   159             except AttributeError:

   160                 pass

   161             else:

   162                 new_target = attr(source, event)

   163                 if new_target:

   164                     break

   165             target_widget = target_widget.master

   166         old_target = self.target

   167         if old_target is new_target:

   168             if old_target:

   169                 old_target.dnd_motion(source, event)

   170         else:

   171             if old_target:

   172                 self.target = None

   173                 old_target.dnd_leave(source, event)

   174             if new_target:

   175                 new_target.dnd_enter(source, event)

   176                 self.target = new_target

   177 

   178     def on_release(self, event):

   179         self.finish(event, 1)

   180 

   181     def cancel(self, event=None):

   182         self.finish(event, 0)

   183 

   184     def finish(self, event, commit=0):

   185         target = self.target

   186         source = self.source

   187         widget = self.initial_widget

   188         root = self.root

   189         try:

   190             del root.__dnd

   191             self.initial_widget.unbind(self.release_pattern)

   192             self.initial_widget.unbind("<Motion>")

   193             widget['cursor'] = self.save_cursor

   194             self.target = self.source = self.initial_widget = self.root = None

   195             if target:

   196                 if commit:

   197                     target.dnd_commit(source, event)

   198                 else:

   199                     target.dnd_leave(source, event)

   200         finally:

   201             source.dnd_end(target, event)

   202 

   203 

   204 

   205 # ----------------------------------------------------------------------

   206 # The rest is here for testing and demonstration purposes only!

   207 

   208 class Icon:

   209 

   210     def __init__(self, name):

   211         self.name = name

   212         self.canvas = self.label = self.id = None

   213 

   214     def attach(self, canvas, x=10, y=10):

   215         if canvas is self.canvas:

   216             self.canvas.coords(self.id, x, y)

   217             return

   218         if self.canvas:

   219             self.detach()

   220         if not canvas:

   221             return

   222         label = Tkinter.Label(canvas, text=self.name,

   223                               borderwidth=2, relief="raised")

   224         id = canvas.create_window(x, y, window=label, anchor="nw")

   225         self.canvas = canvas

   226         self.label = label

   227         self.id = id

   228         label.bind("<ButtonPress>", self.press)

   229 

   230     def detach(self):

   231         canvas = self.canvas

   232         if not canvas:

   233             return

   234         id = self.id

   235         label = self.label

   236         self.canvas = self.label = self.id = None

   237         canvas.delete(id)

   238         label.destroy()

   239 

   240     def press(self, event):

   241         if dnd_start(self, event):

   242             # where the pointer is relative to the label widget:

   243             self.x_off = event.x

   244             self.y_off = event.y

   245             # where the widget is relative to the canvas:

   246             self.x_orig, self.y_orig = self.canvas.coords(self.id)

   247 

   248     def move(self, event):

   249         x, y = self.where(self.canvas, event)

   250         self.canvas.coords(self.id, x, y)

   251 

   252     def putback(self):

   253         self.canvas.coords(self.id, self.x_orig, self.y_orig)

   254 

   255     def where(self, canvas, event):

   256         # where the corner of the canvas is relative to the screen:

   257         x_org = canvas.winfo_rootx()

   258         y_org = canvas.winfo_rooty()

   259         # where the pointer is relative to the canvas widget:

   260         x = event.x_root - x_org

   261         y = event.y_root - y_org

   262         # compensate for initial pointer offset

   263         return x - self.x_off, y - self.y_off

   264 

   265     def dnd_end(self, target, event):

   266         pass

   267 

   268 class Tester:

   269 

   270     def __init__(self, root):

   271         self.top = Tkinter.Toplevel(root)

   272         self.canvas = Tkinter.Canvas(self.top, width=100, height=100)

   273         self.canvas.pack(fill="both", expand=1)

   274         self.canvas.dnd_accept = self.dnd_accept

   275 

   276     def dnd_accept(self, source, event):

   277         return self

   278 

   279     def dnd_enter(self, source, event):

   280         self.canvas.focus_set() # Show highlight border

   281         x, y = source.where(self.canvas, event)

   282         x1, y1, x2, y2 = source.canvas.bbox(source.id)

   283         dx, dy = x2-x1, y2-y1

   284         self.dndid = self.canvas.create_rectangle(x, y, x+dx, y+dy)

   285         self.dnd_motion(source, event)

   286 

   287     def dnd_motion(self, source, event):

   288         x, y = source.where(self.canvas, event)

   289         x1, y1, x2, y2 = self.canvas.bbox(self.dndid)

   290         self.canvas.move(self.dndid, x-x1, y-y1)

   291 

   292     def dnd_leave(self, source, event):

   293         self.top.focus_set() # Hide highlight border

   294         self.canvas.delete(self.dndid)

   295         self.dndid = None

   296 

   297     def dnd_commit(self, source, event):

   298         self.dnd_leave(source, event)

   299         x, y = source.where(self.canvas, event)

   300         source.attach(self.canvas, x, y)

   301 

   302 def test():

   303     root = Tkinter.Tk()

   304     root.geometry("+1+1")

   305     Tkinter.Button(command=root.quit, text="Quit").pack()

   306     t1 = Tester(root)

   307     t1.top.geometry("+1+60")

   308     t2 = Tester(root)

   309     t2.top.geometry("+120+60")

   310     t3 = Tester(root)

   311     t3.top.geometry("+240+60")

   312     i1 = Icon("ICON1")

   313     i2 = Icon("ICON2")

   314     i3 = Icon("ICON3")

   315     i1.attach(t1.canvas)

   316     i2.attach(t2.canvas)

   317     i3.attach(t3.canvas)

   318     root.mainloop()

   319 

   320 if __name__ == '__main__':

   321     test()