[gtk/ebassi/gidocgen: 199/471] paned: Convert docs

From: Emmanuele Bassi <ebassi src gnome org>
To: commits-list gnome org
Cc:
Subject: [gtk/ebassi/gidocgen: 199/471] paned: Convert docs
Date: Mon, 8 Mar 2021 18:23:19 +0000 (UTC)

commit 2ae0b569d1ded59bf1d765c192396d9f55dc6b05
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Feb 26 11:26:50 2021 -0500

    paned: Convert docs
    
    Convert links, add example image, clean things up.

 gtk/gtkpaned.c | 227 +++++++++++++++++++++++++++++++--------------------------
 1 file changed, 125 insertions(+), 102 deletions(-)
---
diff --git a/gtk/gtkpaned.c b/gtk/gtkpaned.c
index b263caba62..91d12f0589 100644
--- a/gtk/gtkpaned.c
+++ b/gtk/gtkpaned.c
@@ -42,30 +42,29 @@
 #include <math.h>
 
 /**
- * SECTION:gtkpaned
- * @Short_description: A widget with two adjustable panes
- * @Title: GtkPaned
+ * GtkPaned:
  *
- * #GtkPaned has two panes, arranged either
- * horizontally or vertically. The division between
- * the two panes is adjustable by the user by dragging
- * a handle.
+ * `GtkPaned` has two panes, arranged either horizontally or vertically.
+ *
+ * ![An example GtkPaned](panes.png)
+ *
+ * The division between the two panes is adjustable by the user
+ * by dragging a handle.
  *
  * Child widgets are added to the panes of the widget with
- * gtk_paned_set_start_child() and gtk_paned_set_end_child().
- * The division between the two children is set by default
- * from the size requests of the children, but it can be adjusted by the
- * user.
+ * [method@Gtk.Paned.set_start_child] and [method@Gtk.Paned.set_end_child].
+ * The division between the two children is set by default from the size
+ * requests of the children, but it can be adjusted by the user.
  *
  * A paned widget draws a separator between the two child widgets and a
  * small handle that the user can drag to adjust the division. It does not
  * draw any relief around the children or around the separator. (The space
  * in which the separator is called the gutter.) Often, it is useful to put
- * each child inside a #GtkFrame so that the gutter appears as a ridge.
- * No separator is drawn if one of the children is missing.
+ * each child inside a [class@Gtk.Frame] so that the gutter appears as a
+ * ridge. No separator is drawn if one of the children is missing.
  *
  * Each child has two options that can be set, @resize and @shrink. If
- * @resize is true, then when the #GtkPaned is resized, that child will
+ * @resize is true, then when the `GtkPaned` is resized, that child will
  * expand or shrink along with the paned widget. If @shrink is true, then
  * that child can be made smaller than its requisition by the user.
  * Setting @shrink to %FALSE allows the application to set a minimum size.
@@ -73,7 +72,7 @@
  * @resize is true for both children.
  *
  * The application can set the position of the slider as if it were set
- * by the user, by calling gtk_paned_set_position().
+ * by the user, by calling [method@Gtk.Paned.set_position].
  *
  * # CSS nodes
  *
@@ -84,7 +83,7 @@
  * ╰── <child>
  * ]|
  *
- * GtkPaned has a main CSS node with name paned, and a subnode for
+ * `GtkPaned` has a main CSS node with name paned, and a subnode for
  * the separator with name separator. The subnode gets a .wide style
  * class when the paned is supposed to be wide.
  *
@@ -95,7 +94,7 @@
  *
  * ## Creating a paned widget with minimum sizes.
  *
- * |[<!-- language="C" -->
+ * ```c
  * GtkWidget *hpaned = gtk_paned_new (GTK_ORIENTATION_HORIZONTAL);
  * GtkWidget *frame1 = gtk_frame_new (NULL);
  * GtkWidget *frame2 = gtk_frame_new (NULL);
@@ -111,7 +110,7 @@
  * gtk_paned_set_end_child_resize (GTK_PANED (hpaned), FALSE);
  * gtk_paned_set_end_child_shrink (GTK_PANED (hpaned), FALSE);
  * gtk_widget_set_size_request (frame2, 50, -1);
- * ]|
+ * ```
  */
 
 #define HANDLE_EXTRA_SIZE 6
@@ -417,6 +416,11 @@ gtk_paned_class_init (GtkPanedClass *class)
   class->accept_position = gtk_paned_accept_position;
   class->cancel_position = gtk_paned_cancel_position;
 
