Merge branch 'ebassi/docs-for-master' into 'master'

Ebassi/docs for master

See merge request GNOME/gtk!2983

docs/reference/gtk/migrating-3to4.md

@@ -1062,7 +1062,7 @@ to start a drag manually, call gdk_drag_begin().
 The ::drag-data-get signal has been replaced by the #GtkDragSource::prepare
 signal, which returns a #GdkContentProvider for the drag operation.
 
-The destination-side Drag-and-Drop  apis in GTK 4 have also been changed
+The destination-side Drag-and-Drop API in GTK 4 have also been changed
 to use an event controller, #GtkDropTarget. Instead of calling
 gtk_drag_dest_set() and connecting to #GtkWidget signals, you create
 a #GtkDropTarget object, attach it to the widget with

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,

gtk/gtkdroptarget.c

@@ -47,7 +47,46 @@
  * The most basic way to use a #GtkDropTarget to receive drops on a
  * widget is to create it via gtk_drop_target_new() passing in the
  * #GType of the data you want to receive and connect to the
- * GtkDropTarget::drop signal to receive the data.
+ * GtkDropTarget::drop signal to receive the data:
+ *
+ * |[<!-- language="C" -->
+ * static gboolean
+ * on_drop (GtkDropTarget *target,
+ *          const GValue  *value,
+ *          double         x,
+ *          double         y,
+ *          gpointer       data)
+ * {
+ *   MyWidget *self = data;
+ *
+ *   // Call the appropriate setter depending on the type of data
+ *   // that we received
+ *   if (G_VALUE_HOLDS (value, G_TYPE_FILE))
+ *     my_widget_set_file (self, g_value_get_object (value));
+ *   else if (G_VALUE_HOLDS (value, GDK_TYPE_PIXBUF))
+ *     my_widget_set_pixbuf (self, g_value_get_object (value));
+ *   else
+ *     return FALSE;
+ *
+ *   return TRUE;
+ * }
+ *
+ * static void
+ * my_widget_init (MyWidget *self)
+ * {
+ *   GtkDropTarget *target =
+ *     gtk_drop_target_new (G_TYPE_INVALID, GDK_ACTION_COPY);
+ *
+ *   // This widget accepts two types of drop types: GFile objects
+ *   // and GdkPixbuf objects
+ *   gtk_drop_target_set_gtypes (target, (GTypes [2]) {
+ *     G_TYPE_FILE,
+ *     GDK_TYPE_PIXBUF,
+ *   }, 2);
+ *
+ *   gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (target));
+ * }
+ * ]|
  *
  * #GtkDropTarget supports more options, such as:
  *