[gtk/ebassi/gidocgen: 129/200] entry: Convert docs
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk/ebassi/gidocgen: 129/200] entry: Convert docs
- Date: Thu, 25 Feb 2021 13:08:21 +0000 (UTC)
commit 13b5b115ccc0ccfa59cec89e7aa4247b46ae7541
Author: Matthias Clasen <mclasen redhat com>
Date: Sun Feb 21 19:43:32 2021 -0500
entry: Convert docs
Change link syntax, add an example image, generally clean things up.
gtk/gtkentry.c | 728 ++++++++++++++++++++++++++++++++-------------------------
1 file changed, 408 insertions(+), 320 deletions(-)
---
diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index c296f06c11..d9f74667d8 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -73,36 +73,37 @@
#include <string.h>
/**
- * SECTION:gtkentry
- * @Short_description: A single line text entry field
- * @Title: GtkEntry
- * @See_also: #GtkTextView, #GtkEntryCompletion
- *
- * The #GtkEntry widget is a single line text entry
- * widget. A fairly large set of key bindings are supported
- * by default. If the entered text is longer than the allocation
- * of the widget, the widget will scroll so that the cursor
- * position is visible.
- *
- * When using an entry for passwords and other sensitive information,
- * it can be put into “password mode” using gtk_entry_set_visibility().
+ * GtkEntry:
+ *
+ * `GtkEntry` is a single line text entry widget.
+ *
+ * 
+ *
+ * A fairly large set of key bindings are supported by default. If the
+ * entered text is longer than the allocation of the widget, the widget
+ * will scroll so that the cursor position is visible.
+ *
+ * When using an entry for passwords and other sensitive information, it
+ * can be put into “password mode” using [method@Gtk.Entry.set_visibility].
* In this mode, entered text is displayed using a “invisible” character.
* By default, GTK picks the best invisible character that is available
* in the current font, but it can be changed with
- * gtk_entry_set_invisible_char().
+ * [method@Gtk.Entry.set_invisible_char].
*
- * GtkEntry has the ability to display progress or activity
+ * `GtkEntry` has the ability to display progress or activity
* information behind the text. To make an entry display such information,
- * use gtk_entry_set_progress_fraction() or gtk_entry_set_progress_pulse_step().
- *
- * Additionally, GtkEntry can show icons at either side of the entry. These
- * icons can be activatable by clicking, can be set up as drag source and
- * can have tooltips. To add an icon, use gtk_entry_set_icon_from_gicon() or
- * one of the various other functions that set an icon from an icon name or a
- * paintable. To trigger an action when the user clicks an icon,
- * connect to the #GtkEntry::icon-press signal. To allow DND operations
- * from an icon, use gtk_entry_set_icon_drag_source(). To set a tooltip on
- * an icon, use gtk_entry_set_icon_tooltip_text() or the corresponding function
+ * use [method@Gtk.Entry.set_progress_fraction] or
+ * [method@Gtk.Entry.set_progress_pulse_step].
+ *
+ * Additionally, `GtkEntry` can show icons at either side of the entry.
+ * These icons can be activatable by clicking, can be set up as drag source
+ * and can have tooltips. To add an icon, use
+ * [method@Gtk.Entry.set_icon_from_gicon] or one of the various other functions
+ * that set an icon from an icon name or a paintable. To trigger an action when
+ * the user clicks an icon, connect to the [signal@Gtk.Entry::icon-press] signal.
+ * To allow DND operations from an icon, use
+ * [method@Gtk.Entry.set_icon_drag_source]. To set a tooltip on an icon, use
+ * [method@Gtk.Entry.set_icon_tooltip_text] or the corresponding function
* for markup.
*
* Note that functionality or information that is only available by clicking
@@ -121,7 +122,7 @@
* ╰── [progress[.pulse]]
* ]|
*
- * GtkEntry has a main node with the name entry. Depending on the properties
+ * `GtkEntry` has a main node with the name entry. Depending on the properties
* of the entry, the style classes .read-only and .flat may appear. The style
* classes .warning and .error may also be used with entries.
*
@@ -132,11 +133,11 @@
* The node has the style class .pulse when the shown progress is pulsing.
*
* For all the subnodes added to the text node in various situations,
- * see #GtkText.
+ * see [class Gtk Text].
*
* # GtkEntry as GtkBuildable
*
- * The GtkEntry implementation of the GtkBuildable interface supports a
+ * The `GtkEntry` 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
@@ -153,14 +154,14 @@
* ]|
*
* 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
- * applied to the whole text. Note that specifying ranges does not make much
+ * Pango attribute applies. If start and end are not specified, the attribute
+ * is applied to the whole text. Note that specifying ranges does not make much
* sense with translatable attributes. Use markup embedded in the translatable
* content instead.
*
* # Accessibility
*
- * GtkEntry uses the #GTK_ACCESSIBLE_ROLE_TEXT_BOX role.
+ * `GtkEntry` uses the %GTK_ACCESSIBLE_ROLE_TEXT_BOX role.
*/
#define MAX_ICONS 2
@@ -474,6 +475,11 @@ gtk_entry_class_init (GtkEntryClass *class)
quark_entry_completion = g_quark_from_static_string ("gtk-entry-completion-key");
+ /**
+ * GtkEntry:buffer
+ *
+ * The buffer object which actually stores the text.
+ */
entry_props[PROP_BUFFER] =
g_param_spec_object ("buffer",
P_("Text Buffer"),
@@ -481,6 +487,11 @@ gtk_entry_class_init (GtkEntryClass *class)
GTK_TYPE_ENTRY_BUFFER,
GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkEntry:max-length:
+ *
+ * Maximum number of characters for this entry.
+ */
entry_props[PROP_MAX_LENGTH] =
g_param_spec_int ("max-length",
P_("Maximum length"),
@@ -489,6 +500,12 @@ gtk_entry_class_init (GtkEntryClass *class)
0,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkEntry:visibility:
+ *
+ * Whether the entry should show the “invisible char” instead of the
+ * actual text (“password mode”).
+ */
entry_props[PROP_VISIBILITY] =
g_param_spec_boolean ("visibility",
P_("Visibility"),
@@ -496,6 +513,11 @@ gtk_entry_class_init (GtkEntryClass *class)
TRUE,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkEntry:has-frame:
+ *
+ * Whehter the entry should draw a frame.
+ */
entry_props[PROP_HAS_FRAME] =
g_param_spec_boolean ("has-frame",
P_("Has Frame"),
@@ -503,6 +525,11 @@ gtk_entry_class_init (GtkEntryClass *class)
TRUE,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkEntry:invisible=char:
+ *
+ * The character to use when masking entry contents (“password mode”).
+ */
entry_props[PROP_INVISIBLE_CHAR] =
g_param_spec_unichar ("invisible-char",
P_("Invisible character"),
@@ -510,6 +537,11 @@ gtk_entry_class_init (GtkEntryClass *class)
'*',
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkEntry:activates-default:
+ *
+ * Whether to activate the default widget when Enter is pressed.
+ */
entry_props[PROP_ACTIVATES_DEFAULT] =
g_param_spec_boolean ("activates-default",
P_("Activates default"),
@@ -517,6 +549,11 @@ gtk_entry_class_init (GtkEntryClass *class)
FALSE,
GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * GtkEntry:scroll-offset:
+ *
+ * Number of pixels of the entry scrolled off the screen to the left.
+ */
entry_props[PROP_SCROLL_OFFSET] =
g_param_spec_int ("scroll-offset",
P_("Scroll offset"),
@@ -540,7 +577,7 @@ gtk_entry_class_init (GtkEntryClass *class)
/**
* GtkEntry:overwrite-mode:
*
- * If text is overwritten when typing in the #GtkEntry.
+ * If text is overwritten when typing in the `GtkEntry`.
*/
entry_props[PROP_OVERWRITE_MODE] =
g_param_spec_boolean ("overwrite-mode",
@@ -552,7 +589,7 @@ gtk_entry_class_init (GtkEntryClass *class)
/**
* GtkEntry:text-length:
*
- * The length of the text in the #GtkEntry.
+ * The length of the text in the `GtkEntry`.
*/
entry_props[PROP_TEXT_LENGTH] =
g_param_spec_uint ("text-length",
@@ -565,7 +602,7 @@ gtk_entry_class_init (GtkEntryClass *class)
/**
* GtkEntry:invisible-char-set:
*
- * Whether the invisible char has been set for the #GtkEntry.
+ * Whether the invisible char has been set for the `GtkEntry`.
*/
entry_props[PROP_INVISIBLE_CHAR_SET] =
g_param_spec_boolean ("invisible-char-set",
@@ -591,7 +628,9 @@ gtk_entry_class_init (GtkEntryClass *class)
* GtkEntry:progress-pulse-step:
*
* The fraction of total entry width to move the progress
- * bouncing block for each call to gtk_entry_progress_pulse().
+ * bouncing block for each pulse.
+ *
+ * See [method@Gtk.Entry.progress_pulse].
*/
entry_props[PROP_PROGRESS_PULSE_STEP] =
g_param_spec_double ("progress-pulse-step",
@@ -604,7 +643,7 @@ gtk_entry_class_init (GtkEntryClass *class)
/**
* GtkEntry:placeholder-text:
*
- * The text that will be displayed in the #GtkEntry when it is empty
+ * The text that will be displayed in the `GtkEntry` when it is empty
* and unfocused.
*/
entry_props[PROP_PLACEHOLDER_TEXT] =
@@ -617,7 +656,7 @@ gtk_entry_class_init (GtkEntryClass *class)
/**
* GtkEntry:primary-icon-paintable:
*
- * A #GdkPaintable to use as the primary icon for the entry.
+ * A `GdkPaintable` to use as the primary icon for the entry.
*/
entry_props[PROP_PAINTABLE_PRIMARY] =
g_param_spec_object ("primary-icon-paintable",
@@ -629,7 +668,7 @@ gtk_entry_class_init (GtkEntryClass *class)
/**
* GtkEntry:secondary-icon-paintable:
*
- * A #GdkPaintable to use as the secondary icon for the entry.
+ * A `GdkPaintable` to use as the secondary icon for the entry.
*/
entry_props[PROP_PAINTABLE_SECONDARY] =
g_param_spec_object ("secondary-icon-paintable",
@@ -665,7 +704,7 @@ gtk_entry_class_init (GtkEntryClass *class)
/**
* GtkEntry:primary-icon-gicon:
*
- * The #GIcon to use for the primary icon for the entry.
+ * The `GIcon` to use for the primary icon for the entry.
*/
entry_props[PROP_GICON_PRIMARY] =
g_param_spec_object ("primary-icon-gicon",
@@ -677,7 +716,7 @@ gtk_entry_class_init (GtkEntryClass *class)
/**
* GtkEntry:secondary-icon-gicon:
*
- * The #GIcon to use for the secondary icon for the entry.
+ * The `GIcon` to use for the secondary icon for the entry.
*/
entry_props[PROP_GICON_SECONDARY] =
g_param_spec_object ("secondary-icon-gicon",
@@ -717,8 +756,9 @@ gtk_entry_class_init (GtkEntryClass *class)
*
* Whether the primary icon is activatable.
*
- * GTK emits the #GtkEntry::icon-press and #GtkEntry::icon-release
- * signals only on sensitive, activatable icons.
+ * GTK emits the [signal@Gtk.Entry::icon-press] and
+ * [signal@Gtk.Entry::icon-release] signals only on sensitive,
+ * activatable icons.
*
* Sensitive, but non-activatable icons can be used for purely
* informational purposes.
@@ -735,8 +775,9 @@ gtk_entry_class_init (GtkEntryClass *class)
*
* Whether the secondary icon is activatable.
*
- * GTK emits the #GtkEntry::icon-press and #GtkEntry::icon-release
- * signals only on sensitive, activatable icons.
+ * GTK emits the [signal@Gtk.Entry::icon-press] and
+ * [signal@Gtk.Entry::icon-release] signals only on sensitive,
+ * activatable icons.
*
* Sensitive, but non-activatable icons can be used for purely
* informational purposes.
@@ -754,8 +795,8 @@ gtk_entry_class_init (GtkEntryClass *class)
* Whether the primary icon is sensitive.
*
* An insensitive icon appears grayed out. GTK does not emit the
- * #GtkEntry::icon-press and #GtkEntry::icon-release signals and
- * does not allow DND from insensitive icons.
+ * [signal@Gtk.Entry::icon-press] and [signal@Gtk.Entry::icon-release]
+ * signals and does not allow DND from insensitive icons.
*
* An icon should be set insensitive if the action that would trigger
* when clicked is currently not available.
@@ -773,8 +814,8 @@ gtk_entry_class_init (GtkEntryClass *class)
* Whether the secondary icon is sensitive.
*
* An insensitive icon appears grayed out. GTK does not emit the
- * #GtkEntry::icon-press and #GtkEntry::icon-release signals and
- * does not allow DND from insensitive icons.
+ * [signal@Gtk.Entry::icon-press[ and [signal@Gtk.Entry::icon-release]
+ * signals and does not allow DND from insensitive icons.
*
* An icon should be set insensitive if the action that would trigger
* when clicked is currently not available.
@@ -791,7 +832,7 @@ gtk_entry_class_init (GtkEntryClass *class)
*
* The contents of the tooltip on the primary icon.
*
- * Also see gtk_entry_set_icon_tooltip_text().
+ * Also see [method@Gtk.Entry.set_icon_tooltip_text].
*/
entry_props[PROP_TOOLTIP_TEXT_PRIMARY] =
g_param_spec_string ("primary-icon-tooltip-text",
@@ -805,7 +846,7 @@ gtk_entry_class_init (GtkEntryClass *class)
*
* The contents of the tooltip on the secondary icon.
*
- * Also see gtk_entry_set_icon_tooltip_text().
+ * Also see [method@Gtk.Entry.set_icon_tooltip_text].
*/
entry_props[PROP_TOOLTIP_TEXT_SECONDARY] =
g_param_spec_string ("secondary-icon-tooltip-text",
@@ -817,10 +858,9 @@ gtk_entry_class_init (GtkEntryClass *class)
/**
* GtkEntry:primary-icon-tooltip-markup:
*
- * The contents of the tooltip on the primary icon, which is marked up
- * with the [Pango text markup language][PangoMarkupFormat].
+ * The contents of the tooltip on the primary icon, with markup.
*
- * Also see gtk_entry_set_icon_tooltip_markup().
+ * Also see [method@Gtk.Entry.set_icon_tooltip_markup].
*/
entry_props[PROP_TOOLTIP_MARKUP_PRIMARY] =
g_param_spec_string ("primary-icon-tooltip-markup",
@@ -832,10 +872,9 @@ gtk_entry_class_init (GtkEntryClass *class)
/**
* GtkEntry:secondary-icon-tooltip-markup:
*
- * The contents of the tooltip on the secondary icon, which is marked up
- * with the [Pango text markup language][PangoMarkupFormat].
+ * The contents of the tooltip on the secondary icon, with markup.
*
- * Also see gtk_entry_set_icon_tooltip_markup().
+ * Also see [method@Gtk.Entry.set_icon_tooltip_markup].
*/
entry_props[PROP_TOOLTIP_MARKUP_SECONDARY] =
g_param_spec_string ("secondary-icon-tooltip-markup",
@@ -848,11 +887,12 @@ gtk_entry_class_init (GtkEntryClass *class)
* GtkEntry:im-module:
*
* Which IM (input method) module should be used for this entry.
- * See #GtkIMContext.
*
- * Setting this to a non-%NULL value overrides the
- * system-wide IM module setting. See the GtkSettings
- * #GtkSettings:gtk-im-module property.
+ * See [class@Gtk.IMContext].
+ *
+ * Setting this to a non-%NULL value overrides the system-wide IM
+ * module setting. See the GtkSettings [property@Gtk.Settings:gtk-im-module]
+ * property.
*/
entry_props[PROP_IM_MODULE] =
g_param_spec_string ("im-module",
@@ -883,7 +923,7 @@ gtk_entry_class_init (GtkEntryClass *class)
*
* Note that setting the purpose to %GTK_INPUT_PURPOSE_PASSWORD or
* %GTK_INPUT_PURPOSE_PIN is independent from setting
- * #GtkEntry:visibility.
+ * [property@Gtk.Entry:visibility].
*/
entry_props[PROP_INPUT_PURPOSE] =
g_param_spec_enum ("input-purpose",
@@ -896,8 +936,9 @@ gtk_entry_class_init (GtkEntryClass *class)
/**
* GtkEntry:input-hints:
*
- * Additional hints (beyond #GtkEntry:input-purpose) that
- * allow input methods to fine-tune their behaviour.
+ * Additional hints that allow input methods to fine-tune their behavior.
+ *
+ * Also see [property@Gtk.Entry:input-purpose]
*/
entry_props[PROP_INPUT_HINTS] =
g_param_spec_flags ("input-hints",
@@ -915,7 +956,7 @@ gtk_entry_class_init (GtkEntryClass *class)
* This is mainly useful to change the size or weight of the text.
*
* The #PangoAttribute's @start_index and @end_index must refer to the
- * #GtkEntryBuffer text, i.e. without the preedit string.
+ * [class@Gtk.EntryBuffer] text, i.e. without the preedit string.
*/
entry_props[PROP_ATTRIBUTES] =
g_param_spec_boxed ("attributes",
@@ -939,8 +980,8 @@ gtk_entry_class_init (GtkEntryClass *class)
/**
* GtkEntry::show-emoji-icon:
*
- * When this is %TRUE, the entry will show an emoji icon in the secondary
- * icon position that brings up the Emoji chooser when clicked.
+ * Whether the entry will sohw an Emoji icon in the secondary icon position
+ * to open the Emoji chooser.
*/
entry_props[PROP_SHOW_EMOJI_ICON] =
g_param_spec_boolean ("show-emoji-icon",
@@ -952,8 +993,7 @@ gtk_entry_class_init (GtkEntryClass *class)
/**
* GtkEntry: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.
*/
entry_props[PROP_EXTRA_MENU] =
g_param_spec_object ("extra-menu",
@@ -977,9 +1017,9 @@ gtk_entry_class_init (GtkEntryClass *class)
* GtkEntry::activate:
* @self: The widget on which the signal is emitted
*
- * The ::activate signal is forwarded from the
- * #GtkText::activated signal, which is a keybinding
- * signal for all forms of the Enter key.
+ * Emitted when the entry is activated.
+ *
+ * The keybindings for this signal are all forms of the Enter key.
*/
signals[ACTIVATE] =
g_signal_new (I_("activate"),
@@ -995,8 +1035,7 @@ gtk_entry_class_init (GtkEntryClass *class)
* @entry: The entry on which the signal is emitted
* @icon_pos: The position of the clicked icon
*
- * The ::icon-press signal is emitted when an activatable icon
- * is clicked.
+ * Emitted when an activatable icon is clicked.
*/
signals[ICON_PRESS] =
g_signal_new (I_("icon-press"),
@@ -1013,8 +1052,8 @@ gtk_entry_class_init (GtkEntryClass *class)
* @entry: The entry on which the signal is emitted
* @icon_pos: The position of the clicked icon
*
- * The ::icon-release signal is emitted on the button release from a
- * mouse click over an activatable icon.
+ * Emitted on the button release from a mouse click
+ * over an activatable icon.
*/
signals[ICON_RELEASE] =
g_signal_new (I_("icon-release"),
@@ -1828,15 +1867,14 @@ gtk_entry_snapshot (GtkWidget *widget,
/**
* gtk_entry_grab_focus_without_selecting:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
* Causes @entry to have keyboard focus.
*
- * It behaves like gtk_widget_grab_focus(),
- * except that it doesn't select the contents of the entry.
- * You only want to call this on some special entries
- * which the user usually doesn't want to replace all text in,
- * such as search-as-you-type entries.
+ * It behaves like [method@Gtk.Widget.grab_focus], except that it doesn't
+ * select the contents of the entry. You only want to call this on some
+ * special entries which the user usually doesn't want to replace all text
+ * in, such as search-as-you-type entries.
*
* Returns: %TRUE if focus is now inside @self
*/
@@ -1920,7 +1958,7 @@ gtk_entry_start_editing (GtkCellEditable *cell_editable,
/**
* gtk_entry_reset_im_context:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
* Reset the input method context of the entry if needed.
*
@@ -2002,7 +2040,7 @@ gtk_entry_clear_icon (GtkEntry *entry,
*
* Creates a new entry.
*
- * Returns: a new #GtkEntry.
+ * Returns: a new `GtkEntry`.
*/
GtkWidget*
gtk_entry_new (void)
@@ -2012,11 +2050,11 @@ gtk_entry_new (void)
/**
* gtk_entry_new_with_buffer:
- * @buffer: The buffer to use for the new #GtkEntry.
+ * @buffer: The buffer to use for the new `GtkEntry`.
*
* Creates a new entry with the specified text buffer.
*
- * Returns: a new #GtkEntry
+ * Returns: a new `GtkEntry`
*/
GtkWidget*
gtk_entry_new_with_buffer (GtkEntryBuffer *buffer)
@@ -2036,12 +2074,12 @@ get_buffer (GtkEntry *entry)
/**
* gtk_entry_get_buffer:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
- * Get the #GtkEntryBuffer object which holds the text for
+ * Get the `GtkEntryBuffer` object which holds the text for
* this widget.
*
- * Returns: (transfer none): A #GtkEntryBuffer object.
+ * Returns: (transfer none): A `GtkEntryBuffer` object.
*/
GtkEntryBuffer*
gtk_entry_get_buffer (GtkEntry *entry)
@@ -2053,10 +2091,10 @@ gtk_entry_get_buffer (GtkEntry *entry)
/**
* gtk_entry_set_buffer:
- * @entry: a #GtkEntry
- * @buffer: a #GtkEntryBuffer
+ * @entry: a `GtkEntry`
+ * @buffer: a `GtkEntryBuffer`
*
- * Set the #GtkEntryBuffer object which holds the text for
+ * Set the `GtkEntryBuffer` object which holds the text for
* this widget.
*/
void
@@ -2072,27 +2110,28 @@ gtk_entry_set_buffer (GtkEntry *entry,
/**
* gtk_entry_set_visibility:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @visible: %TRUE if the contents of the entry are displayed
* as plaintext
*
* Sets whether the contents of the entry are visible or not.
+ *
* When visibility is set to %FALSE, characters are displayed
* as the invisible char, and will also appear that way when
* the text in the entry widget is copied elsewhere.
*
* By default, GTK picks the best invisible character available
* in the current font, but it can be changed with
- * gtk_entry_set_invisible_char().
+ * [method@Gtk.Entry.set_invisible_char].
*
- * Note that you probably want to set #GtkEntry:input-purpose
+ * Note that you probably want to set [property@Gtk.Entry:input-purpose]
* to %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN to
* inform input methods about the purpose of this entry,
* in addition to setting visibility to %FALSE.
*/
void
gtk_entry_set_visibility (GtkEntry *entry,
- gboolean visible)
+ gboolean visible)
{
GtkEntryPrivate *priv = gtk_entry_get_instance_private (entry);
@@ -2103,13 +2142,14 @@ gtk_entry_set_visibility (GtkEntry *entry,
/**
* gtk_entry_get_visibility:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
+ *
+ * Retrieves whether the text in @entry is visible.
*
- * Retrieves whether the text in @entry is visible. See
- * gtk_entry_set_visibility().
+ * See [method@Gtk.Entry.set_visibility].
*
* Returns: %TRUE if the text is currently visible
- **/
+ */
gboolean
gtk_entry_get_visibility (GtkEntry *entry)
{
@@ -2122,17 +2162,20 @@ gtk_entry_get_visibility (GtkEntry *entry)
/**
* gtk_entry_set_invisible_char:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @ch: a Unicode character
- *
- * Sets the character to use in place of the actual text when
- * gtk_entry_set_visibility() has been called to set text visibility
- * to %FALSE. i.e. this is the character used in “password mode” to
- * show the user how many characters have been typed. By default, GTK
- * picks the best invisible char available in the current font. If you
- * set the invisible char to 0, then the user will get no feedback
- * at all; there will be no text on the screen as they type.
- **/
+ *
+ * Sets the character to use in place of the actual text
+ * in “password mode”.
+ *
+ * See [method@Gtk.Entry.set_visibility] for how to enable
+ * “password mode”.
+ *
+ * By default, GTK picks the best invisible char available in
+ * the current font. If you set the invisible char to 0, then
+ * the user will get no feedback at all; there will be no text
+ * on the screen as they type.
+ */
void
gtk_entry_set_invisible_char (GtkEntry *entry,
gunichar ch)
@@ -2146,14 +2189,14 @@ gtk_entry_set_invisible_char (GtkEntry *entry,
/**
* gtk_entry_get_invisible_char:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
- * Retrieves the character displayed in place of the real characters
- * for entries with visibility set to false. See gtk_entry_set_invisible_char().
+ * Retrieves the character displayed in place of the actual text
+ * in “password mode”.
*
* Returns: the current invisible char, or 0, if the entry does not
- * show invisible text at all.
- **/
+ * show invisible text at all.
+ */
gunichar
gtk_entry_get_invisible_char (GtkEntry *entry)
{
@@ -2166,12 +2209,11 @@ gtk_entry_get_invisible_char (GtkEntry *entry)
/**
* gtk_entry_unset_invisible_char:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
- * Unsets the invisible char previously set with
- * gtk_entry_set_invisible_char(). So that the
- * default invisible char is used again.
- **/
+ * Unsets the invisible char, so that the default invisible char
+ * is used again. See [method@Gtk.Entry.set_invisible_char].
+ */
void
gtk_entry_unset_invisible_char (GtkEntry *entry)
{
@@ -2184,11 +2226,11 @@ gtk_entry_unset_invisible_char (GtkEntry *entry)
/**
* gtk_entry_set_overwrite_mode:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @overwrite: new value
*
- * Sets whether the text is overwritten when typing in the #GtkEntry.
- **/
+ * Sets whether the text is overwritten when typing in the `GtkEntry`.
+ */
void
gtk_entry_set_overwrite_mode (GtkEntry *entry,
gboolean overwrite)
@@ -2202,12 +2244,12 @@ gtk_entry_set_overwrite_mode (GtkEntry *entry,
/**
* gtk_entry_get_overwrite_mode:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
- * Gets the value set by gtk_entry_set_overwrite_mode().
+ * Gets whether the `GtkEntry` is in overwrite mode.
*
* Returns: whether the text is overwritten when typing.
- **/
+ */
gboolean
gtk_entry_get_overwrite_mode (GtkEntry *entry)
{
@@ -2221,18 +2263,19 @@ gtk_entry_get_overwrite_mode (GtkEntry *entry)
/**
* gtk_entry_set_max_length:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @max: the maximum length of the entry, or 0 for no maximum.
* (other than the maximum length of entries.) The value passed in will
* be clamped to the range 0-65536.
*
- * Sets the maximum allowed length of the contents of the widget. If
- * the current contents are longer than the given length, then they
- * will be truncated to fit.
+ * Sets the maximum allowed length of the contents of the widget.
+ *
+ * If the current contents are longer than the given length, then
+ * they will be truncated to fit.
*
- * This is equivalent to getting @entry's #GtkEntryBuffer and
- * calling gtk_entry_buffer_set_max_length() on it.
- **/
+ * This is equivalent to getting @entry's `GtkEntryBuffer` and
+ * calling [method@Gtk.EntryBuffer.set_max_length] on it.
+ */
void
gtk_entry_set_max_length (GtkEntry *entry,
int max)
@@ -2246,17 +2289,15 @@ gtk_entry_set_max_length (GtkEntry *entry,
/**
* gtk_entry_get_max_length:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
- * Retrieves the maximum allowed length of the text in
- * @entry. See gtk_entry_set_max_length().
+ * Retrieves the maximum allowed length of the text in @entry.
*
- * This is equivalent to getting @entry's #GtkEntryBuffer and
- * calling gtk_entry_buffer_get_max_length() on it.
+ * See [method@Gtk.Entry.set_max_length].
*
* Returns: the maximum allowed number of characters
- * in #GtkEntry, or 0 if there is no maximum.
- **/
+ * in `GtkEntry`, or 0 if there is no maximum.
+ */
int
gtk_entry_get_max_length (GtkEntry *entry)
{
@@ -2269,18 +2310,16 @@ gtk_entry_get_max_length (GtkEntry *entry)
/**
* gtk_entry_get_text_length:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
- * Retrieves the current length of the text in
- * @entry.
+ * Retrieves the current length of the text in @entry.
*
- * This is equivalent to getting @entry's #GtkEntryBuffer and
- * calling gtk_entry_buffer_get_length() on it.
-
+ * This is equivalent to getting @entry's `GtkEntryBuffer`
+ * and calling [method@Gtk.EntryBuffer.get_length] on it.
*
* Returns: the current number of characters
- * in #GtkEntry, or 0 if there are none.
- **/
+ * in `GtkEntry`, or 0 if there are none.
+ */
guint16
gtk_entry_get_text_length (GtkEntry *entry)
{
@@ -2293,14 +2332,15 @@ gtk_entry_get_text_length (GtkEntry *entry)
/**
* gtk_entry_set_activates_default:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @setting: %TRUE to activate window’s default widget on Enter keypress
*
- * If @setting is %TRUE, pressing Enter in the @entry will activate the default
- * widget for the window containing the entry. This usually means that
- * the dialog box containing the entry will be closed, since the default
- * widget is usually one of the dialog buttons.
- **/
+ * Sets whether pressing Enter in the @entry will activate the default
+ * widget for the window containing the entry.
+ *
+ * This usually means that the dialog containing the entry will be closed,
+ * since the default widget is usually one of the dialog buttons.
+ */
void
gtk_entry_set_activates_default (GtkEntry *entry,
gboolean setting)
@@ -2314,7 +2354,7 @@ gtk_entry_set_activates_default (GtkEntry *entry,
/**
* gtk_entry_get_activates_default:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
* Retrieves the value set by gtk_entry_set_activates_default().
*
@@ -2332,11 +2372,11 @@ gtk_entry_get_activates_default (GtkEntry *entry)
/**
* gtk_entry_set_has_frame:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @setting: new value
*
* Sets whether the entry has a beveled frame around it.
- **/
+ */
void
gtk_entry_set_has_frame (GtkEntry *entry,
gboolean setting)
@@ -2358,12 +2398,12 @@ gtk_entry_set_has_frame (GtkEntry *entry,
/**
* gtk_entry_get_has_frame:
- * @entry: a #GtkEntry
- *
+ * @entry: a `GtkEntry`
+ *
* Gets the value set by gtk_entry_set_has_frame().
- *
+ *
* Returns: whether the entry has a beveled frame
- **/
+ */
gboolean
gtk_entry_get_has_frame (GtkEntry *entry)
{
@@ -2374,14 +2414,15 @@ gtk_entry_get_has_frame (GtkEntry *entry)
/**
* gtk_entry_set_alignment:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @xalign: The horizontal alignment, from 0 (left) to 1 (right).
- * Reversed for RTL layouts
- *
- * Sets the alignment for the contents of the entry. This controls
- * the horizontal positioning of the contents when the displayed
- * text is shorter than the width of the entry.
- **/
+ * Reversed for RTL layouts
+ *
+ * Sets the alignment for the contents of the entry.
+ *
+ * This controls the horizontal positioning of the contents when
+ * the displayed text is shorter than the width of the entry.
+ */
void
gtk_entry_set_alignment (GtkEntry *entry,
float xalign)
@@ -2395,12 +2436,12 @@ gtk_entry_set_alignment (GtkEntry *entry,
/**
* gtk_entry_get_alignment:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
* Gets the value set by gtk_entry_set_alignment().
*
* Returns: the alignment
- **/
+ */
float
gtk_entry_get_alignment (GtkEntry *entry)
{
@@ -2413,11 +2454,11 @@ gtk_entry_get_alignment (GtkEntry *entry)
/**
* gtk_entry_set_icon_from_paintable:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @icon_pos: Icon position
- * @paintable: (allow-none): A #GdkPaintable, or %NULL
+ * @paintable: (allow-none): A `GdkPaintable`, or %NULL
*
- * Sets the icon shown in the specified position using a #GdkPaintable
+ * Sets the icon shown in the specified position using a `GdkPaintable`.
*
* If @paintable is %NULL, no icon will be shown in the specified position.
*/
@@ -2468,17 +2509,18 @@ gtk_entry_set_icon_from_paintable (GtkEntry *entry,
/**
* gtk_entry_set_icon_from_icon_name:
- * @entry: A #GtkEntry
+ * @entry: A `GtkEntry`
* @icon_pos: The position at which to set the icon
* @icon_name: (allow-none): An icon name, or %NULL
*
* Sets the icon shown in the entry at the specified position
* from the current icon theme.
*
- * If the icon name isn’t known, a “broken image” icon will be displayed
- * instead.
+ * If the icon name isn’t known, a “broken image” icon will be
+ * displayed instead.
*
- * If @icon_name is %NULL, no icon will be shown in the specified position.
+ * If @icon_name is %NULL, no icon will be shown in the
+ * specified position.
*/
void
gtk_entry_set_icon_from_icon_name (GtkEntry *entry,
@@ -2523,16 +2565,18 @@ gtk_entry_set_icon_from_icon_name (GtkEntry *entry,
/**
* gtk_entry_set_icon_from_gicon:
- * @entry: A #GtkEntry
+ * @entry: A `GtkEntry`
* @icon_pos: The position at which to set the icon
* @icon: (allow-none): The icon to set, or %NULL
*
* Sets the icon shown in the entry at the specified position
* from the current icon theme.
- * If the icon isn’t known, a “broken image” icon will be displayed
- * instead.
*
- * If @icon is %NULL, no icon will be shown in the specified position.
+ * If the icon isn’t known, a “broken image” icon will be
+ * displayed instead.
+ *
+ * If @icon is %NULL, no icon will be shown in the
+ * specified position.
*/
void
gtk_entry_set_icon_from_gicon (GtkEntry *entry,
@@ -2576,7 +2620,7 @@ gtk_entry_set_icon_from_gicon (GtkEntry *entry,
/**
* gtk_entry_set_icon_activatable:
- * @entry: A #GtkEntry
+ * @entry: A `GtkEntry`
* @icon_pos: Icon position
* @activatable: %TRUE if the icon should be activatable
*
@@ -2611,7 +2655,7 @@ gtk_entry_set_icon_activatable (GtkEntry *entry,
/**
* gtk_entry_get_icon_activatable:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @icon_pos: Icon position
*
* Returns whether the icon is activatable.
@@ -2635,15 +2679,16 @@ gtk_entry_get_icon_activatable (GtkEntry *entry,
/**
* gtk_entry_get_icon_paintable:
- * @entry: A #GtkEntry
+ * @entry: A `GtkEntry`
* @icon_pos: Icon position
*
- * Retrieves the #GdkPaintable used for the icon.
+ * Retrieves the `GdkPaintable` used for the icon.
*
- * If no #GdkPaintable was used for the icon, %NULL is returned.
+ * If no `GdkPaintable` was used for the icon, %NULL is returned.
*
- * Returns: (transfer none) (nullable): A #GdkPaintable, or %NULL if no icon is
- * set for this position or the icon set is not a #GdkPaintable.
+ * Returns: (transfer none) (nullable): A `GdkPaintable`, or %NULL
+ * if no icon is set for this position or the icon set is not
+ * a `GdkPaintable`.
*/
GdkPaintable *
gtk_entry_get_icon_paintable (GtkEntry *entry,
@@ -2665,15 +2710,16 @@ gtk_entry_get_icon_paintable (GtkEntry *entry,
/**
* gtk_entry_get_icon_gicon:
- * @entry: A #GtkEntry
+ * @entry: A `GtkEntry`
* @icon_pos: Icon position
*
- * Retrieves the #GIcon used for the icon, or %NULL if there is
- * no icon or if the icon was set by some other method (e.g., by
- * paintable or icon name).
+ * Retrieves the `GIcon` used for the icon.
+ *
+ * %NULL will be returned if there is no icon or if the icon was
+ * set by some other method (e.g., by `GdkPaintable` or icon name).
*
- * Returns: (transfer none) (nullable): A #GIcon, or %NULL if no icon is set
- * or if the icon is not a #GIcon
+ * Returns: (transfer none) (nullable): A `GIcon`, or %NULL if no
+ * icon is set or if the icon is not a `GIcon`
*/
GIcon *
gtk_entry_get_icon_gicon (GtkEntry *entry,
@@ -2695,15 +2741,16 @@ gtk_entry_get_icon_gicon (GtkEntry *entry,
/**
* gtk_entry_get_icon_name:
- * @entry: A #GtkEntry
+ * @entry: A `GtkEntry`
* @icon_pos: Icon position
*
- * Retrieves the icon name used for the icon, or %NULL if there is
- * no icon or if the icon was set by some other method (e.g., by
- * paintable or gicon).
+ * Retrieves the icon name used for the icon.
*
- * Returns: (nullable): An icon name, or %NULL if no icon is set or if the icon
- * wasn’t set from an icon name
+ * %NULL is returned if there is no icon or if the icon was set
+ * by some other method (e.g., by `GdkPaintable` or gicon).
+ *
+ * Returns: (nullable): An icon name, or %NULL if no icon is set
+ * or if the icon wasn’t set from an icon name
*/
const char *
gtk_entry_get_icon_name (GtkEntry *entry,
@@ -2725,10 +2772,10 @@ gtk_entry_get_icon_name (GtkEntry *entry,
/**
* gtk_entry_set_icon_sensitive:
- * @entry: A #GtkEntry
+ * @entry: A `GtkEntry`
* @icon_pos: Icon position
* @sensitive: Specifies whether the icon should appear
- * sensitive or insensitive
+ * sensitive or insensitive
*
* Sets the sensitivity for the specified icon.
*/
@@ -2759,7 +2806,7 @@ gtk_entry_set_icon_sensitive (GtkEntry *entry,
/**
* gtk_entry_get_icon_sensitive:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @icon_pos: Icon position
*
* Returns whether the icon appears sensitive or insensitive.
@@ -2786,15 +2833,17 @@ gtk_entry_get_icon_sensitive (GtkEntry *entry,
/**
* gtk_entry_get_icon_storage_type:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @icon_pos: Icon position
*
* Gets the type of representation being used by the icon
- * to store image data. If the icon has no image data,
- * the return value will be %GTK_IMAGE_EMPTY.
+ * to store image data.
+ *
+ * If the icon has no image data, the return value will
+ * be %GTK_IMAGE_EMPTY.
*
* Returns: image representation being used
- **/
+ */
GtkImageType
gtk_entry_get_icon_storage_type (GtkEntry *entry,
GtkEntryIconPosition icon_pos)
@@ -2815,15 +2864,16 @@ gtk_entry_get_icon_storage_type (GtkEntry *entry,
/**
* gtk_entry_get_icon_at_pos:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @x: the x coordinate of the position to find, relative to @entry
* @y: the y coordinate of the position to find, relative to @entry
*
- * Finds the icon at the given position and return its index. The
- * position’s coordinates are relative to the @entry’s top left corner.
- * If @x, @y doesn’t lie inside an icon, -1 is returned.
- * This function is intended for use in a #GtkWidget::query-tooltip
- * signal handler.
+ * Finds the icon at the given position and return its index.
+ *
+ * The position’s coordinates are relative to the @entry’s
+ * top left corner. If @x, @y doesn’t lie inside an icon,
+ * -1 is returned. This function is intended for use in a
+ * [signal@GtkWidget::query-tooltip] signal handler.
*
* Returns: the index of the icon at the given position, or -1
*/
@@ -2857,12 +2907,14 @@ gtk_entry_get_icon_at_pos (GtkEntry *entry,
/**
* gtk_entry_set_icon_drag_source:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @icon_pos: icon position
* @provider: a #GdkContentProvider
* @actions: a bitmask of the allowed drag actions
*
- * Sets up the icon at the given position so that GTK will start a drag
+ * Sets up the icon at the given position as drag source.
+ *
+ * This makes it so that GTK will start a drag
* operation when the user clicks and drags the icon.
*/
void
@@ -2886,13 +2938,13 @@ gtk_entry_set_icon_drag_source (GtkEntry *entry,
/**
* gtk_entry_get_current_icon_drag_source:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
- * Returns the index of the icon which is the source of the current
- * DND operation, or -1.
+ * Returns the index of the icon which is the source of the
+ * current DND operation, or -1.
*
- * Returns: index of the icon which is the source of the current
- * DND operation, or -1.
+ * Returns: index of the icon which is the source of the
+ * current DND operation, or -1.
*/
int
gtk_entry_get_current_icon_drag_source (GtkEntry *entry)
@@ -2917,17 +2969,19 @@ gtk_entry_get_current_icon_drag_source (GtkEntry *entry)
/**
* gtk_entry_get_icon_area:
- * @entry: A #GtkEntry
+ * @entry: A `GtkEntry`
* @icon_pos: Icon position
* @icon_area: (out): Return location for the icon’s area
*
* Gets the area where entry’s icon at @icon_pos is drawn.
+ *
* This function is useful when drawing something to the
* entry in a draw callback.
*
- * If the entry is not realized or has no icon at the given position,
- * @icon_area is filled with zeros. Otherwise, @icon_area will be filled
- * with the icon's allocation, relative to @entry's allocation.
+ * If the entry is not realized or has no icon at the given
+ * position, @icon_area is filled with zeros. Otherwise,
+ * @icon_area will be filled with the icon's allocation,
+ * relative to @entry's allocation.
*/
void
gtk_entry_get_icon_area (GtkEntry *entry,
@@ -2990,14 +3044,14 @@ ensure_has_tooltip (GtkEntry *entry)
/**
* gtk_entry_get_icon_tooltip_text:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @icon_pos: the icon position
*
- * Gets the contents of the tooltip on the icon at the specified
+ * Gets the contents of the tooltip on the icon at the specified
* position in @entry.
- *
+ *
* Returns: (nullable): the tooltip text, or %NULL. Free the returned
- * string with g_free() when done.
+ * string with g_free() when done.
*/
char *
gtk_entry_get_icon_tooltip_text (GtkEntry *entry,
@@ -3024,23 +3078,28 @@ gtk_entry_get_icon_tooltip_text (GtkEntry *entry,
/**
* gtk_entry_set_icon_tooltip_text:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @icon_pos: the icon position
- * @tooltip: (allow-none): the contents of the tooltip for the icon, or %NULL
+ * @tooltip: (allow-none): the contents of the tooltip for the
+ * icon, or %NULL
*
* Sets @tooltip as the contents of the tooltip for the icon
* at the specified position.
*
* Use %NULL for @tooltip to remove an existing tooltip.
*
- * See also gtk_widget_set_tooltip_text() and
- * gtk_entry_set_icon_tooltip_markup().
- *
- * If you unset the widget tooltip via gtk_widget_set_tooltip_text() or
- * gtk_widget_set_tooltip_markup(), this sets GtkWidget:has-tooltip to %FALSE,
- * which suppresses icon tooltips too. You can resolve this by then calling
- * gtk_widget_set_has_tooltip() to set GtkWidget:has-tooltip back to %TRUE, or
- * setting at least one non-empty tooltip on any icon achieves the same result.
+ * See also [method@Gtk.Widget.set_tooltip_text] and
+ * [method@Gtk.Entry.set_icon_tooltip_markup].
+ *
+ * If you unset the widget tooltip via
+ * [method@Gtk.Widget.set_tooltip_text] or
+ * [method@Gtk.Widget.set_tooltip_markup], this sets
+ * [property@Gtk.Widget:has-tooltip] to %FALSE, which suppresses
+ * icon tooltips too. You can resolve this by then calling
+ * [method@Gtk.Widget.set_has_tooltip] to set
+ * [property@Gtk.Widget:has-tooltip] back to %TRUE, or
+ * setting at least one non-empty tooltip on any icon
+ * achieves the same result.
*/
void
gtk_entry_set_icon_tooltip_text (GtkEntry *entry,
@@ -3076,14 +3135,14 @@ gtk_entry_set_icon_tooltip_text (GtkEntry *entry,
/**
* gtk_entry_get_icon_tooltip_markup:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @icon_pos: the icon position
*
- * Gets the contents of the tooltip on the icon at the specified
+ * Gets the contents of the tooltip on the icon at the specified
* position in @entry.
- *
- * Returns: (nullable): the tooltip text, or %NULL. Free the returned
- * string with g_free() when done.
+ *
+ * Returns: (nullable): the tooltip text, or %NULL. Free the
+ * returned string with g_free() when done.
*/
char *
gtk_entry_get_icon_tooltip_markup (GtkEntry *entry,
@@ -3105,18 +3164,20 @@ gtk_entry_get_icon_tooltip_markup (GtkEntry *entry,
/**
* gtk_entry_set_icon_tooltip_markup:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @icon_pos: the icon position
- * @tooltip: (allow-none): the contents of the tooltip for the icon, or %NULL
+ * @tooltip: (allow-none): the contents of the tooltip for the
+ * icon, or %NULL
*
* Sets @tooltip as the contents of the tooltip for the icon at
- * the specified position. @tooltip is assumed to be marked up with
- * the [Pango text markup language][PangoMarkupFormat].
+ * the specified position.
+ *
+ * @tooltip is assumed to be marked up with Pango Markup.
*
* Use %NULL for @tooltip to remove an existing tooltip.
*
- * See also gtk_widget_set_tooltip_markup() and
- * gtk_entry_set_icon_tooltip_text().
+ * See also [method@Gtk.Widget.set_tooltip_markup] and
+ * [method@Gtk.Entry.set_icon_tooltip_text].
*/
void
gtk_entry_set_icon_tooltip_markup (GtkEntry *entry,
@@ -3188,13 +3249,15 @@ gtk_entry_query_tooltip (GtkWidget *widget,
/**
* gtk_entry_set_completion:
- * @entry: A #GtkEntry
- * @completion: (allow-none): The #GtkEntryCompletion or %NULL
+ * @entry: A `GtkEntry`
+ * @completion: (allow-none): The `GtkEntryCompletion` or %NULL
+ *
+ * Sets @completion to be the auxiliary completion object
+ * to use with @entry.
*
- * Sets @completion to be the auxiliary completion object to use with @entry.
- * All further configuration of the completion mechanism is done on
- * @completion using the #GtkEntryCompletion API. Completion is disabled if
- * @completion is set to %NULL.
+ * All further configuration of the completion mechanism is
+ * done on @completion using the `GtkEntryCompletion` API.
+ * Completion is disabled if @completion is set to %NULL.
*/
void
gtk_entry_set_completion (GtkEntry *entry,
@@ -3234,12 +3297,13 @@ gtk_entry_set_completion (GtkEntry *entry,
/**
* gtk_entry_get_completion:
- * @entry: A #GtkEntry
+ * @entry: A `GtkEntry`
*
- * Returns the auxiliary completion object currently in use by @entry.
+ * Returns the auxiliary completion object currently
+ * in use by @entry.
*
- * Returns: (nullable) (transfer none): The auxiliary completion object currently
- * in use by @entry.
+ * Returns: (nullable) (transfer none): The auxiliary
+ * completion object currently in use by @entry
*/
GtkEntryCompletion *
gtk_entry_get_completion (GtkEntry *entry)
@@ -3273,12 +3337,13 @@ gtk_entry_ensure_progress_widget (GtkEntry *entry)
/**
* gtk_entry_set_progress_fraction:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @fraction: fraction of the task that’s been completed
*
* Causes the entry’s progress indicator to “fill in” the given
- * fraction of the bar. The fraction should be between 0.0 and 1.0,
- * inclusive.
+ * fraction of the bar.
+ *
+ * The fraction should be between 0.0 and 1.0, inclusive.
*/
void
gtk_entry_set_progress_fraction (GtkEntry *entry,
@@ -3304,10 +3369,11 @@ gtk_entry_set_progress_fraction (GtkEntry *entry,
/**
* gtk_entry_get_progress_fraction:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
* Returns the current fraction of the task that’s been completed.
- * See gtk_entry_set_progress_fraction().
+ *
+ * See [method@Gtk.Entry.set_progress_fraction].
*
* Returns: a fraction from 0.0 to 1.0
*/
@@ -3326,11 +3392,14 @@ gtk_entry_get_progress_fraction (GtkEntry *entry)
/**
* gtk_entry_set_progress_pulse_step:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @fraction: fraction between 0.0 and 1.0
*
* Sets the fraction of total entry width to move the progress
- * bouncing block for each call to gtk_entry_progress_pulse().
+ * bouncing block for each pulse.
+ *
+ * Use [method@Gtk.Entry.progress_pulse] to pulse
+ * the progress.
*/
void
gtk_entry_set_progress_pulse_step (GtkEntry *entry,
@@ -3353,9 +3422,10 @@ gtk_entry_set_progress_pulse_step (GtkEntry *entry,
/**
* gtk_entry_get_progress_pulse_step:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
- * Retrieves the pulse step set with gtk_entry_set_progress_pulse_step().
+ * Retrieves the pulse step set with
+ * gtk_entry_set_progress_pulse_step().
*
* Returns: a fraction from 0.0 to 1.0
*/
@@ -3374,14 +3444,16 @@ gtk_entry_get_progress_pulse_step (GtkEntry *entry)
/**
* gtk_entry_progress_pulse:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
- * Indicates that some progress is made, but you don’t know how much.
- * Causes the entry’s progress indicator to enter “activity mode,”
- * where a block bounces back and forth. Each call to
- * gtk_entry_progress_pulse() causes the block to move by a little bit
- * (the amount of movement per pulse is determined by
- * gtk_entry_set_progress_pulse_step()).
+ * Indicates that some progress is made, but you don’t
+ * know how much.
+ *
+ * Causes the entry’s progress indicator to enter “activity
+ * mode”, where a block bounces back and forth. Each call to
+ * gtk_entry_progress_pulse() causes the block to move by a
+ * little bit (the amount of movement per pulse is determined
+ * by [method@Gtk.Entry.set_progress_pulse_step]).
*/
void
gtk_entry_progress_pulse (GtkEntry *entry)
@@ -3396,13 +3468,15 @@ gtk_entry_progress_pulse (GtkEntry *entry)
/**
* gtk_entry_set_placeholder_text:
- * @entry: a #GtkEntry
- * @text: (nullable): a string to be displayed when @entry is empty and unfocused, or %NULL
+ * @entry: a `GtkEntry`
+ * @text: (nullable): a string to be displayed when @entry is
+ * empty and unfocused, or %NULL
*
* Sets text to be displayed in @entry when it is empty.
- * This can be used to give a visual hint of the expected contents of
- * the #GtkEntry.
- **/
+ *
+ * This can be used to give a visual hint of the expected
+ * contents of the `GtkEntry`.
+ */
void
gtk_entry_set_placeholder_text (GtkEntry *entry,
const char *text)
@@ -3420,15 +3494,17 @@ gtk_entry_set_placeholder_text (GtkEntry *entry,
/**
* gtk_entry_get_placeholder_text:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
- * Retrieves the text that will be displayed when @entry is empty and unfocused
+ * Retrieves the text that will be displayed when @entry
+ * is empty and unfocused
*
- * Returns: (nullable) (transfer none):a pointer to the placeholder text as a string.
- * This string points to internally allocated storage in the widget and must
- * not be freed, modified or stored. If no placeholder text has been set,
- * %NULL will be returned.
- **/
+ * Returns: (nullable) (transfer none):a pointer to the
+ * placeholder text as a string. This string points to
+ * internally allocated storage in the widget and must
+ * not be freed, modified or stored. If no placeholder
+ * text has been set, %NULL will be returned.
+ */
const char *
gtk_entry_get_placeholder_text (GtkEntry *entry)
{
@@ -3441,12 +3517,11 @@ gtk_entry_get_placeholder_text (GtkEntry *entry)
/**
* gtk_entry_set_input_purpose:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @purpose: the purpose
*
- * Sets the #GtkEntry:input-purpose property which
- * can be used by on-screen keyboards and other input
- * methods to adjust their behaviour.
+ * Sets the input purpose which can be used by input methods
+ * to adjust their behavior.
*/
void
gtk_entry_set_input_purpose (GtkEntry *entry,
@@ -3462,9 +3537,9 @@ gtk_entry_set_input_purpose (GtkEntry *entry,
/**
* gtk_entry_get_input_purpose:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
- * Gets the value of the #GtkEntry:input-purpose property.
+ * Gets the input purpose of the `GtkEntry`.
*/
GtkInputPurpose
gtk_entry_get_input_purpose (GtkEntry *entry)
@@ -3478,11 +3553,11 @@ gtk_entry_get_input_purpose (GtkEntry *entry)
/**
* gtk_entry_set_input_hints:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @hints: the hints
*
- * Sets the #GtkEntry:input-hints property, which
- * allows input methods to fine-tune their behaviour.
+ * Set additional hints which allow input methods to
+ * fine-tune their behavior.
*/
void
gtk_entry_set_input_hints (GtkEntry *entry,
@@ -3498,9 +3573,9 @@ gtk_entry_set_input_hints (GtkEntry *entry,
/**
* gtk_entry_get_input_hints:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
- * Gets the value of the #GtkEntry:input-hints property.
+ * Gets the input hints of this `GtkEntry`.
*/
GtkInputHints
gtk_entry_get_input_hints (GtkEntry *entry)
@@ -3514,11 +3589,16 @@ gtk_entry_get_input_hints (GtkEntry *entry)
/**
* gtk_entry_set_attributes:
- * @entry: a #GtkEntry
- * @attrs: a #PangoAttrList
+ * @entry: a `GtkEntry`
+ * @attrs: a `PangoAttrList`
+ *
+ * Sets a `PangoAttrList`.
*
- * Sets a #PangoAttrList; the attributes in the list are applied to the
- * entry text.
+ * The attributes in the list are applied to the entry text.
+ *
+ * Since the attributes will be applies to text that changes
+ * as the user types, it makes most sense to use attributes
+ * with unlimited extent.
*/
void
gtk_entry_set_attributes (GtkEntry *entry,
@@ -3533,13 +3613,14 @@ gtk_entry_set_attributes (GtkEntry *entry,
/**
* gtk_entry_get_attributes:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
+ *
+ * Gets the attribute list of the `GtkEntry`.
*
- * Gets the attribute list that was set on the entry using
- * gtk_entry_set_attributes(), if any.
+ * See [method@Gtk.Entry.set_attributes].
*
- * Returns: (transfer none) (nullable): the attribute list, or %NULL
- * if none was set.
+ * Returns: (transfer none) (nullable): the attribute list,
+ * or %NULL if none was set.
*/
PangoAttrList *
gtk_entry_get_attributes (GtkEntry *entry)
@@ -3553,11 +3634,12 @@ gtk_entry_get_attributes (GtkEntry *entry)
/**
* gtk_entry_set_tabs:
- * @entry: a #GtkEntry
- * @tabs: (nullable): a #PangoTabArray
+ * @entry: a `GtkEntry`
+ * @tabs: (nullable): a `PangoTabArray`
+ *
+ * Sets a `PangoTabArray`.
*
- * Sets a #PangoTabArray; the tabstops in the array are applied to the entry
- * text.
+ * The tabstops in the array are applied to the entry text.
*/
void
@@ -3573,12 +3655,14 @@ gtk_entry_set_tabs (GtkEntry *entry,
/**
* gtk_entry_get_tabs:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
- * Gets the tabstops that were set on the entry using gtk_entry_set_tabs(), if
- * any.
+ * Gets the tabstops of the `GtkEntry.
*
- * Returns: (nullable) (transfer none): the tabstops, or %NULL if none was set.
+ * See [method@Gtk.Entry.set_tabs].
+ *
+ * Returns: (nullable) (transfer none): the tabstops,
+ * or %NULL if none was set.
*/
PangoTabArray *
@@ -3672,8 +3756,8 @@ gtk_entry_get_text_widget (GtkEntry *entry)
/**
* gtk_entry_set_extra_menu:
- * @entry: a #GtkEntry
- * @model: (allow-none): a #GMenuModel
+ * @entry: a `GtkEntry`
+ * @model: (allow-none): a `GMenuModel`
*
* Sets a menu model to add when constructing
* the context menu for @entry.
@@ -3693,7 +3777,7 @@ gtk_entry_set_extra_menu (GtkEntry *entry,
/**
* gtk_entry_get_extra_menu:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
*
* Gets the menu model set with gtk_entry_set_extra_menu().
*
@@ -3711,11 +3795,15 @@ gtk_entry_get_extra_menu (GtkEntry *entry)
/*< private >
* gtk_entry_activate_icon:
- * @entry: a #GtkEntry
+ * @entry: a `GtkEntry`
* @pos: the icon position
*
- * Emits the #GtkEntry::icon-press and #GtkEntry::icon-release signals on
- * the @entry icon at the given @pos, if the icon is set and activatable.
+ * Activates an icon.
+ *
+ * This causes the [signal@Gtk.Entry::icon-press] and
+ * [signal@Gtk.Entry::icon-release] signals to be emitted
+ * on the @entry icon at the given @pos, if the icon is
+ * set and activatable.
*
* Returns: %TRUE if the signal was emitted
*/
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
