| 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 am 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 |
import tkinter |
| 103 |
|
| 104 |
__all__ = ["dnd_start", "DndHandler"] |
| 105 |
|
| 106 |
|
| 107 |
# The factory function |
| 108 |
|
| 109 |
def dnd_start(source, event): |
| 110 |
h = DndHandler(source, event) |
| 111 |
if h.root is not None: |
| 112 |
return h |
| 113 |
else: |
| 114 |
return None |
| 115 |
|
| 116 |
|
| 117 |
# The class that does the work |
| 118 |
|
| 119 |
class DndHandler: |
| 120 |
|
| 121 |
root = None |
| 122 |
|
| 123 |
def __init__(self, source, event): |
| 124 |
if event.num > 5: |
| 125 |
return |
| 126 |
root = event.widget._root() |
| 127 |
try: |
| 128 |
root.__dnd |
| 129 |
return # Don't start recursive dnd |
| 130 |
except AttributeError: |
| 131 |
root.__dnd = self |
| 132 |
self.root = root |
| 133 |
self.source = source |
| 134 |
self.target = None |
| 135 |
self.initial_button = button = event.num |
| 136 |
self.initial_widget = widget = event.widget |
| 137 |
self.release_pattern = "<B%d-ButtonRelease-%d>" % (button, button) |
| 138 |
self.save_cursor = widget['cursor'] or "" |
| 139 |
widget.bind(self.release_pattern, self.on_release) |
| 140 |
widget.bind("<Motion>", self.on_motion) |
| 141 |
widget['cursor'] = "hand2" |
| 142 |
|
| 143 |
def __del__(self): |
| 144 |
root = self.root |
| 145 |
self.root = None |
| 146 |
if root is not None: |
| 147 |
try: |
| 148 |
del root.__dnd |
| 149 |
except AttributeError: |
| 150 |
pass |
| 151 |
|
| 152 |
def on_motion(self, event): |
| 153 |
x, y = event.x_root, event.y_root |
| 154 |
target_widget = self.initial_widget.winfo_containing(x, y) |
| 155 |
source = self.source |
| 156 |
new_target = None |
| 157 |
while target_widget is not None: |
| 158 |
try: |
| 159 |
attr = target_widget.dnd_accept |
| 160 |
except AttributeError: |
| 161 |
pass |
| 162 |
else: |
| 163 |
new_target = attr(source, event) |
| 164 |
if new_target is not None: |
| 165 |
break |
| 166 |
target_widget = target_widget.master |
| 167 |
old_target = self.target |
| 168 |
if old_target is new_target: |
| 169 |
if old_target is not None: |
| 170 |
old_target.dnd_motion(source, event) |
| 171 |
else: |
| 172 |
if old_target is not None: |
| 173 |
self.target = None |
| 174 |
old_target.dnd_leave(source, event) |
| 175 |
if new_target is not None: |
| 176 |
new_target.dnd_enter(source, event) |
| 177 |
self.target = new_target |
| 178 |
|
| 179 |
def on_release(self, event): |
| 180 |
self.finish(event, 1) |
| 181 |
|
| 182 |
def cancel(self, event=None): |
| 183 |
self.finish(event, 0) |
| 184 |
|
| 185 |
def finish(self, event, commit=0): |
| 186 |
target = self.target |
| 187 |
source = self.source |
| 188 |
widget = self.initial_widget |
| 189 |
root = self.root |
| 190 |
try: |
| 191 |
del root.__dnd |
| 192 |
self.initial_widget.unbind(self.release_pattern) |
| 193 |
self.initial_widget.unbind("<Motion>") |
| 194 |
widget['cursor'] = self.save_cursor |
| 195 |
self.target = self.source = self.initial_widget = self.root = None |
| 196 |
if target is not None: |
| 197 |
if commit: |
| 198 |
target.dnd_commit(source, event) |
| 199 |
else: |
| 200 |
target.dnd_leave(source, event) |
| 201 |
finally: |
| 202 |
source.dnd_end(target, event) |
| 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 is not None: |
| 219 |
self.detach() |
| 220 |
if canvas is None: |
| 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 canvas is None: |
| 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 |
|
| 269 |
class Tester: |
| 270 |
|
| 271 |
def __init__(self, root): |
| 272 |
self.top = tkinter.Toplevel(root) |
| 273 |
self.canvas = tkinter.Canvas(self.top, width=100, height=100) |
| 274 |
self.canvas.pack(fill="both", expand=1) |
| 275 |
self.canvas.dnd_accept = self.dnd_accept |
| 276 |
|
| 277 |
def dnd_accept(self, source, event): |
| 278 |
return self |
| 279 |
|
| 280 |
def dnd_enter(self, source, event): |
| 281 |
self.canvas.focus_set() # Show highlight border |
| 282 |
x, y = source.where(self.canvas, event) |
| 283 |
x1, y1, x2, y2 = source.canvas.bbox(source.id) |
| 284 |
dx, dy = x2-x1, y2-y1 |
| 285 |
self.dndid = self.canvas.create_rectangle(x, y, x+dx, y+dy) |
| 286 |
self.dnd_motion(source, event) |
| 287 |
|
| 288 |
def dnd_motion(self, source, event): |
| 289 |
x, y = source.where(self.canvas, event) |
| 290 |
x1, y1, x2, y2 = self.canvas.bbox(self.dndid) |
| 291 |
self.canvas.move(self.dndid, x-x1, y-y1) |
| 292 |
|
| 293 |
def dnd_leave(self, source, event): |
| 294 |
self.top.focus_set() # Hide highlight border |
| 295 |
self.canvas.delete(self.dndid) |
| 296 |
self.dndid = None |
| 297 |
|
| 298 |
def dnd_commit(self, source, event): |
| 299 |
self.dnd_leave(source, event) |
| 300 |
x, y = source.where(self.canvas, event) |
| 301 |
source.attach(self.canvas, x, y) |
| 302 |
|
| 303 |
|
| 304 |
def test(): |
| 305 |
root = tkinter.Tk() |
| 306 |
root.geometry("+1+1") |
| 307 |
tkinter.Button(command=root.quit, text="Quit").pack() |
| 308 |
t1 = Tester(root) |
| 309 |
t1.top.geometry("+1+60") |
| 310 |
t2 = Tester(root) |
| 311 |
t2.top.geometry("+120+60") |
| 312 |
t3 = Tester(root) |
| 313 |
t3.top.geometry("+240+60") |
| 314 |
i1 = Icon("ICON1") |
| 315 |
i2 = Icon("ICON2") |
| 316 |
i3 = Icon("ICON3") |
| 317 |
i1.attach(t1.canvas) |
| 318 |
i2.attach(t2.canvas) |
| 319 |
i3.attach(t3.canvas) |
| 320 |
root.mainloop() |
| 321 |
|
| 322 |
|
| 323 |
if __name__ == '__main__': |
| 324 |
test() |