GNOME.org
 

[gtk/ebassi/gidocgen: 214/471] headerbar: Convert docs


commit 5cb29b389913c4a8b479d84722ab0e6761cc40df
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Feb 26 23:15:27 2021 -0500

    headerbar: Convert docs

 gtk/gtkheaderbar.c | 138 +++++++++++++++++++++++++++--------------------------
 1 file changed, 70 insertions(+), 68 deletions(-)
---
diff --git a/gtk/gtkheaderbar.c b/gtk/gtkheaderbar.c
index 821e29f99f..efa0df9b0e 100644
--- a/gtk/gtkheaderbar.c
+++ b/gtk/gtkheaderbar.c
@@ -38,37 +38,36 @@
 #include <string.h>
 
 /**
- * SECTION:gtkheaderbar
- * @Short_description: A box with a centered child
- * @Title: GtkHeaderBar
- * @See_also: #GtkBox, #GtkActionBar
+ * GtkHeaderBar:
  *
- * `GtkHeaderBar` is a widget for creating custom title bars for
- * [class@Gtk.Window].
+ * `GtkHeaderBar` is a widget for creating custom title bars for windows.
  *
- * GtkHeaderBar is similar to a horizontal #GtkBox. It allows children to 
- * be placed at the start or the end. In addition, it allows the window
- * title to be displayed. The title will be centered with respect to the
- * width of the box, even if the children at either side take up different
- * amounts of space.
+ * `GtkHeaderBar` is similar to a horizontal `GtkCenterBox`. It allows
+ * children to be placed at the start or the end. In addition, it allows
+ * the window title to be displayed. The title will be centered with respect
+ * to the width of the box, even if the children at either side take up
+ * different amounts of space.
  *
- * GtkHeaderBar can add typical window frame controls, such as minimize,
+ * `GtkHeaderBar` can add typical window frame controls, such as minimize,
  * maximize and close buttons, or the window icon.
  *
- * For these reasons, GtkHeaderBar is the natural choice for use as the custom
- * titlebar widget of a #GtkWindow (see gtk_window_set_titlebar()), as it gives
- * features typical of titlebars while allowing the addition of child widgets.
+ * For these reasons, `GtkHeaderBar` is the natural choice for use as the
+ * custom titlebar widget of a `GtkWindow (see [method@Gtk.Window.set_titlebar]),
+ * as it gives features typical of titlebars while allowing the addition of
+ * child widgets.
  *
- * The GtkHeaderBar implementation of the #GtkBuildable interface supports
+ * ## GtkHeaderBar as GtkBuildable
+ *
+ * The `GtkHeaderBar` implementation of the `GtkBuildable` interface supports
  * adding children at the start or end sides by specifying “start” or “end” as
  * the “type” attribute of a <child> element, or setting the title widget by
  * specifying “title” value.
  *
- * By default the GtkHeaderBar uses a #GtkLabel displaying the title of the
+ * By default the `GtkHeaderBar` uses a `GtkLabel` displaying the title of the
  * window it is contained in as the title widget, equivalent to the following
  * UI definition:
  *
- * |[
+ * ```xml
  * <object class="GtkHeaderBar">
  *   <property name="title-widget">
  *     <object class="GtkLabel">
@@ -82,7 +81,7 @@
  *     </object>
  *   </property>
  * </object>
- * ]|
+ * ```
  *
  * # CSS nodes
  *
@@ -99,17 +98,17 @@
  *             ╰── windowcontrols.end
  * ]|
  *
- * A #GtkHeaderBar's CSS node is called `headerbar`. It contains a `windowhandle`
+ * A `GtkHeaderBar`'s CSS node is called `headerbar`. It contains a `windowhandle`
  * subnode, which contains a `box` subnode, which contains two `box` subnodes at
  * the start and end of the header bar, as well as a center node that represents
  * the title.
  *
- * Each of the boxes contains a `windowcontrols` subnode, see #GtkWindowControls
- * for details, as well as other children.
+ * Each of the boxes contains a `windowcontrols` subnode, see
+ * [class@Gtk.WindowControls] for details, as well as other children.
  *
  * # Accessibility
  *
- * GtkHeaderBar uses the %GTK_ACCESSIBLE_ROLE_GROUP role.
+ * `GtkHeaderBar` uses the %GTK_ACCESSIBLE_ROLE_GROUP role.
  */
 
 #define MIN_TITLE_CHARS 5