+  /**
+   * GtkPaned:position: (attributes org.gtk.Property.get=gtk_paned_get_position 
org.gtk.Property.set=gtk_paned_set_position)
+   *
+   * Position of the separator in pixels, from the left/top.
+   */
   paned_props[PROP_POSITION] =
     g_param_spec_int ("position",
                       P_("Position"),
@@ -424,6 +428,11 @@ gtk_paned_class_init (GtkPanedClass *class)
                       0, G_MAXINT, 0,
                       GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkPaned:position-set:
+   *
+   * %TRUE if the `position` property has been set.
+   */
   paned_props[PROP_POSITION_SET] =
     g_param_spec_boolean ("position-set",
                           P_("Position Set"),
@@ -435,6 +444,7 @@ gtk_paned_class_init (GtkPanedClass *class)
    * GtkPaned:min-position:
    *
    * The smallest possible value for the position property.
+   *
    * This property is derived from the size and shrinkability
    * of the widget's children.
    */
@@ -449,6 +459,7 @@ gtk_paned_class_init (GtkPanedClass *class)
    * GtkPaned:max-position:
    *
    * The largest possible value for the position property.
+   *
    * This property is derived from the size and shrinkability
    * of the widget's children.
    */
@@ -460,11 +471,12 @@ gtk_paned_class_init (GtkPanedClass *class)
                       GTK_PARAM_READABLE|G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkPaned:wide-handle:
+   * GtkPaned:wide-handle: (attributes org.gtk.Property.get=gtk_paned_get_wide_handle 
org.gtk.Property.set=gtk_paned_set_wide_handle)
    *
-   * Setting this property to %TRUE indicates that the paned needs
-   * to provide stronger visual separation (e.g. because it separates
-   * between two notebooks, whose tab rows would otherwise merge visually).
+   * Whether the `GtkPaned` should provide a stronger visual separation.
+   *
+   * For example, this could be set when a paned contains two
+   * [class@Gtk.Notebook]s, whose tab rows would otherwise merge visually.
    */
   paned_props[PROP_WIDE_HANDLE] =
     g_param_spec_boolean ("wide-handle",
@@ -474,10 +486,10 @@ gtk_paned_class_init (GtkPanedClass *class)
                           GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkPaned:resize-start-child:
+   * GtkPaned:resize-start-child: (attributes org.gtk.Property.get=gtk_paned_get_resize_start_child 
org.gtk.Property.set=gtk_paned_set_resize_start_child)
    *
-   * The "resize-start-child" property determines whether the first child expands and
-   * shrinks along with the paned widget.
+   * Determines whether the first child expands and shrinks
+   * along with the paned widget.
    */
   paned_props[PROP_RESIZE_START_CHILD] =
     g_param_spec_boolean ("resize-start-child",
@@ -487,10 +499,10 @@ gtk_paned_class_init (GtkPanedClass *class)
                           GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkPaned:resize-end-child:
+   * GtkPaned:resize-end-child: (attributes org.gtk.Property.get=gtk_paned_get_resize_end_child 
org.gtk.Property.set=gtk_paned_set_resize_end_child)
    *
-   * The "resize-end-child" property determines whether the second child expands and
-   * shrinks along with the paned widget.
+   * Determines whether the second child expands and shrinks
+   * along with the paned widget.
    */
   paned_props[PROP_RESIZE_END_CHILD] =
     g_param_spec_boolean ("resize-end-child",
@@ -500,10 +512,10 @@ gtk_paned_class_init (GtkPanedClass *class)
                           GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkPaned:shrink-start-child:
+   * GtkPaned:shrink-start-child: (attributes org.gtk.Property.get=gtk_paned_get_shrink_start_child 
org.gtk.Property.set=gtk_paned_set_shrink_start_child)
    *
-   * The "shrink-start-child" property determines whether the first child can be made
-   * smaller than its requisition.
+   * Determines whether the first child can be made smaller
+   * than its requisition.
    */
   paned_props[PROP_SHRINK_START_CHILD] =
     g_param_spec_boolean ("shrink-start-child",
@@ -513,10 +525,10 @@ gtk_paned_class_init (GtkPanedClass *class)
                           GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkPaned:shrink-end-child:
+   * GtkPaned:shrink-end-child: (attributes org.gtk.Property.get=gtk_paned_get_shrink_end_child 
org.gtk.Property.set=gtk_paned_set_shrink_end_child)
    *
-   * The "shrink-end-child" property determines whether the second child can be made
-   * smaller than its requisition.
+   * Determines whether the second child can be made smaller
+   * than its requisition.
    */
   paned_props[PROP_SHRINK_END_CHILD] =
     g_param_spec_boolean ("shrink-end-child",
@@ -525,6 +537,11 @@ gtk_paned_class_init (GtkPanedClass *class)
                           TRUE,
                           GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkPaned:start-child: (attributes org.gtk.Property.get=gtk_paned_get_start_child 
org.gtk.Property.set=gtk_paned_set_start_child)
+   *
+   * The first child.
+   */
   paned_props[PROP_START_CHILD] =
     g_param_spec_object ("start-child",
                           P_("First child"),
@@ -532,6 +549,11 @@ gtk_paned_class_init (GtkPanedClass *class)
                           GTK_TYPE_WIDGET,
                           GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
+  /**
+   * GtkPaned:end-child: (attributes org.gtk.Property.get=gtk_paned_get_end_child 
org.gtk.Property.set=gtk_paned_set_end_child)
+   *
+   * The second child.
+   */
   paned_props[PROP_END_CHILD] =
     g_param_spec_object ("end-child",
                           P_("Second child"),
@@ -547,11 +569,11 @@ gtk_paned_class_init (GtkPanedClass *class)
    * @widget: the object that received the signal
    * @reversed: whether cycling backward or forward
    *
-   * The ::cycle-child-focus signal is a
-   * [keybinding signal][GtkSignalAction]
-   * which gets emitted to cycle the focus between the children of the paned.
+   * Emitted to cycle the focus between the children of the paned.
    *
-   * The default binding is f6.
+   * This is a [keybinding signal](class.SignalAction.html).
+   *
+   * The default binding is F6.
    */
   signals [CYCLE_CHILD_FOCUS] =
     g_signal_new (I_("cycle-child-focus"),
@@ -567,11 +589,11 @@ gtk_paned_class_init (GtkPanedClass *class)
    * GtkPaned::toggle-handle-focus:
    * @widget: the object that received the signal
    *
-   * The ::toggle-handle-focus is a
-   * [keybinding signal][GtkSignalAction]
-   * which gets emitted to accept the current position of the handle and then
+   * Emitted to accept the current position of the handle and then
    * move focus to the next widget in the focus chain.
    *
+   * This is a [keybinding signal](class.SignalAction.html).
+   *
    * The default binding is Tab.
    */
   signals [TOGGLE_HANDLE_FOCUS] =
@@ -588,10 +610,9 @@ gtk_paned_class_init (GtkPanedClass *class)
    * @widget: the object that received the signal
    * @scroll_type: a #GtkScrollType
    *
-   * The ::move-handle signal is a
-   * [keybinding signal][GtkSignalAction]
-   * which gets emitted to move the handle when the user is using key bindings
-   * to move it.
+   * Emitted to move the handle with key bindings.
+   *
+   * This is a [keybinding signal](class.SignalAction.html).
    */
   signals[MOVE_HANDLE] =
     g_signal_new (I_("move-handle"),
@@ -608,12 +629,12 @@ gtk_paned_class_init (GtkPanedClass *class)
    * @widget: the object that received the signal
    * @reversed: whether cycling backward or forward
    *
-   * The ::cycle-handle-focus signal is a
-   * [keybinding signal][GtkSignalAction]
-   * which gets emitted to cycle whether the paned should grab focus to allow
+   * Emitted to cycle whether the paned should grab focus to allow
    * the user to change position of the handle by using key bindings.
    *
-   * The default binding for this signal is f8.
+   * This is a [keybinding signal](class.SignalAction.html).
+   *
+   * The default binding for this signal is F8.
    */
   signals [CYCLE_HANDLE_FOCUS] =
     g_signal_new (I_("cycle-handle-focus"),
@@ -629,11 +650,11 @@ gtk_paned_class_init (GtkPanedClass *class)
    * GtkPaned::accept-position:
    * @widget: the object that received the signal
    *
-   * The ::accept-position signal is a
-   * [keybinding signal][GtkSignalAction]
-   * which gets emitted to accept the current position of the handle when
+   * Emitted to accept the current position of the handle when
    * moving it using key bindings.
    *
+   * This is a [keybinding signal](class.SignalAction.html).
+   *
    * The default binding for this signal is Return or Space.
    */
   signals [ACCEPT_POSITION] =
@@ -649,12 +670,14 @@ gtk_paned_class_init (GtkPanedClass *class)
    * GtkPaned::cancel-position:
    * @widget: the object that received the signal
    *
-   * The ::cancel-position signal is a
-   * [keybinding signal][GtkSignalAction]
-   * which gets emitted to cancel moving the position of the handle using key
-   * bindings. The position of the handle will be reset to the value prior to
+   * Emitted to cancel moving the position of the handle using key
+   * bindings.
+   *
+   * The position of the handle will be reset to the value prior to
    * moving it.
    *
+   * This is a [keybinding signal](class.SignalAction.html).
+   *
    * The default binding for this signal is Escape.
    */
   signals [CANCEL_POSITION] =
@@ -1512,10 +1535,10 @@ gtk_paned_css_changed (GtkWidget         *widget,
  * gtk_paned_new:
  * @orientation: the paned’s orientation.
  *
- * Creates a new #GtkPaned widget.
+ * Creates a new `GtkPaned` widget.
  *
- * Returns: a new #GtkPaned.
- **/
+ * Returns: a new `GtkPaned`.
+ */
 GtkWidget *
 gtk_paned_new (GtkOrientation orientation)
 {
@@ -1525,8 +1548,8 @@ gtk_paned_new (GtkOrientation orientation)
 }
 
 /**
- * gtk_paned_set_start_child:
- * @paned: a #GtkPaned
+ * gtk_paned_set_start_child: (attributes org.gtk.Method.set_property=start-child)
+ * @paned: a `GtkPaned`
  * @child: the widget to add
  *
  * Sets the start child of @paned to @child.
@@ -1550,12 +1573,12 @@ gtk_paned_set_start_child (GtkPaned *paned,
 }
 
 /**
- * gtk_paned_get_start_child:
- * @paned: a #GtkPaned
+ * gtk_paned_get_start_child: (attributes org.gtk.Method.get_property=start-child)
+ * @paned: a `GtkPaned`
  *
- * Retrieves the start child of the given #GtkPaned.
+ * Retrieves the start child of the given `GtkPaned`.
  *
- * See also: #GtkPaned:start-child
+ * See also: `GtkPaned`:start-child
  *
  * Returns: (transfer none) (nullable): the start child widget
  */
@@ -1568,11 +1591,11 @@ gtk_paned_get_start_child (GtkPaned *paned)
 }
 
 /**
- * gtk_paned_set_resize_start_child:
- * @paned: a #GtkPaned
+ * gtk_paned_set_resize_start_child: (attributes org.gtk.Method.set_property=resize-start-child)
+ * @paned: a `GtkPaned`
  * @resize: %TRUE to let the start child be resized
  *
- * Sets the #GtkPaned:resize-start-child property
+ * Sets the `GtkPaned`:resize-start-child property
  */
 void
 gtk_paned_set_resize_start_child (GtkPaned *paned,
@@ -1589,8 +1612,8 @@ gtk_paned_set_resize_start_child (GtkPaned *paned,
 }
 
 /**
- * gtk_paned_get_resize_start_child:
- * @paned: a #GtkPaned
+ * gtk_paned_get_resize_start_child: (attributes org.gtk.Method.get_property=resize-start-child)
+ * @paned: a `GtkPaned`
  *
  * Returns whether the start child can be resized.
  *
@@ -1605,11 +1628,11 @@ gtk_paned_get_resize_start_child (GtkPaned *paned)
 }
 
 /**
- * gtk_paned_set_shrink_start_child:
- * @paned: a #GtkPaned
+ * gtk_paned_set_shrink_start_child: (attributes org.gtk.Method.set_property=shrink-start-child)
+ * @paned: a `GtkPaned`
  * @resize: %TRUE to let the start child be shrunk
  *
- * Sets the #GtkPaned:shrink-start-child property
+ * Sets the `GtkPaned`:shrink-start-child property
  */
 void
 gtk_paned_set_shrink_start_child (GtkPaned *paned,
@@ -1626,8 +1649,8 @@ gtk_paned_set_shrink_start_child (GtkPaned *paned,
 }
 
 /**
- * gtk_paned_get_shrink_start_child:
- * @paned: a #GtkPaned
+ * gtk_paned_get_shrink_start_child: (attributes org.gtk.Method.get_property=shrink-start-child)
+ * @paned: a `GtkPaned`
  *
  * Returns whether the start child can be shrunk.
  *
@@ -1642,8 +1665,8 @@ gtk_paned_get_shrink_start_child (GtkPaned *paned)
 }
 
 /**
- * gtk_paned_set_end_child:
- * @paned: a #GtkPaned
+ * gtk_paned_set_end_child: (attributes org.gtk.Method.set_property=end-child)
+ * @paned: a `GtkPaned`
  * @child: the widget to add
  *
  * Sets the end child of @paned to @child.
@@ -1667,12 +1690,12 @@ gtk_paned_set_end_child (GtkPaned *paned,
 }
 
 /**
- * gtk_paned_get_end_child:
- * @paned: a #GtkPaned
+ * gtk_paned_get_end_child: (attributes org.gtk.Method.get_property=end-child)
+ * @paned: a `GtkPaned`
  *
- * Retrieves the end child of the given #GtkPaned.
+ * Retrieves the end child of the given `GtkPaned`.
  *
- * See also: #GtkPaned:end-child
+ * See also: `GtkPaned`:end-child
  *
  * Returns: (transfer none) (nullable): the end child widget
  */
@@ -1685,11 +1708,11 @@ gtk_paned_get_end_child (GtkPaned *paned)
 }
 
 /**
- * gtk_paned_set_resize_end_child:
- * @paned: a #GtkPaned
+ * gtk_paned_set_resize_end_child: (attributes org.gtk.Method.set_property=resize-end-child)
+ * @paned: a `GtkPaned`
  * @resize: %TRUE to let the end child be resized
  *
- * Sets the #GtkPaned:resize-end-child property
+ * Sets the `GtkPaned`:resize-end-child property
  */
 void
 gtk_paned_set_resize_end_child (GtkPaned *paned,
@@ -1706,8 +1729,8 @@ gtk_paned_set_resize_end_child (GtkPaned *paned,
 }
 
 /**
- * gtk_paned_get_resize_end_child:
- * @paned: a #GtkPaned
+ * gtk_paned_get_resize_end_child: (attributes org.gtk.Method.get_property=resize-end-child)
+ * @paned: a `GtkPaned`
  *
  * Returns whether the end child can be resized.
  *
@@ -1722,11 +1745,11 @@ gtk_paned_get_resize_end_child (GtkPaned *paned)
 }
 
 /**
- * gtk_paned_set_shrink_end_child:
- * @paned: a #GtkPaned
+ * gtk_paned_set_shrink_end_child: (attributes org.gtk.Method.set_property=shrink-end-child)
+ * @paned: a `GtkPaned`
  * @resize: %TRUE to let the end child be shrunk
  *
- * Sets the #GtkPaned:shrink-end-child property
+ * Sets the `GtkPaned`:shrink-end-child property
  */
 void
 gtk_paned_set_shrink_end_child (GtkPaned *paned,
@@ -1743,8 +1766,8 @@ gtk_paned_set_shrink_end_child (GtkPaned *paned,
 }
 
 /**
- * gtk_paned_get_shrink_end_child:
- * @paned: a #GtkPaned
+ * gtk_paned_get_shrink_end_child: (attributes org.gtk.Method.get_property=shrink-end-child)
+ * @paned: a `GtkPaned`
  *
  * Returns whether the end child can be shrunk.
  *
@@ -1759,8 +1782,8 @@ gtk_paned_get_shrink_end_child (GtkPaned *paned)
 }
 
 /**
- * gtk_paned_get_position:
- * @paned: a #GtkPaned widget
+ * gtk_paned_get_position: (attributes org.gtk.Method.get_property=position)
+ * @paned: a `GtkPaned` widget
  *
  * Obtains the position of the divider between the two panes.
  *
@@ -1775,8 +1798,8 @@ gtk_paned_get_position (GtkPaned  *paned)
 }
 
 /**
- * gtk_paned_set_position:
- * @paned: a #GtkPaned widget
+ * gtk_paned_set_position: (attributes org.gtk.Method.set_property=position)
+ * @paned: a `GtkPaned` widget
  * @position: pixel position of divider, a negative value means that the position
  *            is unset.
  *
@@ -2448,11 +2471,11 @@ gtk_paned_toggle_handle_focus (GtkPaned *paned)
 }
 
 /**
- * gtk_paned_set_wide_handle:
- * @paned: a #GtkPaned
- * @wide: the new value for the #GtkPaned:wide-handle property
+ * gtk_paned_set_wide_handle: (attributes org.gtk.Method.set_propery=wide-handle)
+ * @paned: a `GtkPaned`
+ * @wide: the new value for the [property@Gtk.Paned:wide-handle] property
  *
- * Sets the #GtkPaned:wide-handle property.
+ * Sets whether the separator should be wide.
  */
 void
 gtk_paned_set_wide_handle (GtkPaned *paned,
@@ -2475,10 +2498,10 @@ gtk_paned_set_wide_handle (GtkPaned *paned,
 }
 
 /**
- * gtk_paned_get_wide_handle:
- * @paned: a #GtkPaned
+ * gtk_paned_get_wide_handle: (attributes org.gtk.Method.get_property=wide-handle)
+ * @paned: a `GtkPaned`
  *
- * Gets the #GtkPaned:wide-handle property.
+ * Gets whether the separator should be wide.
  *
  * Returns: %TRUE if the paned should have a wide handle
  */
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]