summaryrefslogtreecommitdiffstats
path: root/Lib
diff options
context:
space:
mode:
authorGuido van Rossum <guido@python.org>1998-04-10 16:14:34 (GMT)
committerGuido van Rossum <guido@python.org>1998-04-10 16:14:34 (GMT)
commit4cee3c49c285967434208df77e12cef331d97869 (patch)
treeb4cebeebd7fce9f669f395668be236f4b6349ec2 /Lib
parentea609c18a0bb6420f9cdb1440326b1bfdbfc32a2 (diff)
downloadcpython-4cee3c49c285967434208df77e12cef331d97869.zip
cpython-4cee3c49c285967434208df77e12cef331d97869.tar.gz
cpython-4cee3c49c285967434208df77e12cef331d97869.tar.bz2
Another easter present.
Diffstat (limited to 'Lib')
-rw-r--r--Lib/lib-tk/Tkdnd.py321
1 files changed, 321 insertions, 0 deletions
diff --git a/Lib/lib-tk/Tkdnd.py b/Lib/lib-tk/Tkdnd.py
new file mode 100644
index 0000000..0dda3b7
--- /dev/null
+++ b/Lib/lib-tk/Tkdnd.py
@@ -0,0 +1,321 @@
+"""Drag-and-drop support for Tkinter.
+
+This is very preliminary. I currently only support dnd *within* one
+application, between different windows (or within the same window).
+
+I an trying to make this as generic as possible -- not dependent on
+the use of a particular widget or icon type, etc. I also hope that
+this will work with Pmw.
+
+To enable an object to be dragged, you must create an event binding
+for it that starts the drag-and-drop process. Typically, you should
+bind <ButtonPress> to a callback function that you write. The function
+should call Tkdnd.dnd_start(source, event), where 'source' is the
+object to be dragged, and 'event' is the event that invoked the call
+(the argument to your callback function). Even though this is a class
+instantiation, the returned instance should not be stored -- it will
+be kept alive automatically for the duration of the drag-and-drop.
+
+When a drag-and-drop is already in process for the Tk interpreter, the
+call is *ignored*; this normally averts starting multiple simultaneous
+dnd processes, e.g. because different button callbacks all
+dnd_start().
+
+The object is *not* necessarily a widget -- it can be any
+application-specific object that is meaningful to potential
+drag-and-drop targets.
+
+Potential drag-and-drop targets are discovered as follows. Whenever
+the mouse moves, and at the start and end of a drag-and-drop move, the
+Tk widget directly under the mouse is inspected. This is the target
+widget (not to be confused with the target object, yet to be
+determined). If there is no target widget, there is no dnd target
+object. If there is a target widget, and it has an attribute
+dnd_accept, this should be a function (or any callable object). The
+function is called as dnd_accept(source, event), where 'source' is the
+object being dragged (the object passed to dnd_start() above), and
+'event' is the most recent event object (generally a <Motion> event;
+it can also be <ButtonPress> or <ButtonRelease>). If the dnd_accept()
+function returns something other than None, this is the new dnd target
+object. If dnd_accept() returns None, or if the target widget has no
+dnd_accept attribute, the target widget's parent is considered as the
+target widget, and the search for a target object is repeated from
+there. If necessary, the search is repeated all the way up to the
+root widget. If none of the target widgets can produce a target
+object, there is no target object (the target object is None).
+
+The target object thus produced, if any, is called the new target
+object. It is compared with the old target object (or None, if there
+was no old target widget). There are several cases ('source' is the
+source object, and 'event' is the most recent event object):
+
+- Both the old and new target objects are None. Nothing happens.
+
+- The old and new target objects are the same object. Its method
+dnd_motion(source, event) is called.
+
+- The old target object was None, and the new target object is not
+None. The new target object's method dnd_enter(source, event) is
+called.
+
+- The new target object is None, and the old target object is not
+None. The old target object's method dnd_leave(source, event) is
+called.
+
+- The old and new target objects differ and neither is None. The old
+target object's method dnd_leave(source, event), and then the new
+target object's method dnd_enter(source, event) is called.
+
+Once this is done, the new target object replaces the old one, and the
+Tk mainloop proceeds. The return value of the methods mentioned above
+is ignored; if they raise an exception, the normal exception handling
+mechanisms take over.
+
+The drag-and-drop processes can end in two ways: a final target object
+is selected, or no final target object is selected. When a final
+target object is selected, it will always have been notified of the
+potential drop by a call to its dnd_enter() method, as described
+above, and possibly one or more calls to its dnd_motion() method; its
+dnd_leave() method has not been called since the last call to
+dnd_enter(). The target is notified of the drop by a call to its
+method dnd_commit(source, event).
+
+If no final target object is selected, and there was an old target
+object, its dnd_leave(source, event) method is called to complete the
+dnd sequence.
+
+Finally, the source object is notified that the drag-and-drop process
+is over, by a call to source.dnd_end(target, event), specifying either
+the selected target object, or None if no target object was selected.
+The source object can use this to implement the commit action; this is
+sometimes simpler than to do it in the target's dnd_commit(). The
+target's dnd_commit() method could then simply be aliased to
+dnd_leave().
+
+At any time during a dnd sequence, the application can cancel the
+sequence by calling the cancel() method on the object returned by
+dnd_start(). This will call dnd_leave() if a target is currently
+active; it will never call dnd_commit().
+
+"""
+
+
+import Tkinter
+
+
+# The factory function
+
+def dnd_start(source, event):
+ h = DndHandler(source, event)
+ if h.root:
+ return h
+ else:
+ return None
+
+
+# The class that does the work
+
+class DndHandler:
+
+ root = None
+
+ def __init__(self, source, event):
+ if event.num > 5:
+ return
+ root = event.widget._root()
+ try:
+ root.__dnd
+ return # Don't start recursive dnd
+ except AttributeError:
+ root.__dnd = self
+ self.root = root
+ self.source = source
+ self.target = None
+ self.initial_button = button = event.num
+ self.initial_widget = widget = event.widget
+ self.release_pattern = "<B%d-ButtonRelease-%d>" % (button, button)
+ self.save_cursor = widget['cursor'] or ""
+ widget.bind(self.release_pattern, self.on_release)
+ widget.bind("<Motion>", self.on_motion)
+ widget['cursor'] = "hand2"
+
+ def __del__(self):
+ root = self.root
+ self.root = None
+ if root:
+ try:
+ del root.__dnd
+ except AttributeError:
+ pass
+
+ def on_motion(self, event):
+ x, y = event.x_root, event.y_root
+ target_widget = self.initial_widget.winfo_containing(x, y)
+ source = self.source
+ new_target = None
+ while target_widget:
+ try:
+ attr = target_widget.dnd_accept
+ except AttributeError:
+ pass
+ else:
+ new_target = attr(source, event)
+ if new_target:
+ break
+ target_widget = target_widget.master
+ old_target = self.target
+ if old_target is new_target:
+ if old_target:
+ old_target.dnd_motion(source, event)
+ else:
+ if old_target:
+ self.target = None
+ old_target.dnd_leave(source, event)
+ if new_target:
+ new_target.dnd_enter(source, event)
+ self.target = new_target
+
+ def on_release(self, event):
+ self.finish(event, 1)
+
+ def cancel(self, event=None):
+ self.finish(event, 0)
+
+ def finish(self, event, commit=0):
+ target = self.target
+ source = self.source
+ widget = self.initial_widget
+ root = self.root
+ try:
+ del root.__dnd
+ self.initial_widget.unbind(self.release_pattern)
+ self.initial_widget.unbind("<Motion>")
+ widget['cursor'] = self.save_cursor
+ self.target = self.source = self.initial_widget = self.root = None
+ if target:
+ if commit:
+ target.dnd_commit(source, event)
+ else:
+ target.dnd_leave(source, event)
+ finally:
+ source.dnd_end(target, event)
+
+
+
+# ----------------------------------------------------------------------
+# The rest is here for testing and demonstration purposes only!
+
+class Icon:
+
+ def __init__(self, name):
+ self.name = name
+ self.canvas = self.label = self.id = None
+
+ def attach(self, canvas, x=10, y=10):
+ if canvas is self.canvas:
+ self.canvas.coords(self.id, x, y)
+ return
+ if self.canvas:
+ self.detach()
+ if not canvas:
+ return
+ label = Tkinter.Label(canvas, text=self.name,
+ borderwidth=2, relief="raised")
+ id = canvas.create_window(x, y, window=label, anchor="nw")
+ self.canvas = canvas
+ self.label = label
+ self.id = id
+ label.bind("<ButtonPress>", self.press)
+
+ def detach(self):
+ canvas = self.canvas
+ if not canvas:
+ return
+ id = self.id
+ label = self.label
+ self.canvas = self.label = self.id = None
+ canvas.delete(id)
+ label.destroy()
+
+ def press(self, event):
+ if dnd_start(self, event):
+ # where the pointer is relative to the label widget:
+ self.x_off = event.x
+ self.y_off = event.y
+ # where the widget is relative to the canvas:
+ self.x_orig, self.y_orig = self.canvas.coords(self.id)
+
+ def move(self, event):
+ x, y = self.where(self.canvas, event)
+ self.canvas.coords(self.id, x, y)
+
+ def putback(self):
+ self.canvas.coords(self.id, self.x_orig, self.y_orig)
+
+ def where(self, canvas, event):
+ # where the corner of the canvas is relative to the screen:
+ x_org = canvas.winfo_rootx()
+ y_org = canvas.winfo_rooty()
+ # where the pointer is relative to the canvas widget:
+ x = event.x_root - x_org
+ y = event.y_root - y_org
+ # compensate for initial pointer offset
+ return x - self.x_off, y - self.y_off
+
+ def dnd_end(self, target, event):
+ pass
+
+class Tester:
+
+ def __init__(self, root):
+ self.top = Tkinter.Toplevel(root)
+ self.canvas = Tkinter.Canvas(self.top, width=100, height=100)
+ self.canvas.pack(fill="both", expand=1)
+ self.canvas.dnd_accept = self.dnd_accept
+
+ def dnd_accept(self, source, event):
+ return self
+
+ def dnd_enter(self, source, event):
+ self.canvas.focus_set() # Show higlight border
+ x, y = source.where(self.canvas, event)
+ x1, y1, x2, y2 = source.canvas.bbox(source.id)
+ dx, dy = x2-x1, y2-y1
+ self.dndid = self.canvas.create_rectangle(x, y, x+dx, y+dy)
+ self.dnd_motion(source, event)
+
+ def dnd_motion(self, source, event):
+ x, y = source.where(self.canvas, event)
+ x1, y1, x2, y2 = self.canvas.bbox(self.dndid)
+ self.canvas.move(self.dndid, x-x1, y-y1)
+
+ def dnd_leave(self, source, event):
+ self.top.focus_set() # Hide highlight border
+ self.canvas.delete(self.dndid)
+ self.dndid = None
+
+ def dnd_commit(self, source, event):
+ self.dnd_leave(source, event)
+ x, y = source.where(self.canvas, event)
+ source.attach(self.canvas, x, y)
+
+def test():
+ root = Tkinter.Tk()
+ root.geometry("+1+1")
+ Tkinter.Button(command=root.quit, text="Quit").pack()
+ t1 = Tester(root)
+ t1.top.geometry("+1+60")
+ t2 = Tester(root)
+ t2.top.geometry("+120+60")
+ t3 = Tester(root)
+ t3.top.geometry("+240+60")
+ i1 = Icon("ICON1")
+ i2 = Icon("ICON2")
+ i3 = Icon("ICON3")
+ i1.attach(t1.canvas)
+ i2.attach(t2.canvas)
+ i3.attach(t3.canvas)
+ root.mainloop()
+
+if __name__ == '__main__':
+ test()