@@ -282,19 +281,20 @@ construct_title_label (GtkHeaderBar *bar)
 
 /**
  * gtk_header_bar_set_title_widget:
- * @bar: a #GtkHeaderBar
+ * @bar: a `GtkHeaderBar`
  * @title_widget: (allow-none): a widget to use for a title
  *
- * Sets the title for the #GtkHeaderBar.
+ * Sets the title for the `GtkHeaderBar`.
  *
- * When set to %NULL, the headerbar will display the title of the window it is
- * contained in.
+ * When set to %NULL, the headerbar will display the title of
+ * the window it is contained in.
  *
- * The title should help a user identify the current view. To achieve the same
- * style as the builtin title, use the “title” style class.
+ * The title should help a user identify the current view.
+ * To achieve the same style as the builtin title, use the
+ * “title” style class.
  *
- * You should set the title widget to %NULL, for the window title label to be
- * visible again.
+ * You should set the title widget to %NULL, for the window
+ * title label to be visible again.
  */
 void
 gtk_header_bar_set_title_widget (GtkHeaderBar *bar,
@@ -330,13 +330,14 @@ gtk_header_bar_set_title_widget (GtkHeaderBar *bar,
 
 /**
  * gtk_header_bar_get_title_widget:
- * @bar: a #GtkHeaderBar
+ * @bar: a `GtkHeaderBar`
+ *
+ * Retrieves the title widget of the header.
  *
- * Retrieves the title widget of the header. See
- * gtk_header_bar_set_title_widget().
+ * See [method@Gtk.HeaderBar.set_title_widget].
  *
  * Returns: (nullable) (transfer none): the title widget
- *    of the header, or %NULL if none has been set explicitly.
+ *   of the header, or %NULL if none has been set explicitly.
  */
 GtkWidget *
 gtk_header_bar_get_title_widget (GtkHeaderBar *bar)
@@ -475,12 +476,15 @@ gtk_header_bar_pack (GtkHeaderBar *bar,
 
 /**
  * gtk_header_bar_remove:
- * @bar: a #GtkHeaderBar
+ * @bar: a `GtkHeaderBar`
  * @child: the child to remove
  *
- * Removes a child from @bar, after it has been added
- * with gtk_header_bar_pack_start(), gtk_header_bar_pack_end()
- * or gtk_header_bar_set_title_widget().
+ * Removes a child from the `GtkHeaderBar`.
+ *
+ * The child must have been added with
+ * [method@Gtk.HeaderBar.pack_start],
+ * [method@Gtk.HeaderBar.pack_end] or
+ * [method@Gtk.HeaderBar.set_title_widget].
  */
 void
 gtk_header_bar_remove (GtkHeaderBar *bar,
@@ -568,14 +572,14 @@ gtk_header_bar_class_init (GtkHeaderBarClass *class)
                            G_PARAM_READWRITE|G_PARAM_STATIC_STRINGS);
 
   /**
-   * GtkHeaderBar:show-title-buttons:
+   * GtkHeaderBar:show-title-buttons: (attributes org.gtk.Property.get=gtk_header_bar_get_show_title_buttons 
org.gtk.Property.set=gtk_header_bar_set_show_title_buttons)
    *
    * Whether to show title buttons like close, minimize, maximize.
    *
    * Which buttons are actually shown and where is determined
-   * by the #GtkHeaderBar:decoration-layout property, and by
-   * the state of the window (e.g. a close button will not be
-   * shown if the window can't be closed).
+   * by the [property@Gtk.HeaderBar:decoration-layout] property,
+   * and by the state of the window (e.g. a close button will not
+   * be shown if the window can't be closed).
    */
   header_bar_props[PROP_SHOW_TITLE_BUTTONS] =
       g_param_spec_boolean ("show-title-buttons",
@@ -585,14 +589,12 @@ gtk_header_bar_class_init (GtkHeaderBarClass *class)
                             GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkHeaderBar:decoration-layout:
+   * GtkHeaderBar:decoration-layout: (attributes org.gtk.Property.get=gtk_header_bar_get_decoration_layout 
org.gtk.Property.set=gtk_header_bar_set_decoration_layout)
    *
-   * The decoration layout for buttons. If this property is
-   * not set, the #GtkSettings:gtk-decoration-layout setting
-   * is used.
+   * The decoration layout for buttons.
    *
-   * See gtk_header_bar_set_decoration_layout() for information
-   * about the format of this string.
+   * If this property is not set, the
+   * [property@Gtk.Settings:gtk-decoration-layout] setting is used.
    */
   header_bar_props[PROP_DECORATION_LAYOUT] =
       g_param_spec_string ("decoration-layout",
@@ -663,7 +665,7 @@ gtk_header_bar_buildable_init (GtkBuildableIface *iface)
 
 /**
  * gtk_header_bar_pack_start:
- * @bar: A #GtkHeaderBar
+ * @bar: A `GtkHeaderBar`
  * @child: the #GtkWidget to be added to @bar
  *
  * Adds @child to @bar, packed with reference to the
@@ -678,7 +680,7 @@ gtk_header_bar_pack_start (GtkHeaderBar *bar,
 
 /**
  * gtk_header_bar_pack_end:
- * @bar: A #GtkHeaderBar
+ * @bar: A `GtkHeaderBar`
  * @child: the #GtkWidget to be added to @bar
  *
  * Adds @child to @bar, packed with reference to the
@@ -694,9 +696,9 @@ gtk_header_bar_pack_end (GtkHeaderBar *bar,
 /**
  * gtk_header_bar_new:
  *
- * Creates a new #GtkHeaderBar widget.
+ * Creates a new `GtkHeaderBar` widget.
  *
- * Returns: a new #GtkHeaderBar
+ * Returns: a new `GtkHeaderBar`
  */
 GtkWidget *
 gtk_header_bar_new (void)
@@ -705,8 +707,8 @@ gtk_header_bar_new (void)
 }
 
 /**
- * gtk_header_bar_get_show_title_buttons:
- * @bar: a #GtkHeaderBar
+ * gtk_header_bar_get_show_title_buttons: (attributes org.gtk.Method.get_property=show-title-buttons)
+ * @bar: a `GtkHeaderBar`
  *
  * Returns whether this header bar shows the standard window
  * title buttons.
@@ -722,12 +724,12 @@ gtk_header_bar_get_show_title_buttons (GtkHeaderBar *bar)
 }
 
 /**
- * gtk_header_bar_set_show_title_buttons:
- * @bar: a #GtkHeaderBar
+ * gtk_header_bar_set_show_title_buttons: (attributes org.gtk.Method.set_property=show-title-buttons)
+ * @bar: a `GtkHeaderBar`
  * @setting: %TRUE to show standard title buttons
  *
  * Sets whether this header bar shows the standard window
- * title buttons including close, maximize, and minimize.
+ * title buttons.
  */
 void
 gtk_header_bar_set_show_title_buttons (GtkHeaderBar *bar,
@@ -763,19 +765,20 @@ gtk_header_bar_set_show_title_buttons (GtkHeaderBar *bar,
 }
 
 /**
- * gtk_header_bar_set_decoration_layout:
- * @bar: a #GtkHeaderBar
+ * gtk_header_bar_set_decoration_layout: (attributes org.gtk.Method.set_property=decoration-layout)
+ * @bar: a `GtkHeaderBar`
  * @layout: (allow-none): a decoration layout, or %NULL to
  *     unset the layout
  *
- * Sets the decoration layout for this header bar, overriding
- * the #GtkSettings:gtk-decoration-layout setting. 
+ * Sets the decoration layout for this header bar.
+ *
+ * This property overrides the
+ * [property@Gtk.Settings:gtk-decoration-layout] setting.
  *
  * There can be valid reasons for overriding the setting, such
  * as a header bar design that does not allow for buttons to take
  * room on the right, or only offers room for a single close button.
- * Split header bars are another example for overriding the
- * setting.
+ * Split header bars are another example for overriding the setting.
  *
  * The format of the string is button names, separated by commas.
  * A colon separates the buttons that should appear on the left
@@ -798,11 +801,10 @@ gtk_header_bar_set_decoration_layout (GtkHeaderBar *bar,
 }
 
 /**
- * gtk_header_bar_get_decoration_layout:
- * @bar: a #GtkHeaderBar
+ * gtk_header_bar_get_decoration_layout: (attributes org.gtk.Method.get_property=decoration-layout)
+ * @bar: a `GtkHeaderBar`
  *
- * Gets the decoration layout set with
- * gtk_header_bar_set_decoration_layout().
+ * Gets the decoration layout of the `GtkHeaderBar`.
  *
  * Returns: (nullable): the decoration layout
  */
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]