GNOME.org
 

[gtk/ebassi/gidocgen: 383/500] droptargetasync: Convert docs


commit b3f6e95d625ff3dc6fda14152fdd30fdaa4227a1
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Mar 1 01:33:06 2021 -0500

    droptargetasync: Convert docs

 gtk/gtkdroptargetasync.c | 138 +++++++++++++++++++++++------------------------
 1 file changed, 69 insertions(+), 69 deletions(-)
---
diff --git a/gtk/gtkdroptargetasync.c b/gtk/gtkdroptargetasync.c
index c14d307096..e9f443cf1d 100644
--- a/gtk/gtkdroptargetasync.c
+++ b/gtk/gtkdroptargetasync.c
@@ -35,41 +35,38 @@
 
 
 /**
- * SECTION:gtkdroptargetasync
- * @Short_description: Event controller to receive DND drops
- * @Title: GtkDropTargetAsync
- * @See_also: #GtkDropTarget
+ * GtkDropTargetAsync:
+ *
+ * `GtkDropTargetAsync` is an event controller to receive Drag-and-Drop
+ * operations, asynchronously.
  *
- * GtkDropTargetAsync is an auxiliary object that can be used to receive
- * Drag-and-Drop operations.  
  * It is the more complete but also more complex method of handling drop
- * operations compared to #GtkDropTarget and you should only use it if
- * #GtkDropTarget doesn't provide all the features you need.
+ * operations compared to [class@Gtk.DropTarget], and you should only use
+ * it if `GtkDropTarget` doesn't provide all the features you need.
  *
- * To use a #GtkDropTargetAsync to receive drops on a widget, you create
- * a #GtkDropTargetAsync object, configure which data formats and actions
- * you support, connect to its signals, and then attach
- * it to the widget with gtk_widget_add_controller().
+ * To use a `GtkDropTargetAsync` to receive drops on a widget, you create
+ * a `GtkDropTargetAsync` object, configure which data formats and actions
+ * you support, connect to its signals, and then attach it to the widget
+ * with [method@Gtk.Widget.add_controller].
  *
- * During a drag operation, the first signal that a GtkDropTargetAsync
- * emits is #GtkDropTargetAsync::accept, which is meant to determine
- * whether the target is a possible drop site for the ongoing drop.
- * The default handler for the ::accept signal accepts the drop
- * if it finds a compatible data format and an action that is supported
- * on both sides.
+ * During a drag operation, the first signal that a `GtkDropTargetAsync`
+ * emits is [signal@Gtk.DropTargetAsync::accept], which is meant to determine
+ * whether the target is a possible drop site for the ongoing drop. The
+ * default handler for the ::accept signal accepts the drop if it finds
+ * a compatible data format and an action that is supported on both sides.
  *
  * If it is, and the widget becomes a target, you will receive a
- * #GtkDropTargetAsync::drag-enter signal, followed by
- * #GtkDropTargetAsync::drag-motion signals as the pointer moves,
- * optionally a #GtkDropTargetAsync::drop signal when a drop happens,
- * and finally a #GtkDropTargetAsync::drag-leave signal when the pointer
- * moves off the widget.
+ * [signal@Gtk.DropTargetAsync::drag-enter] signal, followed by
+ * [signal@Gtk.DropTargetAsync::drag-motion] signals as the pointer moves,
+ * optionally a [signal@Gtk.DropTargetAsync::drop] signal when a drop happens,
+ * and finally a [signal@Gtk.DropTargetAsync::drag-leave] signal when the
+ * pointer moves off the widget.
  *
- * The ::drag-enter and ::drag-motion handler return a #GdkDragAction
+ * The ::drag-enter and ::drag-motion handler return a `GdkDragAction`
  * to update the status of the ongoing operation. The ::drop handler
  * should decide if it ultimately accepts the drop and if it does, it
  * should initiate the data transfer and finish the operation by calling
- * gdk_drop_finish().
+ * [method Gdk Drop.finish].
  *
  * Between the ::drag-enter and ::drag-leave signals the widget is a
  * current drop target, and will receive the %GTK_STATE_FLAG_DROP_ACTIVE
@@ -383,19 +380,19 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class)
   class->drop = gtk_drop_target_async_drop;
 
   /**
-   * GtkDropTargetAsync:actions:
+   * GtkDropTargetAsync:actions: (attributes org.gtk.Property.get=gtk_drop_target_async_get_actions 
org.gtk.Property.set=gtk_drop_target_async_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"), P_("Actions"),
                            GDK_TYPE_DRAG_ACTION, 0,
                            G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS | G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkDropTargetAsync:formats:
+   * GtkDropTargetAsync:formats: (attributes org.gtk.Property.get=gtk_drop_target_async_get_formats 
org.gtk.Property.set=gtk_drop_target_async_set_formats)
    *
-   * The #GdkContentFormats that determines the supported data formats
+   * The `GdkContentFormats` that determines the supported data formats.
    */
   properties[PROP_FORMATS] =
        g_param_spec_boxed ("formats", P_("Formats"), P_("Formats"),
@@ -406,16 +403,16 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class)
 
  /**
    * GtkDropTargetAsync::accept:
-   * @self: the #GtkDropTargetAsync
+   * @self: the `GtkDropTargetAsync`
    * @drop: the #GdkDrop
    *
-   * The ::accept signal is emitted on the drop site when a drop operation
-   * is about to begin.
+   * 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_async_reject() or
-   * ultimately by returning %FALSE from #GtkDropTargetAsync::drop.
+   * but may be rejected later via a call to [method@Gtk.DropTargetAsync.reject_drop]
+   * or ultimately by returning %FALSE from a [signal@Gtk.DropTargetAsync::drop]
+   * handler.
    *
    * The default handler for this signal decides whether to accept the drop
    * based on the formats provided by the @drop.
@@ -423,7 +420,7 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class)
    * If the decision whether the drop will be accepted or rejected needs
    * further processing, such as inspecting the data, this function should
    * return %TRUE and proceed as is @drop was accepted and if it decides to
-   * reject the drop later, it should call gtk_drop_target_async_reject_drop().
+   * reject the drop later, it should call [method@Gtk.DropTargetAsync.reject_drop].
    *
    * Returns: %TRUE if @drop is accepted
    */
