From b9bcdbbfdc0a1ef3ecdb293ca5e8181453319487 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Mon, 21 Dec 2020 17:03:59 +0000
Subject: [PATCH] docs: Add examples of GtkDragSource use

The description is a bit terse; we should help out application
developers some more.
---
 gtk/gtkdragsource.c | 54 ++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 51 insertions(+), 3 deletions(-)

diff --git a/gtk/gtkdragsource.c b/gtk/gtkdragsource.c
index ca69d15ffe..98b96c7594 100644
--- a/gtk/gtkdragsource.c
+++ b/gtk/gtkdragsource.c
@@ -55,15 +55,63 @@
  * source must be added to a widget as an event controller, using
  * gtk_widget_add_controller().
  *
+ * |[<!-- language="C" -->
+ * static void
+ * my_widget_init (MyWidget *self)
+ * {
+ *   GtkDragSource *drag_source = gtk_drag_source_new ();
+ *
+ *   g_signal_connect (drag_source, "prepare", G_CALLBACK (on_drag_prepare), self);
+ *   g_signal_connect (drag_source, "drag-begin", G_CALLBACK (on_drag_begin), self);
+ *
+ *   gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (drag_source));
+ * }
+ * ]|
+ *
  * Setting up the content provider and icon ahead of time only
  * makes sense when the data does not change. More commonly, you
  * will want to set them up just in time. To do so, #GtkDragSource
  * has #GtkDragSource::prepare and #GtkDragSource::drag-begin signals.
+ *
  * The ::prepare signal is emitted before a drag is started, and
  * can be used to set the content provider and actions that the
- * drag should be started with. The ::drag-begin signal is emitted
- * after the #GdkDrag object has been created, and can be used
- * to set up the drag icon.
+ * drag should be started with.
+ *
+ * |[<!-- language="C" -->
+ * static GdkContentProvider *
+ * on_drag_prepare (GtkDragSource *source,
+ *                  double         x,
+ *                  double         y,
+ *                  MyWidget      *self)
+ * {
+ *   // This widget supports two types of content: GFile objects
+ *   // and GdkPixbuf objects; GTK will handle the serialization
+ *   // of these types automatically
+ *   GFile *file = my_widget_get_file (self);
+ *   GdkPixbuf *pixbuf = my_widget_get_pixbuf (self);
+ *
+ *   return gdk_content_provider_new_union ((GdkContentProvider *[2]) {
+ *       gdk_content_provider_new_typed (G_TYPE_FILE, file),
+ *       gdk_content_provider_new_typed (GDK_TYPE_PIXBUF, pixbuf),
+ *     }, 2);
+ * }
+ * ]|
+ *
+ * The ::drag-begin signal is emitted after the #GdkDrag object has
+ * been created, and can be used to set up the drag icon.
+ *
+ * |[<!-- language="C" -->
+ * static void
+ * on_drag_begin (GtkDragSource *source,
+ *                GtkDrag       *drag,
+ *                MyWidget      *self)
+ * {
+ *   // Set the widget as the drag icon
+ *   GdkPaintable *paintable = gtk_widget_paintable_new (GTK_WIDGET (self));
+ *   gtk_drag_source_set_icon (source, paintable, 0, 0);
+ *   g_object_unref (paintable);
+ * }
+ * ]|
  *
  * During the DND operation, GtkDragSource emits signals that
  * can be used to obtain updates about the status of the operation,