GNOME.org
 

[gtk/ebassi/gidocgen: 349/465] droptarget: Convert docs


commit 5d99fad0c7d25c312e0a6e66fd9c6338268a2e12
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Mar 1 01:32:55 2021 -0500

    droptarget: Convert docs

 gtk/gtkdroptarget.c | 217 +++++++++++++++++++++++++++-------------------------
 1 file changed, 112 insertions(+), 105 deletions(-)
---
diff --git a/gtk/gtkdroptarget.c b/gtk/gtkdroptarget.c
index 3e2a3a8103..bd6002422a 100644
--- a/gtk/gtkdroptarget.c
+++ b/gtk/gtkdroptarget.c
@@ -36,20 +36,16 @@
 
 
 /**
- * SECTION:gtkdroptarget
- * @Short_description: Event controller to receive DND drops
- * @Title: GtkDropTarget
- * @See_also: #GdkDrop, #GtkDropTargetAsync
+ * GtkDropTarget:
  *
- * GtkDropTarget is an event controller implementing a simple way to
- * receive Drag-and-Drop operations.
+ * `GtkDropTarget` is an event controller to receive Drag-and-Drop operations.
  *
- * 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:
+ * The most basic way to use a `GtkDropTarget` to receive drops on a
+ * widget is to create it via [ctor Gtk DropTarget new], passing in the
+ * `GType` of the data you want to receive and connect to the
+ * [signal@Gtk.DropTarget::drop] signal to receive the data:
  *
- * |[<!-- language="C" -->
+ * ```c
  * static gboolean
  * on_drop (GtkDropTarget *target,
  *          const GValue  *value,
@@ -86,28 +82,32 @@
  *
  *   gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (target));
  * }
- * ]|
+ * ```
  *
- * #GtkDropTarget supports more options, such as:
+ * `GtkDropTarget` supports more options, such as:
  *
- *  * rejecting potential drops via the #GtkDropTarget::accept signal
- *    and the gtk_drop_target_reject() function to let other drop
+ *  * rejecting potential drops via the [signal@Gtk.DropTarget::accept] signal
+ *    and the [method@Gtk.DropTarget.reject] function to let other drop
  *    targets handle the drop
  *  * tracking an ongoing drag operation before the drop via the
- *    #GtkDropTarget::enter, #GtkDropTarget::motion and
- *    #GtkDropTarget::leave signals
+ *    [signal@Gtk.DropTarget::enter], [signal@Gtk.DropTarget::motion] and
+ *    [signal@Gtk.DropTarget::leave] signals
  *  * configuring how to receive data by setting the
- *    #GtkDropTarget:preload property and listening for its availability
- *    via the #GtkDropTarget:value property
+ *    [property@Gtk.DropTarget:preload] property and listening for its
+ *    availability via the [property@Gtk.DropTarget:value] property
  *
- * However, #GtkDropTarget is ultimately modeled in a synchronous way
- * and only supports data transferred via #GType.  
- * If you want full control over an ongoing drop, the #GtkDropTargetAsync
- * object gives you this ability.
+ * However, `GtkDropTarget` is ultimately modeled in a synchronous way
+ * and only supports data transferred via `GType`. If you want full control
+ * over an ongoing drop, the [class@Gtk.DropTargetAsync] object gives you
+ * this ability.
  *
  * While a pointer is dragged over the drop target's widget and the drop
  * has not been rejected, that widget will receive the
  * %GTK_STATE_FLAG_DROP_ACTIVE state, which can be used to style the widget.
+ *
+ * If you are not interested in receiving the drop, but just want to update
+ * UI state during a Drag-and-Drop operation (e.g. switching tabs), you can
+ * use [class@Gtk.DropControllerMotion].
  */
 
 struct _GtkDropTarget