@@ -439,15 +436,16 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class)
 
   /**
    * GtkDropTargetAsync::drag-enter:
-   * @self: the #GtkDropTargetAsync
+   * @self: the `GtkDropTargetAsync`
    * @drop: the #GdkDrop
    * @x: the x coordinate of the current pointer position
    * @y: the y coordinate of the current pointer position
    *
-   * The ::drag-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. 
+   * Returns: Preferred action for this drag operation.
    */
   signals[DRAG_ENTER] =
       g_signal_new (I_("drag-enter"),
@@ -461,15 +459,14 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class)
 
   /**
    * GtkDropTargetAsync::drag-motion:
-   * @self: the #GtkDropTargetAsync
+   * @self: the `GtkDropTargetAsync`
    * @drop: the #GdkDrop
    * @x: the x coordinate of the current pointer position
    * @y: the y coordinate of the current pointer position
    *
-   * The ::drag-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. 
+   * Returns: Preferred action for this drag operation.
    */
   signals[DRAG_MOTION] =
       g_signal_new (I_("drag-motion"),
@@ -483,12 +480,13 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class)
 
   /**
    * GtkDropTargetAsync::drag-leave:
-   * @self: the #GtkDropTargetAsync
+   * @self: the `GtkDropTargetAsync`
    * @drop: the #GdkDrop
    *
-   * The ::drag-leave signal is emitted on the drop site when the pointer
-   * leaves the widget. Its main purpose it to undo things done in
-   * #GtkDropTargetAsync::drag-enter.
+   * Emitted on the drop site when the pointer leaves the widget.
+   *
+   * Its main purpose it to undo things done in
+   * `GtkDropTargetAsync`::drag-enter.
    */
   signals[DRAG_LEAVE] =
       g_signal_new (I_("drag-leave"),
@@ -502,23 +500,25 @@ gtk_drop_target_async_class_init (GtkDropTargetAsyncClass *class)
 
   /**
    * GtkDropTargetAsync::drop:
-   * @self: the #GtkDropTargetAsync
+   * @self: the `GtkDropTargetAsync`
    * @drop: the #GdkDrop
    * @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 must ensure that gdk_drop_finish() is
-   * called to let the source know that the drop is done. The call to
-   * gdk_drop_finish() must only be done when all data has been received.
+   * accept the drop. The handler must ensure that [method Gdk Drop.finish]
+   * is called to let the source know that the drop is done. The call to
+   * [method Gdk Drop.finish] must only be done when all data has been received.
    *
-   * To receive the data, use one of the read functions provides by #GdkDrop
-   * such as gdk_drop_read_async() or gdk_drop_read_value_async().
+   * To receive the data, use one of the read functions provided by
+   * [class Gdk Drop] such as [method Gdk Drop.read_async] or
+   * [method Gdk Drop.read_value_async].
    *
    * Returns: whether the drop is accepted at the given pointer position
    */
@@ -543,9 +543,9 @@ gtk_drop_target_async_init (GtkDropTargetAsync *self)
  * @formats: (nullable) (transfer full): the supported data formats
  * @actions: the supported actions
  *
- * Creates a new #GtkDropTargetAsync object.
+ * Creates a new `GtkDropTargetAsync` object.
  *
- * Returns: the new #GtkDropTargetAsync
+ * Returns: the new `GtkDropTargetAsync`
  */
 GtkDropTargetAsync *
 gtk_drop_target_async_new (GdkContentFormats *formats,
@@ -564,8 +564,8 @@ gtk_drop_target_async_new (GdkContentFormats *formats,
 }
 
 /**
- * gtk_drop_target_async_set_formats:
- * @self: a #GtkDropTargetAsync
+ * gtk_drop_target_async_set_formats: (attributes org.gtk.Method.set_property=formats)
+ * @self: a `GtkDropTargetAsync`
  * @formats: (nullable): the supported data formats or %NULL for
  *     any format.
  *
@@ -592,8 +592,8 @@ gtk_drop_target_async_set_formats (GtkDropTargetAsync *self,
 }
 
 /**
- * gtk_drop_target_async_get_formats:
- * @self: a #GtkDropTargetAsync
+ * gtk_drop_target_async_get_formats: (attributes org.gtk.Method.get_property=formats)
+ * @self: a `GtkDropTargetAsync`
  *
  * Gets the data formats that this drop target accepts.
  *
@@ -610,8 +610,8 @@ gtk_drop_target_async_get_formats (GtkDropTargetAsync *self)
 }
 
 /**
- * gtk_drop_target_async_set_actions:
- * @self: a #GtkDropTargetAsync
+ * gtk_drop_target_async_set_actions: (attributes org.gtk.Method.set_property=actions)
+ * @self: a `GtkDropTargetAsync`
  * @actions: the supported actions
  *
  * Sets the actions that this drop target supports.
@@ -631,8 +631,8 @@ gtk_drop_target_async_set_actions (GtkDropTargetAsync *self,
 }
 
 /**
- * gtk_drop_target_async_get_actions:
- * @self: a #GtkDropTargetAsync
+ * gtk_drop_target_async_get_actions: (attributes org.gtk.Method.get_property=actions)
+ * @self: a `GtkDropTargetAsync`
  *
  * Gets the actions that this drop target supports.
  *
@@ -648,7 +648,7 @@ gtk_drop_target_async_get_actions (GtkDropTargetAsync *self)
 
 /**
  * gtk_drop_target_async_reject_drop:
- * @self: a #GtkDropTargetAsync
+ * @self: a `GtkDropTargetAsync`
  * @drop: the #GdkDrop of an ongoing drag operation
  *
  * Sets the @drop as not accepted on this drag site.
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]