Lib/lib-tk/Tkdnd.py

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