@@ -608,10 +608,10 @@ gtk_drop_target_class_init (GtkDropTargetClass *class)
   class->drop = gtk_drop_target_drop;
 
   /**
-   * GtkDropTarget:actions:
+   * GtkDropTarget:actions: (attributes org.gtk.Property.get=gtk_drop_target_get_actions 
org.gtk.Property.set=gtk_drop_target_set_actions)
    *
-   * The #GdkDragActions that this drop target supports
-   */ 
+   * The `GdkDragActions` that this drop target supports.
+   */
   properties[PROP_ACTIONS] =
        g_param_spec_flags ("actions",
                            P_("Actions"),
@@ -620,9 +620,9 @@ gtk_drop_target_class_init (GtkDropTargetClass *class)
                            G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS | G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkDropTarget:drop:
+   * GtkDropTarget:drop: (attributes org.gtk.Property.get=gtk_drop_target_get_drop)
    *
-   * The #GdkDrop that is currently being performed
+   * The `GdkDrop` that is currently being performed.
    */
   properties[PROP_DROP] =
        g_param_spec_object ("drop",
@@ -632,9 +632,9 @@ gtk_drop_target_class_init (GtkDropTargetClass *class)
                             GTK_PARAM_READABLE);
 
   /**
-   * GtkDropTarget:formats:
+   * GtkDropTarget:formats: (attributes org.gtk.Property.get=gtk_drop_target_get_formats)
    *
-   * The #GdkContentFormats that determine the supported data formats
+   * The `GdkContentFormats` that determine the supported data formats.
    */
   properties[PROP_FORMATS] =
        g_param_spec_boxed ("formats",
@@ -644,7 +644,7 @@ gtk_drop_target_class_init (GtkDropTargetClass *class)
                            GTK_PARAM_READABLE);
 
   /**
-   * GtkDropTarget:preload:
+   * GtkDropTarget:preload: (attributes org.gtk.Property.get=gtk_drop_target_get_preload 
org.gtk.Property.set=gtk_drop_target_set_preload)
    *
    * Whether the drop data should be preloaded when the pointer is only
    * hovering over the widget but has not been released.
@@ -653,15 +653,16 @@ gtk_drop_target_class_init (GtkDropTargetClass *class)
    * drop at the cost of loading more data.
    *
    * The default value for this property is %FALSE to avoid downloading
-   * huge amounts of data by accident.  
+   * huge amounts of data by accident.
+   *
    * For example, if somebody drags a full document of gigabytes of text
    * from a text editor across a widget with a preloading drop target,
    * this data will be downloaded, even if the data is ultimately dropped
    * elsewhere.
    *
    * For a lot of data formats, the amount of data is very small (like
-   * %GDK_TYPE_RGBA), so enabling this property does not hurt at all.  
-   * And for local-only drag'n'drop operations, no data transfer is done,
+   * %GDK_TYPE_RGBA), so enabling this property does not hurt at all.
+   * And for local-only Drag-and-Drop operations, no data transfer is done,
    * so enabling it there is free.
    */
   properties[PROP_PRELOAD] =
@@ -672,14 +673,17 @@ gtk_drop_target_class_init (GtkDropTargetClass *class)
                              G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS | G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkDropTarget:value:
+   * GtkDropTarget:value: (attributes org.gtk.Property.get=gtk_drop_target_get_value)
+   *
+   * The value for this drop operation.
    *
-   * The value for this drop operation or %NULL if the data has not been
-   * loaded yet or no drop operation is going on.
+   * This is %NULL if the data has not been loaded yet or no drop
+   * operation is going on.
    *
-   * Data may be available before the #GtkDropTarget::drop signal gets emitted -
-   * for example when the #GtkDropTarget:preload property is set.
-   * You can use the #GObject::notify signal to be notified of available data.
+   * Data may be available before the [signal@Gtk.DropTarget::drop]
+   * signal gets emitted - for example when the [property@Gtk.DropTarget:preload]
+   * property is set. You can use the ::notify signal to be notified
+   * of available data.
    */
   properties[PROP_VALUE] =
        g_param_spec_boxed ("value",
@@ -692,24 +696,25 @@ gtk_drop_target_class_init (GtkDropTargetClass *class)
 
  /**
    * GtkDropTarget::accept:
-   * @self: the #GtkDropTarget
-   * @drop: the #GdkDrop
+   * @self: the `GtkDropTarget`
+   * @drop: the `GdkDrop`
+   *
+   * Emitted on the drop site when a drop operation is about to begin.
    *
-   * The ::accept signal is emitted on the drop site when a drop operation
-   * is about to begin.
    * If the drop is not accepted, %FALSE will be returned and the drop target
    * will ignore the drop. If %TRUE is returned, the drop is accepted for now
-   * but may be rejected later via a call to gtk_drop_target_reject() or
-   * ultimately by returning %FALSE from #GtkDropTarget::drop.
+   * but may be rejected later via a call to [method@Gtk.DropTarget.reject]
+   * or ultimately by returning %FALSE from a [signal@Gtk.DropTarget::drop]
+   * handler.
    *
    * The default handler for this signal decides whether to accept the drop
    * based on the formats provided by the @drop.
    *
    * If the decision whether the drop will be accepted or rejected depends
-   * on the data, this function should return %TRUE, the #GtkDropTarget:preload
-   * property should be set and the value should be inspected via the
-   * #GObject::notify:value signal, calling gtk_drop_target_reject() if
-   * required.
+   * on the data, this function should return %TRUE, the
+   * [property@Gtk.DropTarget:preload] property should be set and the value
+   * should be inspected via the ::notify:value signal, calling
+   * [method@Gtk.DropTarget.reject] if required.
    *
    * Returns: %TRUE if @drop is accepted
    */
@@ -725,15 +730,16 @@ gtk_drop_target_class_init (GtkDropTargetClass *class)
 
   /**
    * GtkDropTarget::enter:
-   * @self: the #GtkDropTarget
+   * @self: the `GtkDropTarget`
    * @x: the x coordinate of the current pointer position
    * @y: the y coordinate of the current pointer position
    *
-   * The ::enter signal is emitted on the drop site when the pointer
-   * enters the widget. It can be used to set up custom highlighting.
+   * Emitted on the drop site when the pointer enters the widget.
+   *
+   * It can be used to set up custom highlighting.
    *
-   * Returns: Preferred action for this drag operation or 0 if dropping is not
-   *     supported at the current @x,@y location.
+   * Returns: Preferred action for this drag operation or 0 if
+   *   dropping is not supported at the current @x,@y location.
    */
   signals[ENTER] =
       g_signal_new (I_("enter"),
@@ -747,15 +753,14 @@ gtk_drop_target_class_init (GtkDropTargetClass *class)
 
   /**
    * GtkDropTarget::motion:
-   * @self: the #GtkDropTarget
+   * @self: the `GtkDropTarget`
    * @x: the x coordinate of the current pointer position
    * @y: the y coordinate of the current pointer position
    *
-   * The ::motion signal is emitted while the pointer is moving
-   * over the drop target.
+   * Emitted while the pointer is moving over the drop target.
    *
-   * Returns: Preferred action for this drag operation or 0 if dropping is not
-   *     supported at the current @x,@y location.
+   * Returns: Preferred action for this drag operation or 0 if
+   *   dropping is not supported at the current @x,@y location.
    */
   signals[MOTION] =
       g_signal_new (I_("motion"),
@@ -769,11 +774,12 @@ gtk_drop_target_class_init (GtkDropTargetClass *class)
 
   /**
    * GtkDropTarget::leave:
-   * @self: the #GtkDropTarget
+   * @self: the `GtkDropTarget`
    *
-   * The ::leave signal is emitted on the drop site when the pointer
-   * leaves the widget. Its main purpose it to undo things done in
-   * #GtkDropTarget::enter.
+   * Emitted on the drop site when the pointer leaves the widget.
+   *
+   * Its main purpose it to undo things done in
+   * [signal@Gtk.DropTarget::enter].
    */
   signals[LEAVE] =
       g_signal_new (I_("leave"),
@@ -786,15 +792,16 @@ gtk_drop_target_class_init (GtkDropTargetClass *class)
 
   /**
    * GtkDropTarget::drop:
-   * @self: the #GtkDropTarget
+   * @self: the `GtkDropTarget`
    * @value: the #GValue being dropped
    * @x: the x coordinate of the current pointer position
    * @y: the y coordinate of the current pointer position
    *
-   * The ::drop signal is emitted on the drop site when the user drops
-   * the data onto the widget. The signal handler must determine whether
-   * the pointer position is in a drop zone or not. If it is not in a drop
-   * zone, it returns %FALSE and no further processing is necessary.
+   * Emitted on the drop site when the user drops the data onto the widget.
+   *
+   * The signal handler must determine whether the pointer position is in
+   * a drop zone or not. If it is not in a drop zone, it returns %FALSE
+   * and no further processing is necessary.
    *
    * Otherwise, the handler returns %TRUE. In this case, this handler will
    * accept the drop. The handler is responsible for rading the given @value
@@ -824,13 +831,13 @@ gtk_drop_target_init (GtkDropTarget *self)
  * @type: The supported type or %G_TYPE_INVALID
  * @actions: the supported actions
  *
- * Creates a new #GtkDropTarget object.
+ * Creates a new `GtkDropTarget` object.
  *
  * If the drop target should support more than 1 type, pass
  * %G_TYPE_INVALID for @type and then call
- * gtk_drop_target_set_gtypes().
+ * [method@Gtk.DropTarget.set_gtypes].
  *
- * Returns: the new #GtkDropTarget
+ * Returns: the new `GtkDropTarget`
  */
 GtkDropTarget *
 gtk_drop_target_new (GType         type,
@@ -849,8 +856,8 @@ gtk_drop_target_new (GType         type,
 }
 
 /**
- * gtk_drop_target_get_formats:
- * @self: a #GtkDropTarget
+ * gtk_drop_target_get_formats: (attributes org.gtk.Method.get_property=formats)
+ * @self: a `GtkDropTarget`
  *
  * Gets the data formats that this drop target accepts.
  *
@@ -868,13 +875,13 @@ gtk_drop_target_get_formats (GtkDropTarget *self)
 
 /**
  * gtk_drop_target_set_gtypes:
- * @self: a #GtkDropTarget
+ * @self: a `GtkDropTarget`
  * @types: (nullable) (transfer none) (array length=n_types):
  *     all supported #GTypes that can be dropped
  * @n_types: number of @types
  *
- * Sets the supported #GTypes for this drop target.
- **/
+ * Sets the supported `GTypes` for this drop target.
+ */
 void
 gtk_drop_target_set_gtypes (GtkDropTarget *self,
                             GType         *types,
@@ -899,17 +906,18 @@ gtk_drop_target_set_gtypes (GtkDropTarget *self,
 
 /**
  * gtk_drop_target_get_gtypes:
- * @self: a #GtkDropTarget
+ * @self: a `GtkDropTarget`
  * @n_types: (out) (optional): optional pointer to take the
  *     number of #GTypes contained in the return value
  *
- * Gets the list of supported #GTypes for @self. If no type have been set,
- * %NULL will be returned.
+ * Gets the list of supported `GTypes` for @self.
+ *
+ * If no type have been set, %NULL will be returned.
  *
  * Returns: (transfer none) (nullable) (array length=n_types):
- *      %G_TYPE_INVALID-terminated array of types included in @formats or
- *      %NULL if none.
- **/
+ *   %G_TYPE_INVALID-terminated array of types included in
+ *   @formats or %NULL if none.
+ */
 const GType *
 gtk_drop_target_get_gtypes (GtkDropTarget *self,
                             gsize         *n_types)
@@ -920,8 +928,8 @@ gtk_drop_target_get_gtypes (GtkDropTarget *self,
 }
 
 /**
- * gtk_drop_target_set_actions:
- * @self: a #GtkDropTarget
+ * gtk_drop_target_set_actions: (attributes org.gtk.Method.set_property=actions)
+ * @self: a `GtkDropTarget`
  * @actions: the supported actions
  *
  * Sets the actions that this drop target supports.
@@ -941,8 +949,8 @@ gtk_drop_target_set_actions (GtkDropTarget *self,
 }
 
 /**
- * gtk_drop_target_get_actions:
- * @self: a #GtkDropTarget
+ * gtk_drop_target_get_actions: (attributes org.gtk.Method.get_property=actions)
+ * @self: a `GtkDropTarget`
  *
  * Gets the actions that this drop target supports.
  *
@@ -957,12 +965,12 @@ gtk_drop_target_get_actions (GtkDropTarget *self)
 }
 
 /**
- * gtk_drop_target_set_preload:
- * @self: a #GtkDropTarget
+ * gtk_drop_target_set_preload: (attributes org.gtk.Method.set_property=preload)
+ * @self: a `GtkDropTarget`
  * @preload: %TRUE to preload drop data
  *
- * Sets the GtkDropTarget:preload property.
- **/
+ * Sets whether data should be preloaded on hover.
+ */
 void
 gtk_drop_target_set_preload (GtkDropTarget *self,
                              gboolean       preload)
@@ -978,10 +986,10 @@ gtk_drop_target_set_preload (GtkDropTarget *self,
 }
 
 /**
- * gtk_drop_target_get_preload:
- * @self: a #GtkDropTarget
+ * gtk_drop_target_get_preload: (attributes org.gtk.Method.get_property=preload)
+ * @self: a `GtkDropTarget`
  *
- * Gets the value of the GtkDropTarget:preload property.
+ * Gets whether data should be preloaded on hover.
  *
  * Returns: %TRUE if drop data should be preloaded
  */
@@ -994,15 +1002,15 @@ gtk_drop_target_get_preload (GtkDropTarget *self)
 }
 
 /**
- * gtk_drop_target_get_drop:
- * @self: a #GtkDropTarget
+ * gtk_drop_target_get_drop: (attributes org.gtk.Method.get_property=drop)
+ * @self: a `GtkDropTarget`
  *
  * Gets the currently handled drop operation.
  *
  * If no drop operation is going on, %NULL is returned.
  *
  * Returns: (nullable) (transfer none): The current drop
- **/
+ */
 GdkDrop *
 gtk_drop_target_get_drop (GtkDropTarget *self)
 {
@@ -1012,13 +1020,13 @@ gtk_drop_target_get_drop (GtkDropTarget *self)
 }
 
 /**
- * gtk_drop_target_get_value:
- * @self: a #GtkDropTarget
+ * gtk_drop_target_get_value: (attributes org.gtk.Method.get_property=value)
+ * @self: a `GtkDropTarget`
  *
- * Gets the value of the GtkDropTarget:value property.
+ * Gets the current drop data, as a `GValue`.
  *
  * Returns: (nullable) (transfer none): The current drop data
- **/
+ */
 const GValue *
 gtk_drop_target_get_value (GtkDropTarget *self)
 {
@@ -1032,12 +1040,12 @@ gtk_drop_target_get_value (GtkDropTarget *self)
 
 /**
  * gtk_drop_target_reject:
- * @self: a #GtkDropTarget
+ * @self: a `GtkDropTarget`
  *
  * Rejects the ongoing drop operation.
  *
- * If no drop operation is ongoing - when GdkDropTarget:drop
- * returns %NULL - this function does nothing.
+ * If no drop operation is ongoing, i.e when [property@Gtk.DropTarget:drop]
+ * is %NULL, this function does nothing.
  *
  * This function should be used when delaying the decision
  * on whether to accept a drag or not until after reading
@@ -1053,4 +1061,3 @@ gtk_drop_target_reject (GtkDropTarget *self)
 
   gtk_drop_target_end_drop (self);
 }
-
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]