| 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` |