Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
79 lines (66 sloc) 5.18 KB
Drag and Drop
=============
.. note::
Versions of PyGObject < 3.0.3 contain a bug which does not allow drag
and drop to function correctly. Therefore a version of PyGObject >= 3.0.3 is
required for the following examples to work.
Setting up drag and drop between widgets consists of selecting a drag source
(the widget which the user starts the drag from) with the
:meth:`Gtk.Widget.drag_source_set` method, selecting a drag destination (the
widget which the user drops onto) with the :meth:`Gtk.Widget.drag_dest_set`
method and then handling the relevant signals on both widgets.
Instead of using :meth:`Gtk.Widget.drag_source_set` and
:meth:`Gtk.Widget.drag_dest_set` some specialised widgets require the use of
specific functions (such as :class:`Gtk.TreeView` and :class:`Gtk.IconView`).
A basic drag and drop only requires the source to connect to the "drag-data-get"
signal and the destination to connect to the "drag-data-received" signal. More
complex things such as specific drop areas and custom drag icons will require
you to connect to :ref:`additional signals <drag-signals>` and interact with
the :class:`Gdk.DragContext` object it supplies.
In order to transfer data between the source and destination, you must interact
with the :class:`Gtk.SelectionData` variable supplied in the
:ref:`"drag-data-get" <drag-signals>` and :ref:`"drag-data-received" <drag-signals>`
signals using the :class:`Gtk.SelectionData` get and set methods.
Target Entries
--------------
To allow the drag source and destination to know what data they are receiving and
sending, a common list of :class:`Gtk.TargetEntry's <Gtk.TargetEntry>` are required.
A :class:`Gtk.TargetEntry` describes a piece of data that will be sent by the drag
source and received by the drag destination.
There are two ways of adding :class:`Gtk.TargetEntry's <Gtk.TargetEntry>` to a
source and destination. If the drag and drop is simple and each target entry is
of a different type, you can use the group of methods :meth:`mentioned here
<Gtk.Widget.drag_source_add_text_targets>`.
If you require more than one type of data or wish to do more complex things with
the data, you will need to create the :class:`Gtk.TargetEntry's <Gtk.TargetEntry>`
using the :meth:`Gtk.TargetEntry.new` method.
.. _drag-signals:
Drag Source Signals
-------------------
+--------------------+--------------------------------------------------------------+----------------------------------------------------+
| Name | When it is emitted | Common Purpose |
+====================+==============================================================+====================================================+
| drag-begin | User starts a drag | Set-up drag icon |
+--------------------+--------------------------------------------------------------+----------------------------------------------------+
| drag-data-get | When drag data is requested by the destination | Transfer drag data from source to destination |
+--------------------+--------------------------------------------------------------+----------------------------------------------------+
| drag-data-delete | When a drag with the action Gdk.DragAction.MOVE is completed | Delete data from the source to complete the 'move' |
+--------------------+--------------------------------------------------------------+----------------------------------------------------+
| drag-end | When the drag is complete | Undo anything done in drag-begin |
+--------------------+--------------------------------------------------------------+----------------------------------------------------+
Drag Destination Signals
------------------------
+--------------------+--------------------------------------------------------------+----------------------------------------------------+
| Name | When it is emitted | Common Purpose |
+====================+==============================================================+====================================================+
| drag-motion | Drag icon moves over a drop area | Allow only certain areas to be dropped onto |
+--------------------+--------------------------------------------------------------+----------------------------------------------------+
| drag-drop | Icon is dropped onto a drag area | Allow only certain areas to be dropped onto |
+--------------------+--------------------------------------------------------------+----------------------------------------------------+
| drag-data-received | When drag data is received by the destination | Transfer drag data from source to destination |
+--------------------+--------------------------------------------------------------+----------------------------------------------------+
Example
-------
.. image:: ../images/drag_and_drop_example.png
.. literalinclude:: ../examples/drag_and_drop_example.py
:linenos:
You can’t perform that action at this time.