Debian Codegraph @

Doc/library/tkinter.dnd.rst

raw
1 :mod:`!tkinter.dnd` --- Drag and drop support
2 =============================================
3
4 .. module:: tkinter.dnd
5 :synopsis: Tkinter drag-and-drop interface
6
7 **Source code:** :source:`Lib/tkinter/dnd.py`
8
9 --------------
10
11 .. note:: This is experimental and due to be deprecated when it is replaced
12 with the Tk DND.
13
14 The :mod:`tkinter.dnd` module provides drag-and-drop support for objects within
15 a single application, within the same window or between windows. To enable an
16 object to be dragged, you must create an event binding for it that starts the
17 drag-and-drop process. Typically, you bind a ButtonPress event to a callback
18 function that you write (see :ref:`Bindings-and-Events`). The function should
19 call :func:`dnd_start`, where *source* is the object to be dragged, and *event*
20 is the event that invoked the call (the argument to your callback function).
21
22 Selection of a target object occurs as follows:
23
24 #. Top-down search of the area under the mouse for a target widget:
25
26 * the target widget should have a callable *dnd_accept* attribute;
27 * if *dnd_accept* is not present or returns ``None``,
28 the search moves to the parent widget;
29 * if no target widget is found, the target object is ``None``.
30
31 #. Call to ``<old_target>.dnd_leave(source, event)``.
32 #. Call to ``<new_target>.dnd_enter(source, event)``.
33 #. Call to ``<target>.dnd_commit(source, event)`` to notify of the drop.
34 #. Call to ``<source>.dnd_end(target, event)`` to signal the end of drag-and-drop.
35
36
37 .. class:: DndHandler(source, event)
38
39 The *DndHandler* class handles drag-and-drop events tracking Motion and
40 ButtonRelease events on the root of the event widget.
41
42 .. method:: cancel(event=None)
43
44 Cancel the drag-and-drop process.
45
46 .. method:: finish(event, commit=0)
47
48 Execute end of drag-and-drop functions.
49
50 .. method:: on_motion(event)
51
52 Inspect area below mouse for target objects while a drag
53 is performed.
54
55 .. method:: on_release(event)
56
57 Signal end of drag when the release pattern is triggered.
58
59 .. function:: dnd_start(source, event)
60
61 Factory function for the drag-and-drop process.
62 Return the :class:`DndHandler` instance managing the drag, or ``None`` if a
63 drag could not be started.
64
65 .. seealso::
66
67 :ref:`Bindings-and-Events`