[gtk/dnd-fixes] docs: Add a section about Drag-and-Drop



commit 4f6d3195013a06efd2e5b8f1111f3d9149fff1ba
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Jun 19 12:23:27 2021 -0700

    docs: Add a section about Drag-and-Drop

 docs/reference/gtk/drag-and-drop.md | 54 +++++++++++++++++++++++++++++++++++++
 docs/reference/gtk/gtk4.toml.in     |  1 +
 2 files changed, 55 insertions(+)
---
diff --git a/docs/reference/gtk/drag-and-drop.md b/docs/reference/gtk/drag-and-drop.md
new file mode 100644
index 0000000000..84bf7964bb
--- /dev/null
+++ b/docs/reference/gtk/drag-and-drop.md
@@ -0,0 +1,54 @@
+Title: Drag-and-Drop in GTK
+
+Drag-and-Drop (DND) is a user interaction pattern where users drag a UI element
+from one place to another, either inside a single application or between
+different application windows.
+
+When the element is 'dropped', data is transferred from the source to the
+destination, according to the drag action that is negotiated between both
+sides. Most commonly, that is a _copy_, but it can also be a _move_ or a
+_link_, depending on the kind of data and how the drag operation has been
+set up.
+
+This chapter gives an overview over how Drag-and-Drop is handled with event
+controllers in GTK.
+
+## Drag sources
+
+To make data available via DND, you create a [class@Gtk.DragSource]. Drag sources
+are event controllers, which initiate a Drag-and-Drop operation when the user clicks
+and drags the widget.
+
+A drag source can be set up ahead of time, with the desired drag action(s) and the data
+to be transferred. But it is also possible to provide the data when a drag operation
+is about to begin, by connecting to the [signal@Gtk.DragSource.prepare] signal.
+
+The GtkDragSource emits the [signal Gtk DragSource drag-begin] signal when the DND
+operation starts, and the [signal Gtk DragSource drag-end] signal when it is done.
+But it is not normally necessary to handle these signals. One case in which a ::drag-end
+handler is necessary is to implement `GDK_ACTION_MOVE`.
+
+## Drop targets
+
+To receive data via DND, you create a [class@Gtk.DropTarget], and tell it what kind of
+data to accept. You need to connect to the [signal Gtk DropTarget drop] signal to receive
+the data when a DND operation occurs.
+
+While a DND operation is ongoing, GTK provides updates when the pointer moves over
+the widget to which the drop target is associated. The [signal@Gtk.DropTarget.enter],
+[signal@Gtk.DropTarget.leave] and [signal@Gtk.DropTarget.motion] signals get emitted
+for this purpose.
+
+GtkDropTarget provides a simple API, and only provides the data when it has been completely
+transferred. If you need to handle the data transfer yourself (for example to provide progress
+information during the transfer), you can use the more complicated [class@Gtk.DropTargetAsync].
+
+## Other considerations
+
+It is sometimes necessary to update the UI of the destination while a DND operation is ongoing,
+say to scroll or expand a view, or to switch pages. Typically, such UI changes are triggered
+by hovering over the widget in question.
+
+[class@Gtk.DropControllerMotion] is an event controller that can help with implementing such
+behaviors. It is very similar to [class@Gtk.EventControllerMotion], but provides events during
+a DND operation.
diff --git a/docs/reference/gtk/gtk4.toml.in b/docs/reference/gtk/gtk4.toml.in
index 2a0d57e922..e1cc9f34cb 100644
--- a/docs/reference/gtk/gtk4.toml.in
+++ b/docs/reference/gtk/gtk4.toml.in
@@ -57,6 +57,7 @@ content_files = [
   "initialization.md",
   "actions.md",
   "input-handling.md",
+  "drag-and-drop.md",
   "drawing-model.md",
   "css-overview.md",
   "css-properties.md",


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]