[gtk/ebassi/gidocgen] label: Convert docs
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk/ebassi/gidocgen] label: Convert docs
- Date: Fri, 19 Feb 2021 19:51:23 +0000 (UTC)
commit f355650325954776ba4e71d6920da02670a73039
Author: Matthias Clasen <mclasen redhat com>
Date: Fri Feb 19 14:47:44 2021 -0500
label: Convert docs
Change link syntax, add singl-line summaries,
add missing property docs.
gtk/gtklabel.c | 792 ++++++++++++++++++++++++++++++++-------------------------
1 file changed, 447 insertions(+), 345 deletions(-)
---
diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index e6ca3a631c..15fbc74a95 100644
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -61,8 +61,10 @@
* @Short_description: A widget that displays a small to medium amount of text
* @Title: GtkLabel
*
- * The #GtkLabel widget displays a small amount of text. As the name
- * implies, most labels are used to label another widget such as a #GtkButton.
+ * The `GtkLabel` widget displays a small amount of text. As the name
+ * implies, most labels are used to label another widget such as a [class@Button].
+ *
+ * 
*
* # CSS nodes
*
@@ -74,9 +76,9 @@
* ╰── [link]
* ]|
*
- * GtkLabel has a single CSS node with the name label. A wide variety
+ * `GtkLabel` has a single CSS node with the name label. A wide variety
* of style classes may be applied to labels, such as .title, .subtitle,
- * .dim-label, etc. In the #GtkShortcutsWindow, labels are used with the
+ * .dim-label, etc. In the `GtkShortcutsWindow`, labels are used with the
* .keycap style class.
*
* If the label has a selection, it gets a subnode with name selection.
@@ -90,18 +92,18 @@
* The GtkLabel implementation of the GtkBuildable interface supports a
* custom <attributes> element, which supports any number of <attribute>
* elements. The <attribute> element has attributes named “name“, “value“,
- * “start“ and “end“ and allows you to specify #PangoAttribute values for
- * this label.
+ * “start“ and “end“ and allows you to specify [class@Pango.Attribute]
+ * values for this label.
*
* An example of a UI definition fragment specifying Pango attributes:
- * |[
+ * ```xml
* <object class="GtkLabel">
* <attributes>
* <attribute name="weight" value="PANGO_WEIGHT_BOLD"/>
* <attribute name="background" value="red" start="5" end="10"/>
* </attributes>
* </object>
- * ]|
+ * ```
*
* The start and end attributes specify the range of characters to which the
* Pango attribute applies. If start and end are not specified, the attribute is
@@ -111,136 +113,131 @@
*
* # Accessibility
*
- * GtkLabel uses the #GTK_ACCESSIBLE_ROLE_LABEL role.
+ * `GtkLabel` uses the #GTK_ACCESSIBLE_ROLE_LABEL role.
*
* # Mnemonics
*
- * Labels may contain “mnemonics”. Mnemonics are
- * underlined characters in the label, used for keyboard navigation.
- * Mnemonics are created by providing a string with an underscore before
- * the mnemonic character, such as `"_File"`, to the
- * functions gtk_label_new_with_mnemonic() or
- * gtk_label_set_text_with_mnemonic().
+ * Labels may contain “mnemonics”. Mnemonics are underlined characters in the
+ * label, used for keyboard navigation. Mnemonics are created by providing a
+ * string with an underscore before the mnemonic character, such as `"_File"`,
+ * to the functions [method@Gtk.Label.new_with_mnemonic] or
+ * [method@Gtk.Label.set_text_with_mnemonic].
*
* Mnemonics automatically activate any activatable widget the label is
- * inside, such as a #GtkButton; if the label is not inside the
+ * inside, such as a [class@Gtk.Button]; if the label is not inside the
* mnemonic’s target widget, you have to tell the label about the target
- * using gtk_label_set_mnemonic_widget(). Here’s a simple example where
+ * using [class@Gtk.Label.set_mnemonic_widget]. Here’s a simple example where
* the label is inside a button:
*
- * |[<!-- language="C" -->
- * // Pressing Alt+H will activate this button
- * GtkWidget *button = gtk_button_new ();
- * GtkWidget *label = gtk_label_new_with_mnemonic ("_Hello");
- * gtk_button_set_child (GTK_BUTTON (button), label);
- * ]|
+ * ```c
+ * // Pressing Alt+H will activate this button
+ * GtkWidget *button = gtk_button_new ();
+ * GtkWidget *label = gtk_label_new_with_mnemonic ("_Hello");
+ * gtk_button_set_child (GTK_BUTTON (button), label);
+ * ```
*
* There’s a convenience function to create buttons with a mnemonic label
* already inside:
*
- * |[<!-- language="C" -->
- * // Pressing Alt+H will activate this button
- * GtkWidget *button = gtk_button_new_with_mnemonic ("_Hello");
- * ]|
+ * ```c
+ * // Pressing Alt+H will activate this button
+ * GtkWidget *button = gtk_button_new_with_mnemonic ("_Hello");
+ * ```
*
* To create a mnemonic for a widget alongside the label, such as a
- * #GtkEntry, you have to point the label at the entry with
- * gtk_label_set_mnemonic_widget():
- *
- * |[<!-- language="C" -->
- * // Pressing Alt+H will focus the entry
- * GtkWidget *entry = gtk_entry_new ();
- * GtkWidget *label = gtk_label_new_with_mnemonic ("_Hello");
- * gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry);
- * ]|
+ * [class@Gtk.Entry], you have to point the label at the entry with
+ * [method@Gtk.Label.set_mnemonic_widget]:
+ *
+ * ```c
+ * // Pressing Alt+H will focus the entry
+ * GtkWidget *entry = gtk_entry_new ();
+ * GtkWidget *label = gtk_label_new_with_mnemonic ("_Hello");
+ * gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry);
+ * ```
*
* # Markup (styled text)
*
* To make it easy to format text in a label (changing colors,
* fonts, etc.), label text can be provided in a simple
- * [markup format][PangoMarkupFormat].
+ * markup format:
*
* Here’s how to create a label with a small font:
- * |[<!-- language="C" -->
- * GtkWidget *label = gtk_label_new (NULL);
- * gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>");
- * ]|
+ * ```c
+ * GtkWidget *label = gtk_label_new (NULL);
+ * gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>");
+ * ```
*
- * (See [complete documentation][PangoMarkupFormat] of available
- * tags in the Pango manual.)
+ * (See the Pango manual for complete documentation] of available
+ * tags, [func@Pango.parse_markup])
*
* The markup passed to gtk_label_set_markup() must be valid; for example,
* literal <, > and & characters must be escaped as <, >, and &.
* If you pass text obtained from the user, file, or a network to
- * gtk_label_set_markup(), you’ll want to escape it with
+ * [method@Gtk.Label.set_markup], you’ll want to escape it with
* g_markup_escape_text() or g_markup_printf_escaped().
*
- * Markup strings are just a convenient way to set the #PangoAttrList on
- * a label; gtk_label_set_attributes() may be a simpler way to set
- * attributes in some cases. Be careful though; #PangoAttrList tends to
- * cause internationalization problems, unless you’re applying attributes
+ * Markup strings are just a convenient way to set the [class@Pango.AttrList]
+ * on a label; [method@Gtk.Label.set_attributes] may be a simpler way to set
+ * attributes in some cases. Be careful though; [class@Pango.AttrList] tends
+ * to cause internationalization problems, unless you’re applying attributes
* to the entire string (i.e. unless you set the range of each attribute
* to [0, %G_MAXINT)). The reason is that specifying the start_index and
- * end_index for a #PangoAttribute requires knowledge of the exact string
- * being displayed, so translations will cause problems.
+ * end_index for a [class@Pango.Attribute] requires knowledge of the exact
+ * string being displayed, so translations will cause problems.
*
* # Selectable labels
*
- * Labels can be made selectable with gtk_label_set_selectable().
+ * Labels can be made selectable with [method@Gtk.Label.set_selectable].
* Selectable labels allow the user to copy the label contents to
* the clipboard. Only labels that contain useful-to-copy information
* — such as error messages — should be made selectable.
*
- * # Text layout # {#label-text-layout}
+ * # Text layout
*
* A label can contain any number of paragraphs, but will have
* performance problems if it contains more than a small number.
* Paragraphs are separated by newlines or other paragraph separators
* understood by Pango.
*
- * Labels can automatically wrap text if you call
- * gtk_label_set_wrap().
+ * Labels can automatically wrap text if you call [method@Gtk.Label.set_wrap].
*
- * gtk_label_set_justify() sets how the lines in a label align
- * with one another. If you want to set how the label as a whole
- * aligns in its available space, see the #GtkWidget:halign and
- * #GtkWidget:valign properties.
+ * [method@Gtk.Label.set_justify] sets how the lines in a label align
+ * with one another. If you want to set how the label as a whole aligns
+ * in its available space, see the [property@Gtk.Widget:halign] and
+ * [property@Gtk.Widget:valign] properties.
*
- * The #GtkLabel:width-chars and #GtkLabel:max-width-chars properties
- * can be used to control the size allocation of ellipsized or wrapped
- * labels. For ellipsizing labels, if either is specified (and less
+ * The [property@Gtk.Label:width-chars[ and [property@Gtk.Label:max-width-chars]
+ * properties can be used to control the size allocation of ellipsized or
+ * wrapped labels. For ellipsizing labels, if either is specified (and less
* than the actual text size), it is used as the minimum width, and the actual
* text size is used as the natural width of the label. For wrapping labels,
* width-chars is used as the minimum width, if specified, and max-width-chars
* is used as the natural width. Even if max-width-chars specified, wrapping
* labels will be rewrapped to use all of the available width.
*
- * Note that the interpretation of #GtkLabel:width-chars and
- * #GtkLabel:max-width-chars has changed a bit with the introduction of
- * [width-for-height geometry management.][geometry-management]
- *
* # Links
*
- * GTK supports markup for clickable hyperlinks in addition
- * to regular Pango markup. The markup for links is borrowed from HTML,
- * using the `<a>` with “href“, “title“ and “class“ attributes. GTK renders links
- * similar to the way they appear in web browsers, with colored, underlined
- * text. The “title“ attribute is displayed as a tooltip on the link. The “class“
- * attribute is used as style class on the CSS node for the link.
+ * GTK supports markup for clickable hyperlinks in addition to regular Pango
+ * markup. The markup for links is borrowed from HTML, using the `<a>` with
+ * “href“, “title“ and “class“ attributes. GTK renders links similar to the
+ * way they appear in web browsers, with colored, underlined text. The “title“
+ * attribute is displayed as a tooltip on the link. The “class“ attribute is
+ * used as style class on the CSS node for the link.
*
* An example looks like this:
*
- * |[<!-- language="C" -->
+ * ```c
* const char *text =
* "Go to the"
* "<a href=\"http://www.gtk.org title=\"<i>Our</i> website\">"
* "GTK website</a> for more...";
* GtkWidget *label = gtk_label_new (NULL);
* gtk_label_set_markup (GTK_LABEL (label), text);
- * ]|
+ * ```
*
- * It is possible to implement custom handling for links and their tooltips with
- * the #GtkLabel::activate-link signal and the gtk_label_get_current_uri() function.
+ * It is possible to implement custom handling for links and their tooltips
+ * with the [signal@Gtk.Label::activate-link] signal and the
+ * [method@Gtk.Label.get_current_uri] function.
*/
typedef struct _GtkLabelClass GtkLabelClass;
@@ -940,13 +937,14 @@ nope:
* @existing_layout: %NULL or an existing layout already in use.
* @width: the width to measure with in pango units, or -1 for infinite
*
- * Gets a layout that can be used for measuring sizes. The returned
- * layout will be identical to the label’s layout except for the
- * layout’s width, which will be set to @width. Do not modify the returned
- * layout.
+ * Gets a layout that can be used for measuring sizes.
+ *
+ * The returned layout will be identical to the label’s layout except for
+ * the layout’s width, which will be set to @width. Do not modify the
+ * returned layout.
*
* Returns: a new reference to a pango layout
- **/
+ */
static PangoLayout *
gtk_label_get_measuring_layout (GtkLabel *self,
PangoLayout *existing_layout,
@@ -2075,11 +2073,11 @@ gtk_label_class_init (GtkLabelClass *class)
* @count: the number of @step units to move
* @extend_selection: %TRUE if the move should extend the selection
*
- * The ::move-cursor signal is a
- * [keybinding signal][GtkSignalAction]
- * which gets emitted when the user initiates a cursor movement.
- * If the cursor is not visible in @entry, this signal causes
- * the viewport to be moved instead.
+ * Gets emitted when the user initiates a cursor movement.
+ *
+ * The ::move-cursor signal is a [keybinding signal](class.SignalAction.html).
+ * If the cursor is not visible in @entry, this signal causes the viewport to
+ * be moved instead.
*
* Applications should not connect to it, but may emit it with
* g_signal_emit_by_name() if they need to control the cursor
@@ -2109,9 +2107,9 @@ gtk_label_class_init (GtkLabelClass *class)
* GtkLabel::copy-clipboard:
* @self: the object which received the signal
*
- * The ::copy-clipboard signal is a
- * [keybinding signal][GtkSignalAction]
- * which gets emitted to copy the selection to the clipboard.
+ * Gets emitted to copy the slection to the clipboard.
+ *
+ * The ::copy-clipboard signal is a [keybinding signal](class.SignalAction.html).
*
* The default binding for this signal is Ctrl-c.
*/
@@ -2128,8 +2126,9 @@ gtk_label_class_init (GtkLabelClass *class)
* GtkLabel::activate-current-link:
* @self: The label on which the signal was emitted
*
- * A [keybinding signal][GtkSignalAction]
- * which gets emitted when the user activates a link in the label.
+ * Gets emitted when the user activates a link in the label.
+ *
+ * The ::activate-current-link is a [keybinding signal](class.SignalAction.html).
*
* Applications may also emit the signal with g_signal_emit_by_name()
* if they need to control activation of URIs programmatically.
@@ -2150,7 +2149,8 @@ gtk_label_class_init (GtkLabelClass *class)
* @self: The label on which the signal was emitted
* @uri: the URI that is activated
*
- * The signal which gets emitted to activate a URI.
+ * Gets emitted to activate a URI.
+ *
* Applications may connect to it to override the default behaviour,
* which is to call gtk_show_uri().
*
@@ -2170,15 +2170,16 @@ gtk_label_class_init (GtkLabelClass *class)
*
* The contents of the label.
*
- * If the string contains [Pango XML markup][PangoMarkupFormat], you will
- * have to set the #GtkLabel:use-markup property to %TRUE in order for the
- * label to display the markup attributes. See also gtk_label_set_markup()
- * for a convenience function that sets both this property and the
- * #GtkLabel:use-markup property at the same time.
+ * If the string contains Pango markup (see [func@Pango.parse_markup]),
+ * you will have to set the [property@Gtk.Label:use-markup] property to
+ * %TRUE in order for the label to display the markup attributes. See also
+ * [method@Gtk.Label.set_markup] for a convenience function that sets both
+ * this property and the [property@Gtk.Label:use-markup] property at the
+ * same time.
*
* If the string contains underlines acting as mnemonics, you will have to
- * set the #GtkLabel:use-underline property to %TRUE in order for the label
- * to display them.
+ * set the [property@Gtk.Label:use-underline] property to %TRUE in order
+ * for the label to display them.
*/
label_props[PROP_LABEL] =
g_param_spec_string ("label",
@@ -2187,6 +2188,11 @@ gtk_label_class_init (GtkLabelClass *class)
"",
GTK_PARAM_READWRITE);
+ /**
+ * GtkLabel:attributes:
+ *
+ * A list of style attributes to apply to the text of the label.
+ */
label_props[PROP_ATTRIBUTES] =
g_param_spec_boxed ("attributes",
P_("Attributes"),
@@ -2194,6 +2200,13 @@ gtk_label_class_init (GtkLabelClass *class)
PANGO_TYPE_ATTR_LIST,
GTK_PARAM_READWRITE);
+ /**
+ * GtkLabel:use-markup:
+ *
+ * %TRUE if the text of the label includes Pango markup.
+ *
+ * See [func@Pango.parse_markup].
+ */
label_props[PROP_USE_MARKUP] =
g_param_spec_boolean ("use-markup",
P_("Use markup"),
@@ -2201,6 +2214,11 @@ gtk_label_class_init (GtkLabelClass *class)
FALSE,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkLabel:use-underline:
+ *
+ * %TRUE if the text of the label indicates a mnemonic with _.
+ */
label_props[PROP_USE_UNDERLINE] =
g_param_spec_boolean ("use-underline",
P_("Use underline"),
@@ -2208,6 +2226,14 @@ gtk_label_class_init (GtkLabelClass *class)
FALSE,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkLabel:justify:
+ *
+ * The alignment of the lines in the text of the label, relative to each other.
+ *
+ * This does *not* affect the alignment of the label within its allocation.
+ * See [property@Gtk.Label:xalign] for that.
+ */
label_props[PROP_JUSTIFY] =
g_param_spec_enum ("justify",
P_("Justification"),
@@ -2219,10 +2245,10 @@ gtk_label_class_init (GtkLabelClass *class)
/**
* GtkLabel:xalign:
*
- * The xalign property determines the horizontal alignment of the label text
- * inside the labels size allocation. Compare this to #GtkWidget:halign,
- * which determines how the labels size allocation is positioned in the
- * space available for the label.
+ * The horizontal alignment of the label text inside its size allocation.
+ *
+ * Compare this to [property@Gtk.Widget:halign], which determines how the
+ * labels size allocation is positioned in the space available for the label.
*/
label_props[PROP_XALIGN] =
g_param_spec_float ("xalign",
@@ -2235,10 +2261,10 @@ gtk_label_class_init (GtkLabelClass *class)
/**
* GtkLabel:yalign:
*
- * The yalign property determines the vertical alignment of the label text
- * inside the labels size allocation. Compare this to #GtkWidget:valign,
- * which determines how the labels size allocation is positioned in the
- * space available for the label.
+ * The vertical alignment of the label text inside its size allocation.
+ *
+ * Compare this to [property@Gtk.Widget:valign], which determines how the
+ * labels size allocation is positioned in the space available for the label.
*/
label_props[PROP_YALIGN] =
g_param_spec_float ("yalign",
@@ -2248,6 +2274,11 @@ gtk_label_class_init (GtkLabelClass *class)
0.5,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkLabel:wrap:
+ *
+ * %TRUE if the label text will wrap if it gets too wide.
+ */
label_props[PROP_WRAP] =
g_param_spec_boolean ("wrap",
P_("Line wrap"),
@@ -2258,9 +2289,11 @@ gtk_label_class_init (GtkLabelClass *class)
/**
* GtkLabel:wrap-mode:
*
- * If line wrapping is on (see the #GtkLabel:wrap property) this controls
- * how the line wrapping is done. The default is %PANGO_WRAP_WORD, which
- * means wrap on word boundaries.
+ * Controls how the line wrapping is done.
+ *
+ * This only affects the formatting if line wrapping is on (see the
+ * [property@Gtk.Label:wrap] property). The default is %PANGO_WRAP_WORD,
+ * which means wrap on word boundaries.
*/
label_props[PROP_WRAP_MODE] =
g_param_spec_enum ("wrap-mode",
@@ -2270,6 +2303,11 @@ gtk_label_class_init (GtkLabelClass *class)
PANGO_WRAP_WORD,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkLabel:selectable:
+ *
+ * Whether the label text can be selected with the mouse.
+ */
label_props[PROP_SELECTABLE] =
g_param_spec_boolean ("selectable",
P_("Selectable"),
@@ -2277,6 +2315,11 @@ gtk_label_class_init (GtkLabelClass *class)
FALSE,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkLabel:mnemonic-keyval:
+ *
+ * The mnemonic accelerator key for the label.
+ */
label_props[PROP_MNEMONIC_KEYVAL] =
g_param_spec_uint ("mnemonic-keyval",
P_("Mnemonic key"),
@@ -2285,6 +2328,11 @@ gtk_label_class_init (GtkLabelClass *class)
GDK_KEY_VoidSymbol,
GTK_PARAM_READABLE);
+ /**
+ * GtkLabel:mnemonic-widget:
+ *
+ * The widget to be activated when the labels mnemonic key is pressed.
+ */
label_props[PROP_MNEMONIC_WIDGET] =
g_param_spec_object ("mnemonic-widget",
P_("Mnemonic widget"),
@@ -2296,16 +2344,15 @@ gtk_label_class_init (GtkLabelClass *class)
* GtkLabel:ellipsize:
*
* The preferred place to ellipsize the string, if the label does
- * not have enough room to display the entire string, specified as a
- * #PangoEllipsizeMode.
+ * not have enough room to display the entire string.
*
* Note that setting this property to a value other than
* %PANGO_ELLIPSIZE_NONE has the side-effect that the label requests
* only enough space to display the ellipsis "...". In particular, this
* means that ellipsizing labels do not work well in notebook tabs, unless
- * the #GtkNotebook tab-expand child property is set to %TRUE. Other ways
- * to set a label's width are gtk_widget_set_size_request() and
- * gtk_label_set_width_chars().
+ * the [property@Gtk.Notebook:tab-expand] child property is set to %TRUE.
+ * Other ways to set a label's width are [method@Gtk.Widget.set_size_request]
+ * and [method@Gtk.Label.set_width_chars].
*/
label_props[PROP_ELLIPSIZE] =
g_param_spec_enum ("ellipsize",
@@ -2318,13 +2365,14 @@ gtk_label_class_init (GtkLabelClass *class)
/**
* GtkLabel:width-chars:
*
- * The desired width of the label, in characters. If this property is set to
- * -1, the width will be calculated automatically.
+ * The desired width of the label, in characters.
+ *
+ * If this property is set to -1, the width will be calculated automatically.
*
- * See the section on [text layout][label-text-layout]
- * for details of how #GtkLabel:width-chars and #GtkLabel:max-width-chars
+ * See the section on [text layout][label-text-layout] for details of how
+ * [property@Gtk.Label:width-chars] and [property@Gtk.Label:max-width-chars]
* determine the width of ellipsized and wrapped labels.
- **/
+ */
label_props[PROP_WIDTH_CHARS] =
g_param_spec_int ("width-chars",
P_("Width In Characters"),
@@ -2336,12 +2384,13 @@ gtk_label_class_init (GtkLabelClass *class)
/**
* GtkLabel:single-line-mode:
*
- * Whether the label is in single line mode. In single line mode,
- * the height of the label does not depend on the actual text, it
- * is always set to ascent + descent of the font. This can be an
- * advantage in situations where resizing the label because of text
- * changes would be distracting, e.g. in a statusbar.
- **/
+ * Whether the label is in single line mode.
+ *
+ * In single line mode, the height of the label does not depend on the
+ * actual text, it is always set to ascent + descent of the font. This
+ * can be an advantage in situations where resizing the label because
+ * of text changes would be distracting, e.g. in a statusbar.
+ */
label_props[PROP_SINGLE_LINE_MODE] =
g_param_spec_boolean ("single-line-mode",
P_("Single Line Mode"),
@@ -2352,13 +2401,14 @@ gtk_label_class_init (GtkLabelClass *class)
/**
* GtkLabel:max-width-chars:
*
- * The desired maximum width of the label, in characters. If this property
- * is set to -1, the width will be calculated automatically.
+ * The desired maximum width of the label, in characters.
+ *
+ * If this property is set to -1, the width will be calculated automatically.
*
- * See the section on [text layout][label-text-layout]
- * for details of how #GtkLabel:width-chars and #GtkLabel:max-width-chars
+ * See the section on [text layout][label-text-layout] for details of how
+ * [property@Gtk.Label:width-chars] and [property@Gtk.Label:max-width-chars]
* determine the width of ellipsized and wrapped labels.
- **/
+ */
label_props[PROP_MAX_WIDTH_CHARS] =
g_param_spec_int ("max-width-chars",
P_("Maximum Width In Characters"),
@@ -2371,9 +2421,10 @@ gtk_label_class_init (GtkLabelClass *class)
* GtkLabel:lines:
*
* The number of lines to which an ellipsized, wrapping label
- * should be limited. This property has no effect if the
- * label is not wrapping or ellipsized. Set this property to
- * -1 if you don't want to limit the number of lines.
+ * should be limited.
+ *
+ * This property has no effect if the label is not wrapping or ellipsized.
+ * Set this property to -1 if you don't want to limit the number of lines.
*/
label_props[PROP_LINES] =
g_param_spec_int ("lines",
@@ -2386,8 +2437,7 @@ gtk_label_class_init (GtkLabelClass *class)
/**
* GtkLabel:extra-menu:
*
- * A menu model whose contents will be appended to
- * the context menu.
+ * A menu model whose contents will be appended to the context menu.
*/
label_props[PROP_EXTRA_MENU] =
g_param_spec_object ("extra-menu",
@@ -2586,10 +2636,11 @@ gtk_label_class_init (GtkLabelClass *class)
* gtk_label_new:
* @str: (nullable): The text of the label
*
- * Creates a new label with the given text inside it. You can
- * pass %NULL to get an empty label widget.
+ * Creates a new label with the given text inside it.
*
- * Returns: the new #GtkLabel
+ * You can pass %NULL to get an empty label widget.
+ *
+ * Returns: the new `GtkLabel`
**/
GtkWidget*
gtk_label_new (const char *str)
@@ -2609,22 +2660,22 @@ gtk_label_new (const char *str)
* @str: (nullable): The text of the label, with an underscore in front of the
* mnemonic character
*
- * Creates a new #GtkLabel, containing the text in @str.
+ * Creates a new `GtkLabel`, containing the text in @str.
*
* If characters in @str are preceded by an underscore, they are
* underlined. If you need a literal underscore character in a label, use
* '__' (two underscores). The first underlined character represents a
* keyboard accelerator called a mnemonic. The mnemonic key can be used
* to activate another widget, chosen automatically, or explicitly using
- * gtk_label_set_mnemonic_widget().
+ * [method@Gtk.Label.set_mnemonic_widget].
*
- * If gtk_label_set_mnemonic_widget() is not called, then the first
- * activatable ancestor of the #GtkLabel will be chosen as the mnemonic
+ * If [method@Gtk.Label.set_mnemonic_widget] is not called, then the first
+ * activatable ancestor of the `GtkLabel` will be chosen as the mnemonic
* widget. For instance, if the label is inside a button or menu item,
* the button or menu item will automatically become the mnemonic widget
* and be activated by the mnemonic.
*
- * Returns: the new #GtkLabel
+ * Returns: the new `GtkLabel`
**/
GtkWidget*
gtk_label_new_with_mnemonic (const char *str)
@@ -2752,24 +2803,27 @@ label_mnemonic_widget_weak_notify (gpointer data,
/**
* gtk_label_set_mnemonic_widget:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
* @widget: (nullable): the target #GtkWidget, or %NULL to unset
*
+ * Associate the label with its mnemonic target.
+ *
* If the label has been set so that it has a mnemonic key (using
- * i.e. gtk_label_set_markup_with_mnemonic(),
- * gtk_label_set_text_with_mnemonic(), gtk_label_new_with_mnemonic()
- * or the “use_underline” property) the label can be associated with a
- * widget that is the target of the mnemonic. When the label is inside
- * a widget (like a #GtkButton or a #GtkNotebook tab) it is
- * automatically associated with the correct widget, but sometimes
- * (i.e. when the target is a #GtkEntry next to the label) you need to
- * set it explicitly using this function.
+ * i.e. [method@Gtk.Label.set_markup_with_mnemonic],
+ * [method@Gtk.Label.set_text_with_mnemonic],
+ * [method@Gtk.Label.new_with_mnemonic]
+ * or the [property@Gtk.Label:use_underline] property) the label can be
+ * associated with a widget that is the target of the mnemonic. When the
+ * label is inside a widget (like a [class@Gtk.Button] or a
+ * [class@Gtk.Notebook] tab) it is automatically associated with the correct
+ * widget, but sometimes (i.e. when the target is a [class@Gtk.Entry] next to
+ * the label) you need to set it explicitly using this function.
*
* The target widget will be accelerated by emitting the
- * GtkWidget::mnemonic-activate signal on it. The default handler for
+ * [signal@GtkWidget::mnemonic-activate] signal on it. The default handler for
* this signal will activate the widget if there are no mnemonic collisions
* and toggle focus between the colliding widgets otherwise.
- **/
+ */
void
gtk_label_set_mnemonic_widget (GtkLabel *self,
GtkWidget *widget)
@@ -2800,10 +2854,12 @@ gtk_label_set_mnemonic_widget (GtkLabel *self,
/**
* gtk_label_get_mnemonic_widget:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
*
* Retrieves the target of the mnemonic (keyboard shortcut) of this
- * label. See gtk_label_set_mnemonic_widget().
+ * label.
+ *
+ * See [method@Gtk.Label.set_mnemonic_widget].
*
* Returns: (nullable) (transfer none): the target of the label’s mnemonic,
* or %NULL if none has been set and the default algorithm will be used.
@@ -2818,13 +2874,15 @@ gtk_label_get_mnemonic_widget (GtkLabel *self)
/**
* gtk_label_get_mnemonic_keyval:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
+ *
+ * Return the mnemonic accelerator.
*
* If the label has been set so that it has a mnemonic key this function
* returns the keyval used for the mnemonic accelerator. If there is no
- * mnemonic set up it returns #GDK_KEY_VoidSymbol.
+ * mnemonic set up it returns `GDK_KEY_VoidSymbol`.
*
- * Returns: GDK keyval usable for accelerators, or #GDK_KEY_VoidSymbol
+ * Returns: GDK keyval usable for accelerators, or `GDK_KEY_VoidSymbol`
**/
guint
gtk_label_get_mnemonic_keyval (GtkLabel *self)
@@ -2936,20 +2994,22 @@ gtk_label_recalculate (GtkLabel *self)
/**
* gtk_label_set_text:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
* @str: The text you want to set
*
- * Sets the text within the #GtkLabel widget. It overwrites any text that
- * was there before.
+ * Sets the text within the `GtkLabel` widget.
+ *
+ * It overwrites any text that was there before.
*
- * This function will clear any previously set mnemonic accelerators, and
- * set the #GtkLabel:use-underline property to %FALSE as a side effect.
+ * This function will clear any previously set mnemonic accelerators,
+ * and set the [property@Gtk.Label:use-underline property] to %FALSE as
+ * a side effect.
*
- * This function will set the #GtkLabel:use-markup property to %FALSE
- * as a side effect.
+ * This function will set the [property@Gtk.Label:use-markup] property
+ * to %FALSE as a side effect.
*
- * See also: gtk_label_set_markup()
- **/
+ * See also: [method@Gtk.Label.set_markup]
+ */
void
gtk_label_set_text (GtkLabel *self,
const char *str)
@@ -2972,19 +3032,18 @@ gtk_label_set_text (GtkLabel *self,
/**
* gtk_label_set_attributes:
- * @self: a #GtkLabel
- * @attrs: (nullable): a #PangoAttrList, or %NULL
- *
- * Sets a #PangoAttrList; the attributes in the list are applied to the
- * label text.
- *
- * The attributes set with this function will be applied
- * and merged with any other attributes previously effected by way
- * of the #GtkLabel:use-underline or #GtkLabel:use-markup properties.
- * While it is not recommended to mix markup strings with manually set
- * attributes, if you must; know that the attributes will be applied
- * to the label after the markup string is parsed.
- **/
+ * @self: a `GtkLabel`
+ * @attrs: (nullable): a [class@Pango.AttrList], or %NULL
+ *
+ * Apply attributes to the label text.
+ *
+ * The attributes set with this function will be applied and merged with
+ * any other attributes previously effected by way of the
+ * [property@Gtk.Label:use-underline] or [property@Gtk.Label:use-markup]
+ * properties. While it is not recommended to mix markup strings with
+ * manually set attributes, if you must; know that the attributes will
+ * be applied to the label after the markup string is parsed.
+ */
void
gtk_label_set_attributes (GtkLabel *self,
PangoAttrList *attrs)
@@ -3009,18 +3068,20 @@ gtk_label_set_attributes (GtkLabel *self,
/**
* gtk_label_get_attributes:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
+ *
+ * Gets the labels attribute list.
*
- * Gets the attribute list that was set on the label using
- * gtk_label_set_attributes(), if any. This function does
- * not reflect attributes that come from the labels markup
- * (see gtk_label_set_markup()). If you want to get the
- * effective attributes for the label, use
- * pango_layout_get_attribute (gtk_label_get_layout (self)).
+ * This is the [class@Pango.AttrList] that was set on the label using
+ * [method@Gtk.Label.set_attributes], if any. This function does not
+ * reflect attributes that come from the labels markup (see
+ * [method@Gtk.Label.set_markup]). If you want to get the effective
+ * attributes for the label, use
+ * `pango_layout_get_attribute (gtk_label_get_layout (self))`.
*
* Returns: (nullable) (transfer none): the attribute list, or %NULL
* if none was set.
- **/
+ */
PangoAttrList *
gtk_label_get_attributes (GtkLabel *self)
{
@@ -3031,14 +3092,15 @@ gtk_label_get_attributes (GtkLabel *self)
/**
* gtk_label_set_label:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
* @str: the new text to set for the label
*
- * Sets the text of the label. The label is interpreted as
- * including embedded underlines and/or Pango markup depending
- * on the values of the #GtkLabel:use-underline and
- * #GtkLabel:use-markup properties.
- **/
+ * Sets the text of the label.
+ *
+ * The label is interpreted as including embedded underlines and/or Pango
+ * markup depending on the values of the [property@Gtk.Label:use-underline]
+ * and [property@Gtk.Label:use-markup] properties.
+ */
void
gtk_label_set_label (GtkLabel *self,
const char *str)
@@ -3055,15 +3117,16 @@ gtk_label_set_label (GtkLabel *self,
/**
* gtk_label_get_label:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
*
- * Fetches the text from a label widget including any embedded
- * underlines indicating mnemonics and Pango markup. (See
- * gtk_label_get_text()).
+ * Fetches the text from a label.
+ *
+ * The returned text includes any embedded underlines indicating
+ * mnemonics and Pango markup. (See [method@Gtk.Label.get_text]).
*
* Returns: the text of the label widget. This string is
* owned by the widget and must not be modified or freed.
- **/
+ */
const char *
gtk_label_get_label (GtkLabel *self)
{
@@ -3528,17 +3591,18 @@ error_set:
/**
* gtk_label_set_markup:
- * @self: a #GtkLabel
- * @str: a markup string (see [Pango markup format][PangoMarkupFormat])
+ * @self: a `GtkLabel`
+ * @str: a markup string
+ *
+ * Sets the labels text and attributes from markup.
*
- * Parses @str which is marked up with the
- * [Pango text markup language][PangoMarkupFormat], setting the
- * label’s text and attribute list based on the parse results.
+ * The string must be marked up with Pango markup
+ * (see [func@Pango.parse_markup]).
*
- * If the @str is external data, you may need to escape it with
- * g_markup_escape_text() or g_markup_printf_escaped():
+ * If the @str is external data, you may need to escape it
+ * with g_markup_escape_text() or g_markup_printf_escaped():
*
- * |[<!-- language="C" -->
+ * ```c
* GtkWidget *self = gtk_label_new (NULL);
* const char *str = "...";
* const char *format = "<span style=\"italic\">\%s</span>";
@@ -3547,17 +3611,17 @@ error_set:
* markup = g_markup_printf_escaped (format, str);
* gtk_label_set_markup (GTK_LABEL (self), markup);
* g_free (markup);
- * ]|
+ * ```
*
- * This function will set the #GtkLabel:use-markup property to %TRUE as
- * a side effect.
+ * This function will set the [property@Gtk.Label:use-markup] property
+ * to %TRUE as a side effect.
*
- * If you set the label contents using the #GtkLabel:label property you
- * should also ensure that you set the #GtkLabel:use-markup property
- * accordingly.
+ * If you set the label contents using the [property@Gtk.Label:label]
+ * property you should also ensure that you set the
+ * [property@Gtk.Label:use-markup] property accordingly.
*
- * See also: gtk_label_set_text()
- **/
+ * See also: [method@Gtk.Label.set_text]
+ */
void
gtk_label_set_markup (GtkLabel *self,
const char *str)
@@ -3580,18 +3644,18 @@ gtk_label_set_markup (GtkLabel *self,
/**
* gtk_label_set_markup_with_mnemonic:
- * @self: a #GtkLabel
- * @str: a markup string (see
- * [Pango markup format][PangoMarkupFormat])
+ * @self: a `GtkLabel`
+ * @str: a markup string
+ *
+ * Sets the labels text, attributes and mnemonic from markup.
*
- * Parses @str which is marked up with the
- * [Pango text markup language][PangoMarkupFormat],
+ * Parses @str which is marked up with Pango markup (see [func@Pango.parse_markup]),
* setting the label’s text and attribute list based on the parse results.
* If characters in @str are preceded by an underscore, they are underlined
* indicating that they represent a keyboard accelerator called a mnemonic.
*
* The mnemonic key can be used to activate another widget, chosen
- * automatically, or explicitly using gtk_label_set_mnemonic_widget().
+ * automatically, or explicitly using method@Gtk.Label.set_mnemonic_widget].
*/
void
gtk_label_set_markup_with_mnemonic (GtkLabel *self,
@@ -3615,11 +3679,13 @@ gtk_label_set_markup_with_mnemonic (GtkLabel *self,
/**
* gtk_label_get_text:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
*
- * Fetches the text from a label widget, as displayed on the
- * screen. This does not include any embedded underlines
- * indicating mnemonics or Pango markup. (See gtk_label_get_label())
+ * Fetches the text from a label.
+ *
+ * The returned text is as it appears on screen. This does not include
+ * any embedded underlines indicating mnemonics or Pango markup. (See
+ * [method@Gtk.Label.get_label])
*
* Returns: the text in the label widget. This is the internal
* string used by the label, and must not be modified.
@@ -3634,15 +3700,17 @@ gtk_label_get_text (GtkLabel *self)
/**
* gtk_label_set_justify:
- * @self: a #GtkLabel
- * @jtype: a #GtkJustification
+ * @self: a `GtkLabel`
+ * @jtype: a `GtkJustification`
*
* Sets the alignment of the lines in the text of the label relative to
- * each other. %GTK_JUSTIFY_LEFT is the default value when the widget is
- * first created with gtk_label_new(). If you instead want to set the
- * alignment of the label as a whole, use gtk_widget_set_halign() instead.
- * gtk_label_set_justify() has no effect on labels containing only a
- * single line.
+ * each other.
+ *
+ * %GTK_JUSTIFY_LEFT is the default value when the widget is first created
+ * with [method Gtk Label new]. If you instead want to set the alignment of
+ * the label as a whole, use [method@Gtk.Widget.set_halign] instead.
+ * [method@Gtk.Label.set_justify] has no effect on labels containing
+ * only a single line.
*/
void
gtk_label_set_justify (GtkLabel *self,
@@ -3665,11 +3733,13 @@ gtk_label_set_justify (GtkLabel *self,
/**
* gtk_label_get_justify:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
*
- * Returns the justification of the label. See gtk_label_set_justify().
+ * Returns the justification of the label.
*
- * Returns: #GtkJustification
+ * See [method@Gtk.Label.set_justify].
+ *
+ * Returns: `GtkJustification`
**/
GtkJustification
gtk_label_get_justify (GtkLabel *self)
@@ -3681,12 +3751,14 @@ gtk_label_get_justify (GtkLabel *self)
/**
* gtk_label_set_ellipsize:
- * @self: a #GtkLabel
- * @mode: a #PangoEllipsizeMode
+ * @self: a `GtkLabel`
+ * @mode: a `PangoEllipsizeMode`
*
- * Sets the mode used to ellipsize (add an ellipsis: "...") to the text
- * if there is not enough space to render the entire string.
- **/
+ * Sets the mode used to ellipsizei the text.
+ *
+ * The text will be ellipsized if there is not enough space
+ * to render the entire string.
+ */
void
gtk_label_set_ellipsize (GtkLabel *self,
PangoEllipsizeMode mode)
@@ -3708,12 +3780,14 @@ gtk_label_set_ellipsize (GtkLabel *self,
/**
* gtk_label_get_ellipsize:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
*
- * Returns the ellipsizing position of the label. See gtk_label_set_ellipsize().
+ * Returns the ellipsizing position of the label.
*
- * Returns: #PangoEllipsizeMode
- **/
+ * See [method@Gtk.Label.set_ellipsize].
+ *
+ * Returns: `PangoEllipsizeMode`
+ **/
PangoEllipsizeMode
gtk_label_get_ellipsize (GtkLabel *self)
{
@@ -3724,11 +3798,11 @@ gtk_label_get_ellipsize (GtkLabel *self)
/**
* gtk_label_set_width_chars:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
* @n_chars: the new desired width, in characters.
*
* Sets the desired width in characters of @label to @n_chars.
- **/
+ */
void
gtk_label_set_width_chars (GtkLabel *self,
int n_chars)
@@ -3745,13 +3819,14 @@ gtk_label_set_width_chars (GtkLabel *self,
/**
* gtk_label_get_width_chars:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
+ *
+ * Retrieves the desired width of @label, in characters.
*
- * Retrieves the desired width of @label, in characters. See
- * gtk_label_set_width_chars().
+ * See [method@Gtk.Label.set_width_chars].
*
* Returns: the width of the label in characters.
- **/
+ */
int
gtk_label_get_width_chars (GtkLabel *self)
{
@@ -3762,11 +3837,11 @@ gtk_label_get_width_chars (GtkLabel *self)
/**
* gtk_label_set_max_width_chars:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
* @n_chars: the new desired maximum width, in characters.
*
* Sets the desired maximum width in characters of @label to @n_chars.
- **/
+ */
void
gtk_label_set_max_width_chars (GtkLabel *self,
int n_chars)
@@ -3784,10 +3859,11 @@ gtk_label_set_max_width_chars (GtkLabel *self,
/**
* gtk_label_get_max_width_chars:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
*
- * Retrieves the desired maximum width of @label, in characters. See
- * gtk_label_set_width_chars().
+ * Retrieves the desired maximum width of @label, in characters.
+ *
+ * See [method@Gtk.Label.set_width_chars].
*
* Returns: the maximum width of the label in characters.
**/
@@ -3801,19 +3877,21 @@ gtk_label_get_max_width_chars (GtkLabel *self)
/**
* gtk_label_set_wrap:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
* @wrap: the setting
*
- * Toggles line wrapping within the #GtkLabel widget. %TRUE makes it break
- * lines if text exceeds the widget’s size. %FALSE lets the text get cut off
- * by the edge of the widget if it exceeds the widget size.
+ * Toggles line wrapping within the `GtkLabel` widget.
+ *
+ * %TRUE makes it break lines if text exceeds the widget’s size.
+ * %FALSE lets the text get cut off by the edge of the widget if
+ * it exceeds the widget size.
*
* Note that setting line wrapping to %TRUE does not make the label
* wrap at its parent container’s width, because GTK widgets
* conceptually can’t make their requisition depend on the parent
* container’s size. For a label that wraps at a specific position,
- * set the label’s width using gtk_widget_set_size_request().
- **/
+ * set the label’s width using [method@Gtk.Widget.set_size_request].
+ */
void
gtk_label_set_wrap (GtkLabel *self,
gboolean wrap)
@@ -3834,10 +3912,11 @@ gtk_label_set_wrap (GtkLabel *self,
/**
* gtk_label_get_wrap:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
*
* Returns whether lines in the label are automatically wrapped.
- * See gtk_label_set_wrap().
+ *
+ * See [method@Gtk.Label.set_wrap].
*
* Returns: %TRUE if the lines of the label are automatically wrapped.
*/
@@ -3851,13 +3930,15 @@ gtk_label_get_wrap (GtkLabel *self)
/**
* gtk_label_set_wrap_mode:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
* @wrap_mode: the line wrapping mode
*
- * If line wrapping is on (see gtk_label_set_wrap()) this controls how
- * the line wrapping is done. The default is %PANGO_WRAP_WORD which means
- * wrap on word boundaries.
- **/
+ * Controls how line wrapping is done.
+ *
+ * This only affects the label if line wrapping is on. (See
+ * [method@Gtk.Label.set_wrap]) The default is %PANGO_WRAP_WORD
+ * which means wrap on word boundaries.
+ */
void
gtk_label_set_wrap_mode (GtkLabel *self,
PangoWrapMode wrap_mode)
@@ -3875,9 +3956,11 @@ gtk_label_set_wrap_mode (GtkLabel *self,
/**
* gtk_label_get_wrap_mode:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
*
- * Returns line wrap mode used by the label. See gtk_label_set_wrap_mode().
+ * Returns line wrap mode used by the label.
+ *
+ * See [method@Gtk.Label.set_wrap_mode].
*
* Returns: %TRUE if the lines of the label are automatically wrapped.
*/
@@ -3942,15 +4025,16 @@ gtk_label_ensure_layout (GtkLabel *self)
/**
* gtk_label_set_text_with_mnemonic:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
* @str: a string
*
* Sets the label’s text from the string @str.
+ *
* If characters in @str are preceded by an underscore, they are underlined
* indicating that they represent a keyboard accelerator called a mnemonic.
* The mnemonic key can be used to activate another widget, chosen
- * automatically, or explicitly using gtk_label_set_mnemonic_widget().
- **/
+ * automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget].
+ */
void
gtk_label_set_text_with_mnemonic (GtkLabel *self,
const char *str)
@@ -4646,12 +4730,14 @@ gtk_label_clear_select_info (GtkLabel *self)
/**
* gtk_label_set_selectable:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
* @setting: %TRUE to allow selecting text in the label
*
- * Selectable labels allow the user to select text from the label, for
- * copy-and-paste.
- **/
+ * Makes text in the label selectable.
+ *
+ * Selectable labels allow the user to select text from the label,
+ * for copy-and-paste.
+ */
void
gtk_label_set_selectable (GtkLabel *self,
gboolean setting)
@@ -4691,12 +4777,12 @@ gtk_label_set_selectable (GtkLabel *self,
/**
* gtk_label_get_selectable:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
*
- * Gets the value set by gtk_label_set_selectable().
+ * Returns whether the label is selectable.
*
* Returns: %TRUE if the user can copy text from the label
- **/
+ */
gboolean
gtk_label_get_selectable (GtkLabel *self)
{
@@ -4820,15 +4906,16 @@ gtk_label_select_region_index (GtkLabel *self,
/**
* gtk_label_select_region:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
* @start_offset: start offset (in characters not bytes)
* @end_offset: end offset (in characters not bytes)
*
* Selects a range of characters in the label, if the label is selectable.
- * See gtk_label_set_selectable(). If the label is not selectable,
+ *
+ * See [method@Gtk.Label.set_selectable]. If the label is not selectable,
* this function has no effect. If @start_offset or
* @end_offset are -1, then the end of the label will be substituted.
- **/
+ */
void
gtk_label_select_region (GtkLabel *self,
int start_offset,
@@ -4852,12 +4939,11 @@ gtk_label_select_region (GtkLabel *self,
/**
* gtk_label_get_selection_bounds:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
* @start: (out): return location for start of selection, as a character offset
* @end: (out): return location for end of selection, as a character offset
*
- * Gets the selected range of characters in the label, returning %TRUE
- * if there’s a selection.
+ * Gets the selected range of characters in the label.
*
* Returns: %TRUE if selection is non-empty
**/
@@ -4920,17 +5006,18 @@ gtk_label_get_selection_bounds (GtkLabel *self,
/**
* gtk_label_get_layout:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
*
- * Gets the #PangoLayout used to display the label.
- * The layout is useful to e.g. convert text positions to
- * pixel positions, in combination with gtk_label_get_layout_offsets().
+ * Gets the `PangoLayout` used to display the label.
+ *
+ * The layout is useful to e.g. convert text positions to pixel
+ * positions, in combination with [method@Gtk.Label.get_layout_offset].
* The returned layout is owned by the @label so need not be
- * freed by the caller. The @label is free to recreate its layout at
- * any time, so it should be considered read-only.
+ * freed by the caller. The @label is free to recreate its layout
+ * at any time, so it should be considered read-only.
*
- * Returns: (transfer none): the #PangoLayout for this label
- **/
+ * Returns: (transfer none): the [class@Pango.Layout] for this label
+ */
PangoLayout*
gtk_label_get_layout (GtkLabel *self)
{
@@ -4943,17 +5030,18 @@ gtk_label_get_layout (GtkLabel *self)
/**
* gtk_label_get_layout_offsets:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
* @x: (out) (optional): location to store X offset of layout, or %NULL
* @y: (out) (optional): location to store Y offset of layout, or %NULL
*
- * Obtains the coordinates where the label will draw the #PangoLayout
- * representing the text in the label; useful to convert mouse events
- * into coordinates inside the #PangoLayout, e.g. to take some action
- * if some part of the label is clicked. Remember
- * when using the #PangoLayout functions you need to convert to
- * and from pixels using PANGO_PIXELS() or #PANGO_SCALE.
- **/
+ * Obtains the coordinates where the label will draw its `PangoLayout`.
+ *
+ * The coordinates are useful to convert mouse events into coordinates
+ * inside the [class@Pango.Layout], e.g. to take some action if some part
+ * of the label is clicked. Remember when using the [class@Pango.Layout]
+ * functions you need to convert to and from pixels using PANGO_PIXELS()
+ * or [constant@Pango.SCALE].
+ */
void
gtk_label_get_layout_offsets (GtkLabel *self,
int *x,
@@ -4974,13 +5062,13 @@ gtk_label_get_layout_offsets (GtkLabel *self,
/**
* gtk_label_set_use_markup:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
* @setting: %TRUE if the label’s text should be parsed for markup.
*
- * Sets whether the text of the label contains markup in
- * [Pango’s text markup language][PangoMarkupFormat].
- * See gtk_label_set_markup().
- **/
+ * Sets whether the text of the label contains markup.
+ *
+ * See [method@Gtk.Label.set_markup].
+ */
void
gtk_label_set_use_markup (GtkLabel *self,
gboolean setting)
@@ -4997,14 +5085,14 @@ gtk_label_set_use_markup (GtkLabel *self,
/**
* gtk_label_get_use_markup:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
*
- * Returns whether the label’s text is interpreted as marked up with
- * the [Pango text markup language][PangoMarkupFormat].
- * See gtk_label_set_use_markup ().
+ * Returns whether the label’s text is interpreted as Pango markup.
+ *
+ * See [method@Gtk.Label.set_use_markup].
*
* Returns: %TRUE if the label’s text will be parsed for markup.
- **/
+ */
gboolean
gtk_label_get_use_markup (GtkLabel *self)
{
@@ -5015,11 +5103,10 @@ gtk_label_get_use_markup (GtkLabel *self)
/**
* gtk_label_set_use_underline:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
* @setting: %TRUE if underlines in the text indicate mnemonics
*
- * If true, an underline in the text indicates the next character should be
- * used for the mnemonic accelerator key.
+ * Sets whether underlines in the text indicate mnemonics.
*/
void
gtk_label_set_use_underline (GtkLabel *self,
@@ -5037,14 +5124,15 @@ gtk_label_set_use_underline (GtkLabel *self,
/**
* gtk_label_get_use_underline:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
+ *
+ * Returns whether an embedded underlines in the label indicate mnemonics.
*
- * Returns whether an embedded underline in the label indicates a
- * mnemonic. See gtk_label_set_use_underline().
+ * See [method@Gtk.Label.set_use_underline].
*
* Returns: %TRUE whether an embedded underline in the label indicates
- * the mnemonic accelerator keys.
- **/
+ * the mnemonic accelerator keys.
+ */
gboolean
gtk_label_get_use_underline (GtkLabel *self)
{
@@ -5055,7 +5143,7 @@ gtk_label_get_use_underline (GtkLabel *self)
/**
* gtk_label_set_single_line_mode:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
* @single_line_mode: %TRUE if the label should be in single line mode
*
* Sets whether the label is in single line mode.
@@ -5081,7 +5169,7 @@ gtk_label_set_single_line_mode (GtkLabel *self,
/**
* gtk_label_get_single_line_mode:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
*
* Returns whether the label is in single line mode.
*
@@ -5095,7 +5183,7 @@ gtk_label_get_single_line_mode (GtkLabel *self)
return self->single_line_mode;
}
-/* Compute the X position for an offset that corresponds to the "more important
+/* Compute the X position for an offset that corresponds to the more important
* cursor position for that offset. We use this when trying to guess to which
* end of the selection we should go to when the user hits the left or
* right arrow key.
@@ -5470,15 +5558,16 @@ gtk_label_do_popup (GtkLabel *self,
/**
* gtk_label_get_current_uri:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
*
* Returns the URI for the currently active link in the label.
+ *
* The active link is the one under the mouse pointer or, in a
* selectable label, the link in which the text cursor is currently
* positioned.
*
- * This function is intended for use in a #GtkLabel::activate-link handler
- * or for use in a #GtkWidget::query-tooltip handler.
+ * This function is intended for use in a [signal@Gtk.Label::activate-link]
+ * handler or for use in a [signal@Gtk.Widget::query-tooltip] handler.
*
* Returns: (nullable): the currently active URI or %NULL if there is none.
* The string is owned by GTK and must not be freed or modified.
@@ -5526,13 +5615,14 @@ _gtk_label_get_selection_bound (GtkLabel *self)
/**
* gtk_label_set_lines:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
* @lines: the desired number of lines, or -1
*
* Sets the number of lines to which an ellipsized, wrapping label
- * should be limited. This has no effect if the label is not wrapping
- * or ellipsized. Set this to -1 if you don’t want to limit the
- * number of lines.
+ * should be limited.
+ *
+ * This has no effect if the label is not wrapping or ellipsized.
+ * Set this to -1 if you don’t want to limit the number of lines.
*/
void
gtk_label_set_lines (GtkLabel *self,
@@ -5551,10 +5641,12 @@ gtk_label_set_lines (GtkLabel *self,
/**
* gtk_label_get_lines:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
*
* Gets the number of lines to which an ellipsized, wrapping
- * label should be limited. See gtk_label_set_lines().
+ * label should be limited.
+ *
+ * See [method@Gtk.Label.set_lines].
*
* Returns: The number of lines
*/
@@ -5568,10 +5660,12 @@ gtk_label_get_lines (GtkLabel *self)
/**
* gtk_label_set_xalign:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
* @xalign: the new xalign value, between 0 and 1
*
- * Sets the #GtkLabel:xalign property for @label.
+ * Sets the `xalign` of the label.
+ *
+ * See the [property@Gtk.Label:xalign] property.
*/
void
gtk_label_set_xalign (GtkLabel *self,
@@ -5592,9 +5686,11 @@ gtk_label_set_xalign (GtkLabel *self,
/**
* gtk_label_get_xalign:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
*
- * Gets the #GtkLabel:xalign property for @label.
+ * Gets the `xalign` of the label.
+ *
+ * See the [property@Gtk.Label:xalign] property.
*
* Returns: the xalign property
*/
@@ -5608,10 +5704,12 @@ gtk_label_get_xalign (GtkLabel *self)
/**
* gtk_label_set_yalign:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
* @yalign: the new yalign value, between 0 and 1
*
- * Sets the #GtkLabel:yalign property for @label.
+ * Sets the `yalign` of the label.
+ *
+ * See the [property@Gtk.Label:yalign] property.
*/
void
gtk_label_set_yalign (GtkLabel *self,
@@ -5632,9 +5730,11 @@ gtk_label_set_yalign (GtkLabel *self,
/**
* gtk_label_get_yalign:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
*
- * Gets the #GtkLabel:yalign property for @label.
+ * Gets the `yalign` of the label.
+ *
+ * See the [property@Gtk.Label:yalign] property.
*
* Returns: the yalign property
*/
@@ -5648,8 +5748,8 @@ gtk_label_get_yalign (GtkLabel *self)
/**
* gtk_label_set_extra_menu:
- * @self: a #GtkLabel
- * @model: (allow-none): a #GMenuModel
+ * @self: a `GtkLabel`
+ * @model: (allow-none): a `GMenuModel`
*
* Sets a menu model to add when constructing
* the context menu for @label.
@@ -5669,9 +5769,11 @@ gtk_label_set_extra_menu (GtkLabel *self,
/**
* gtk_label_get_extra_menu:
- * @self: a #GtkLabel
+ * @self: a `GtkLabel`
+ *
+ * Gets the extra menu model of @label.
*
- * Gets the menu model set with gtk_label_set_extra_menu().
+ * See [method@Gtk.Label.set_extra_menu].
*
* Returns: (transfer none) (nullable): the menu model
*/
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
