[libadwaita/wip/exalm/docs: 2/4] Unify property and setter docs
- From: Alexander Mikhaylenko <alexm src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [libadwaita/wip/exalm/docs: 2/4] Unify property and setter docs
- Date: Wed, 10 Aug 2022 16:54:14 +0000 (UTC)
commit 12ef1984c40beb28aeb0d4d05e04eb49f9e9409a
Author: Alexander Mikhaylenko <alexm gnome org>
Date: Wed Aug 10 19:37:54 2022 +0400
Unify property and setter docs
Make sure bindings that don't expose properties in docs still have
descriptions.
src/adw-action-row.c | 14 +++++---
src/adw-animation-target.c | 4 +++
src/adw-animation.c | 7 ++++
src/adw-application.c | 3 ++
src/adw-avatar.c | 11 +++++-
src/adw-button-content.c | 6 ++++
src/adw-carousel.c | 30 +++++++++++++---
src/adw-clamp-layout.c | 17 ++++++++-
src/adw-clamp-scrollable.c | 15 ++++++++
src/adw-clamp.c | 15 ++++++++
src/adw-combo-row.c | 38 ++++++++++++++------
src/adw-entry-row.c | 17 +++++----
src/adw-expander-row.c | 3 ++
src/adw-flap.c | 56 ++++++++++++++++++++++++++---
src/adw-header-bar.c | 38 ++++++++++++++++++++
src/adw-leaflet.c | 84 +++++++++++++++++++++++++++++++++++++------
src/adw-preferences-group.c | 10 +++++-
src/adw-preferences-row.c | 9 +++++
src/adw-preferences-window.c | 13 +++++++
src/adw-split-button.c | 43 ++++++++++++++++++----
src/adw-spring-animation.c | 31 ++++++++++++++--
src/adw-squeezer.c | 72 ++++++++++++++++++++++++++++++-------
src/adw-status-page.c | 14 ++++++--
src/adw-style-manager.c | 34 ++++++++++++++++++
src/adw-swipe-tracker.c | 9 +++++
src/adw-tab-bar.c | 15 ++++++++
src/adw-tab-view.c | 68 ++++++++++++++++++++++++++++++++++-
src/adw-timed-animation.c | 12 +++++++
src/adw-toast.c | 27 +++++++++++---
src/adw-view-stack.c | 42 ++++++++++++++++++----
src/adw-view-switcher-title.c | 21 +++++++++--
src/adw-window-title.c | 7 +++-
32 files changed, 702 insertions(+), 83 deletions(-)
---
diff --git a/src/adw-action-row.c b/src/adw-action-row.c
index 68a0ef40..3a1d9935 100644
--- a/src/adw-action-row.c
+++ b/src/adw-action-row.c
@@ -264,6 +264,9 @@ adw_action_row_class_init (AdwActionRowClass *klass)
*
* The subtitle for this row.
*
+ * The subtitle is interpreted as Pango markup unless
+ * [property@PreferencesRow:use-markup] is set to `FALSE`.
+ *
* Since: 1.0
*/
props[PROP_SUBTITLE] =
@@ -529,6 +532,13 @@ activatable_widget_weak_notify (gpointer data,
*
* Sets the widget to activate when @self is activated.
*
+ * The row can be activated either by clicking on it, calling
+ * [method@ActionRow.activate], or via mnemonics in the title or the subtitle.
+ * See the [property@PreferencesRow:use-underline] property to enable mnemonics.
+ *
+ * The target widget will be activated by emitting the
+ * [signal@Gtk.Widget::mnemonic-activate] signal on it.
+ *
* Since: 1.0
*/
void
@@ -586,8 +596,6 @@ adw_action_row_set_activatable_widget (AdwActionRow *self,
* Gets the number of lines at the end of which the title label will be
* ellipsized.
*
- * If the value is 0, the number of lines won't be limited.
- *
* Returns: the number of lines at the end of which the title label will be
* ellipsized
*
@@ -646,8 +654,6 @@ adw_action_row_set_title_lines (AdwActionRow *self,
* Gets the number of lines at the end of which the subtitle label will be
* ellipsized.
*
- * If the value is 0, the number of lines won't be limited.
- *
* Returns: the number of lines at the end of which the subtitle label will be
* ellipsized
*
diff --git a/src/adw-animation-target.c b/src/adw-animation-target.c
index 8580365c..9750b6af 100644
--- a/src/adw-animation-target.c
+++ b/src/adw-animation-target.c
@@ -415,6 +415,10 @@ adw_property_animation_target_new_for_pspec (GObject *object,
*
* Gets the object animated by @self.
*
+ * The `AdwPropertyAnimationTarget` instance does not hold a strong reference on
+ * the object; make sure the object is kept alive throughout the target's
+ * lifetime.
+ *
* Returns: (transfer none): the animated object
*
* Since: 1.2
diff --git a/src/adw-animation.c b/src/adw-animation.c
index 70c38bef..bb839805 100644
--- a/src/adw-animation.c
+++ b/src/adw-animation.c
@@ -435,6 +435,13 @@ adw_animation_init (AdwAnimation *self)
*
* Gets the widget @self was created for.
*
+ * It provides the frame clock for the animation. It's not strictly necessary
+ * for this widget to be same as the one being animated.
+ *
+ * The widget must be mapped in order for the animation to work. If it's not
+ * mapped, or if it gets unmapped during an ongoing animation, the animation
+ * will be automatically skipped.
+ *
* Returns: (transfer none): the animation widget
*
* Since: 1.0
diff --git a/src/adw-application.c b/src/adw-application.c
index 2c00ab0c..9263f619 100644
--- a/src/adw-application.c
+++ b/src/adw-application.c
@@ -280,6 +280,9 @@ adw_application_new (const char *application_id,
*
* Gets the style manager for @self.
*
+ * This is a convenience property allowing to access `AdwStyleManager` through
+ * property bindings or expressions.
+ *
* Returns: (transfer none): the style manager
*
* Since: 1.0
diff --git a/src/adw-avatar.c b/src/adw-avatar.c
index f5bffef2..79bc3541 100644
--- a/src/adw-avatar.c
+++ b/src/adw-avatar.c
@@ -366,7 +366,9 @@ adw_avatar_class_init (AdwAvatarClass *klass)
/**
* AdwAvatar:custom-image: (attributes org.gtk.Property.get=adw_avatar_get_custom_image
org.gtk.Property.set=adw_avatar_set_custom_image)
*
- * A custom image to use instead of initials or icon.
+ * A custom image paintable.
+ *
+ * Custom image is displayed instead of initials or icon.
*
* Since: 1.0
*/
@@ -518,6 +520,9 @@ adw_avatar_get_text (AdwAvatar *self)
*
* Sets the text used to generate the fallback initials and color.
*
+ * It's only used to generate the color if [property@Avatar:show-initials] is
+ * `FALSE`.
+ *
* Since: 1.0
*/
void
@@ -566,6 +571,8 @@ adw_avatar_get_show_initials (AdwAvatar *self)
*
* Sets whether to use initials instead of an icon on the fallback avatar.
*
+ * See [property@Avatar:icon-name] for how to change the fallback icon.
+ *
* Since: 1.0
*/
void
@@ -611,6 +618,8 @@ adw_avatar_get_custom_image (AdwAvatar *self)
*
* Sets the custom image paintable.
*
+ * Custom image is displayed instead of initials or icon.
+ *
* Since: 1.0
*/
void
diff --git a/src/adw-button-content.c b/src/adw-button-content.c
index 54c6adc1..a0dfdb12 100644
--- a/src/adw-button-content.c
+++ b/src/adw-button-content.c
@@ -322,6 +322,8 @@ adw_button_content_get_icon_name (AdwButtonContent *self)
*
* Sets the name of the displayed icon.
*
+ * If empty, the icon is not shown.
+ *
* Since: 1.0
*/
void
@@ -415,6 +417,10 @@ adw_button_content_get_use_underline (AdwButtonContent *self)
*
* Sets whether an underline in the text indicates a mnemonic.
*
+ * The mnemonic can be used to activate the parent button.
+ *
+ * See [property@ButtonContent:label].
+ *
* Since: 1.0
*/
void
diff --git a/src/adw-carousel.c b/src/adw-carousel.c
index 494da30d..034b82b8 100644
--- a/src/adw-carousel.c
+++ b/src/adw-carousel.c
@@ -911,7 +911,7 @@ adw_carousel_class_init (AdwCarouselClass *klass)
*
* Whether the carousel can be navigated.
*
- * This can be used to temporarily disable a `AdwCarousel` to only allow
+ * This can be used to temporarily disable the carousel to only allow
* navigating it in a certain state.
*
* Since: 1.0
@@ -1000,6 +1000,8 @@ adw_carousel_class_init (AdwCarouselClass *klass)
*
* Page reveal duration, in milliseconds.
*
+ * Reveal duration is used when animating adding or removing pages.
+ *
* Since: 1.0
*/
props[PROP_REVEAL_DURATION] =
@@ -1470,9 +1472,9 @@ adw_carousel_get_n_pages (AdwCarousel *self)
* adw_carousel_get_position: (attributes org.gtk.Method.get_property=position)
* @self: a carousel
*
- * Gets current scroll position in @self.
+ * Gets current scroll position in @self, unitless.
*
- * It's unitless, 1 matches 1 page.
+ * 1 matches 1 page. Use [method@Carousel.scroll_to] for changing it.
*
* Returns: the scroll position
*
@@ -1511,6 +1513,9 @@ adw_carousel_get_interactive (AdwCarousel *self)
*
* Sets whether @self can be navigated.
*
+ * This can be used to temporarily disable the carousel to only allow navigating
+ * it in a certain state.
+ *
* Since: 1.0
*/
void
@@ -1596,6 +1601,12 @@ adw_carousel_get_scroll_params (AdwCarousel *self)
*
* Sets the scroll animation spring parameters for @self.
*
+ * The default value is equivalent to:
+ *
+ * ```c
+ * adw_spring_params_new (1, 0.5, 500)
+ * ```
+ *
* Since: 1.0
*/
void
@@ -1638,6 +1649,8 @@ adw_carousel_get_allow_mouse_drag (AdwCarousel *self)
*
* Sets whether @self can be dragged with mouse pointer.
*
+ * If @allow_mouse_drag is `FALSE`, dragging is only available on touch.
+ *
* Since: 1.0
*/
void
@@ -1681,6 +1694,8 @@ adw_carousel_get_allow_scroll_wheel (AdwCarousel *self)
*
* Sets whether @self will respond to scroll wheel events.
*
+ * If @allow_scroll_wheel is `FALSE`, wheel events will be ignored.
+ *
* Since: 1.0
*/
void
@@ -1724,6 +1739,9 @@ adw_carousel_get_allow_long_swipes (AdwCarousel *self)
*
* Sets whether to allow swiping for more than one page at a time.
*
+ * If @allow_long_swipes is `FALSE`, each swipe can only move to the adjacent
+ * pages.
+ *
* Since: 1.0
*/
void
@@ -1746,7 +1764,7 @@ adw_carousel_set_allow_long_swipes (AdwCarousel *self,
* adw_carousel_get_reveal_duration: (attributes org.gtk.Method.get_property=reveal-duration)
* @self: a carousel
*
- * Gets duration of the animation used when adding or removing pages.
+ * Gets the page reveal duration, in milliseconds.
*
* Returns: the duration
*
@@ -1765,7 +1783,9 @@ adw_carousel_get_reveal_duration (AdwCarousel *self)
* @self: a carousel
* @reveal_duration: the new reveal duration value
*
- * Sets duration of the animation used when adding or removing pages.
+ * Sets the page reveal duration, in milliseconds.
+ *
+ * Reveal duration is used when animating adding or removing pages.
*
* Since: 1.0
*/
diff --git a/src/adw-clamp-layout.c b/src/adw-clamp-layout.c
index d807c1c4..84f0c0e5 100644
--- a/src/adw-clamp-layout.c
+++ b/src/adw-clamp-layout.c
@@ -360,7 +360,7 @@ adw_clamp_layout_class_init (AdwClampLayoutClass *klass)
/**
* AdwClampLayout:tightening-threshold: (attributes
org.gtk.Property.get=adw_clamp_layout_get_tightening_threshold
org.gtk.Property.set=adw_clamp_layout_set_tightening_threshold)
*
- * The size above which the child is clamped.
+ * The size above which the children are clamped.
*
* Starting from this size, the layout will tighten its grip on the children,
* slowly allocating less and less of the available size up to the maximum
@@ -432,6 +432,8 @@ adw_clamp_layout_get_maximum_size (AdwClampLayout *self)
*
* Sets the maximum size allocated to the children.
*
+ * It is the width if the layout is horizontal, or the height if it is vertical.
+ *
* Since: 1.0
*/
void
@@ -475,6 +477,19 @@ adw_clamp_layout_get_tightening_threshold (AdwClampLayout *self)
*
* Sets the size above which the children are clamped.
*
+ * Starting from this size, the layout will tighten its grip on the children,
+ * slowly allocating less and less of the available size up to the maximum
+ * allocated size. Below that threshold and below the maximum size, the children
+ * will be allocated all the available size.
+ *
+ * If the threshold is greater than the maximum size to allocate to the
+ * children, they will be allocated the whole size up to the maximum. If the
+ * threshold is lower than the minimum size to allocate to the children, that
+ * size will be used as the tightening threshold.
+ *
+ * Effectively, tightening the grip on a child before it reaches its maximum
+ * size makes transitions to and from the maximum size smoother when resizing.
+ *
* Since: 1.0
*/
void
diff --git a/src/adw-clamp-scrollable.c b/src/adw-clamp-scrollable.c
index 3eebb9a7..8ad8cd43 100644
--- a/src/adw-clamp-scrollable.c
+++ b/src/adw-clamp-scrollable.c
@@ -451,6 +451,8 @@ adw_clamp_scrollable_get_maximum_size (AdwClampScrollable *self)
*
* Sets the maximum size allocated to the child.
*
+ * It is the width if the clamp is horizontal, or the height if it is vertical.
+ *
* Since: 1.0
*/
void
@@ -500,6 +502,19 @@ adw_clamp_scrollable_get_tightening_threshold (AdwClampScrollable *self)
*
* Sets the size above which the child is clamped.
*
+ * Starting from this size, the clamp will tighten its grip on the child, slowly
+ * allocating less and less of the available size up to the maximum allocated
+ * size. Below that threshold and below the maximum width, the child will be
+ * allocated all the available size.
+ *
+ * If the threshold is greater than the maximum size to allocate to the child,
+ * the child will be allocated all the width up to the maximum. If the threshold
+ * is lower than the minimum size to allocate to the child, that size will be
+ * used as the tightening threshold.
+ *
+ * Effectively, tightening the grip on the child before it reaches its maximum
+ * size makes transitions to and from the maximum size smoother when resizing.
+ *
* Since: 1.0
*/
void
diff --git a/src/adw-clamp.c b/src/adw-clamp.c
index c06790b9..4450b929 100644
--- a/src/adw-clamp.c
+++ b/src/adw-clamp.c
@@ -343,6 +343,8 @@ adw_clamp_get_maximum_size (AdwClamp *self)
*
* Sets the maximum size allocated to the child.
*
+ * It is the width if the clamp is horizontal, or the height if it is vertical.
+ *
* Since: 1.0
*/
void
@@ -392,6 +394,19 @@ adw_clamp_get_tightening_threshold (AdwClamp *self)
*
* Sets the size above which the child is clamped.
*
+ * Starting from this size, the clamp will tighten its grip on the child, slowly
+ * allocating less and less of the available size up to the maximum allocated
+ * size. Below that threshold and below the maximum size, the child will be
+ * allocated all the available size.
+ *
+ * If the threshold is greater than the maximum size to allocate to the child,
+ * the child will be allocated all the size up to the maximum. If the threshold
+ * is lower than the minimum size to allocate to the child, that size will be
+ * used as the tightening threshold.
+ *
+ * Effectively, tightening the grip on the child before it reaches its maximum
+ * size makes transitions to and from the maximum size smoother when resizing.
+ *
* Since: 1.0
*/
void
diff --git a/src/adw-combo-row.c b/src/adw-combo-row.c
index ba799a95..94045896 100644
--- a/src/adw-combo-row.c
+++ b/src/adw-combo-row.c
@@ -438,7 +438,7 @@ adw_combo_row_class_init (AdwComboRowClass *klass)
/**
* AdwComboRow:model: (attributes org.gtk.Property.get=adw_combo_row_get_model
org.gtk.Property.set=adw_combo_row_set_model)
*
- * Model for the displayed items.
+ * The model that provides the displayed items.
*
* Since: 1.0
*/
@@ -508,10 +508,11 @@ adw_combo_row_class_init (AdwComboRowClass *klass)
*
* An expression used to obtain strings from items.
*
- * It's used to bind strings to labels produced by the default factory.
+ * The expression must have a value type of `G_TYPE_STRING`.
*
- * If [property@ComboRow:factory] is not set, the expression is also used to
- * bind strings to labels produced by a default factory.
+ * It's used to bind strings to labels produced by the default factory if
+ * [property@ComboRow:factory] is not set, or when
+ * [property@ComboRow:use-subtitle] is set to `TRUE`.
*
* Since: 1.0
*/
@@ -529,7 +530,7 @@ adw_combo_row_class_init (AdwComboRowClass *klass)
* If you use a custom list item factory, you will need to give the row a
* name conversion expression with [property@ComboRow:expression].
*
- * If `TRUE`, you should not access [property@ActionRow:subtitle].
+ * If set to `TRUE`, you should not access [property@ActionRow:subtitle].
*
* The subtitle is interpreted as Pango markup if
* [property@PreferencesRow:use-markup] is set to `TRUE`.
@@ -687,7 +688,7 @@ adw_combo_row_get_model (AdwComboRow *self)
* @self: a combo row
* @model: (nullable) (transfer none): the model to use
*
- * Sets the [iface@Gio.ListModel] to use.
+ * Sets the model that provides the displayed items.
*
* Since: 1.0
*/
@@ -750,7 +751,7 @@ adw_combo_row_set_model (AdwComboRow *self,
* adw_combo_row_get_factory: (attributes org.gtk.Method.get_property=factory)
* @self: a combo row
*
- * Gets the factory that's currently used to populate list items.
+ * Gets the factory for populating list items.
*
* Returns: (nullable) (transfer none): the factory in use
*
@@ -773,7 +774,10 @@ adw_combo_row_get_factory (AdwComboRow *self)
* @self: a combo row
* @factory: (nullable) (transfer none): the factory to use
*
- * Sets the `GtkListItemFactory` to use for populating list items.
+ * Sets the factory for populating list items.
+ *
+ * This factory is always used for the item in the row. It is also used for
+ * items in the popup unless [property@ComboRow:list-factory] is set.
*
* Since: 1.0
*/
@@ -803,7 +807,7 @@ adw_combo_row_set_factory (AdwComboRow *self,
* adw_combo_row_get_list_factory: (attributes org.gtk.Method.get_property=list-factory)
* @self: a combo row
*
- * Gets the factory that's currently used to populate list items in the popup.
+ * Gets the factory for populating list items in the popup.
*
* Returns: (nullable) (transfer none): the factory in use
*
@@ -826,7 +830,9 @@ adw_combo_row_get_list_factory (AdwComboRow *self)
* @self: a combo row
* @factory: (nullable) (transfer none): the factory to use
*
- * Sets the `GtkListItemFactory` to use for populating list items in the popup.
+ * Sets the factory for populating list items in the popup.
+ *
+ * If this is not set, [property@ComboRow:factory] is used.
*
* Since: 1.0
*/
@@ -883,6 +889,10 @@ adw_combo_row_get_expression (AdwComboRow *self)
*
* The expression must have a value type of `G_TYPE_STRING`.
*
+ * It's used to bind strings to labels produced by the default factory if
+ * [property@ComboRow:factory] is not set, or when
+ * [property@ComboRow:use-subtitle] is set to `TRUE`.
+ *
* Since: 1.0
*/
void
@@ -940,6 +950,14 @@ adw_combo_row_get_use_subtitle (AdwComboRow *self)
*
* Sets whether to use the current value as the subtitle.
*
+ * If you use a custom list item factory, you will need to give the row a
+ * name conversion expression with [property@ComboRow:expression].
+ *
+ * If set to `TRUE`, you should not access [property@ActionRow:subtitle].
+ *
+ * The subtitle is interpreted as Pango markup if
+ * [property@PreferencesRow:use-markup] is set to `TRUE`.
+ *
* Since: 1.0
*/
void
diff --git a/src/adw-entry-row.c b/src/adw-entry-row.c
index bf329f39..5cb37669 100644
--- a/src/adw-entry-row.c
+++ b/src/adw-entry-row.c
@@ -522,8 +522,7 @@ adw_entry_row_class_init (AdwEntryRowClass *klass)
*
* Whether to suggest emoji replacements on the entry row.
*
- * Emoji replacement is done with :-delimited names,
- * like `:heart:`.
+ * Emoji replacement is done with :-delimited names, like `:heart:`.
*
* Since: 1.2
*/
@@ -801,6 +800,14 @@ adw_entry_row_get_show_apply_button (AdwEntryRow *self)
*
* Sets whether @self can show the apply button.
*
+ * When set to `TRUE`, typing text in the entry will reveal an apply button.
+ * Clicking it or pressing the <kbd>Enter</kbd> key will hide the button and
+ * emit the [signal@EntryRow::apply] signal.
+ *
+ * This is useful if changing the entry contents can trigger an expensive
+ * operation, e.g. network activity, to avoid triggering it after typing every
+ * character.
+ *
* Since: 1.2
*/
void
@@ -990,9 +997,6 @@ adw_entry_row_set_attributes (AdwEntryRow *self,
*
* Gets whether to suggest emoji replacements on @self.
*
- * Emoji replacement is done with :-delimited names,
- * like `:heart:`.
- *
* Returns: whether or not emoji completion is enabled
*
* Since: 1.2
@@ -1016,8 +1020,7 @@ adw_entry_row_get_enable_emoji_completion (AdwEntryRow *self)
*
* Sets whether to suggest emoji replacements on @self.
*
- * Emoji replacement is done with :-delimited names,
- * like `:heart:`.
+ * Emoji replacement is done with :-delimited names, like `:heart:`.
*
* Since: 1.2
*/
diff --git a/src/adw-expander-row.c b/src/adw-expander-row.c
index 79eff775..d1cda5d1 100644
--- a/src/adw-expander-row.c
+++ b/src/adw-expander-row.c
@@ -181,6 +181,9 @@ adw_expander_row_class_init (AdwExpanderRowClass *klass)
*
* The subtitle for this row.
*
+ * The subtitle is interpreted as Pango markup unless
+ * [property@PreferencesRow:use-markup] is set to `FALSE`.
+ *
* Since: 1.0
*/
props[PROP_SUBTITLE] =
diff --git a/src/adw-flap.c b/src/adw-flap.c
index 94b4b83f..1128047c 100644
--- a/src/adw-flap.c
+++ b/src/adw-flap.c
@@ -1268,8 +1268,7 @@ adw_flap_class_init (AdwFlapClass *klass)
*
* The content widget.
*
- * It's always displayed when unfolded, and partially visible
- * when folded.
+ * It's always displayed when unfolded, and partially visible when folded.
*
* Since: 1.0
*/
@@ -1828,6 +1827,8 @@ adw_flap_get_content (AdwFlap *self)
*
* Sets the content widget for @self.
*
+ * It's always displayed when unfolded, and partially visible when folded.
+ *
* Since: 1.0
*/
void
@@ -1878,6 +1879,8 @@ adw_flap_get_flap (AdwFlap *self)
*
* Sets the flap widget for @self.
*
+ * It's only visible when [property@Flap:reveal-progress] is greater than 0.
+ *
* Since: 1.0
*/
void
@@ -1929,6 +1932,10 @@ adw_flap_get_separator (AdwFlap *self)
*
* Sets the separator widget for @self.
*
+ * It's displayed between content and flap when there's no shadow to display.
+ * When exactly it's visible depends on the [property@Flap:transition-type]
+ * value.
+ *
* Since: 1.0
*/
void
@@ -1979,6 +1986,9 @@ adw_flap_get_flap_position (AdwFlap *self)
*
* Sets the flap position for @self.
*
+ * If it's set to `GTK_PACK_START`, the flap is displayed before the content,
+ * if `GTK_PACK_END`, it's displayed after the content.
+ *
* Since: 1.0
*/
void
@@ -2060,6 +2070,12 @@ adw_flap_get_reveal_params (AdwFlap *self)
*
* Sets the reveal animation spring parameters for @self.
*
+ * The default value is equivalent to:
+ *
+ * ```c
+ * adw_spring_params_new (1, 0.5, 500)
+ * ```
+ *
* Since: 1.0
*/
void
@@ -2084,6 +2100,10 @@ adw_flap_set_reveal_params (AdwFlap *self,
*
* Gets the current reveal progress for @self.
*
+ * 0 means fully hidden, 1 means fully revealed.
+ *
+ * See [property@Flap:reveal-flap].
+ *
* Returns: the current reveal progress for @self
*
* Since: 1.0
@@ -2159,7 +2179,7 @@ adw_flap_set_fold_policy (AdwFlap *self,
* adw_flap_get_fold_duration: (attributes org.gtk.Method.get_property=fold-duration)
* @self: a flap
*
- * Gets the duration that fold transitions in @self will take.
+ * Gets the fold transition animation duration for @self, in milliseconds.
*
* Returns: the fold transition duration
*
@@ -2178,7 +2198,7 @@ adw_flap_get_fold_duration (AdwFlap *self)
* @self: a flap
* @duration: the new duration, in milliseconds
*
- * Sets the duration that fold transitions in @self will take.
+ * Sets the fold transition animation duration for @self, in milliseconds.
*
* Since: 1.0
*/
@@ -2202,6 +2222,8 @@ adw_flap_set_fold_duration (AdwFlap *self,
*
* Gets whether @self is currently folded.
*
+ * See [property@Flap:fold-policy].
+ *
* Returns: `TRUE` if @self is currently folded
*
* Since: 1.0
@@ -2239,6 +2261,10 @@ adw_flap_get_locked (AdwFlap *self)
*
* Sets whether @self is locked.
*
+ * If `FALSE`, folding when the flap is revealed automatically closes it, and
+ * unfolding it when the flap is not revealed opens it. If `TRUE`,
+ * [property@Flap:reveal-flap] value never changes on its own.
+ *
* Since: 1.0
*/
void
@@ -2282,6 +2308,11 @@ adw_flap_get_transition_type (AdwFlap *self)
*
* Sets the type of animation used for reveal and fold transitions in @self.
*
+ * [property@Flap:flap] is transparent by default, which means the content will
+ * be seen through it with `ADW_FLAP_TRANSITION_TYPE_OVER` transitions; add the
+ * [`.background`](style-classes.html#background) style class to it if this is
+ * unwanted.
+ *
* Since: 1.0
*/
void
@@ -2329,6 +2360,10 @@ adw_flap_get_modal (AdwFlap *self)
*
* Sets whether @self is modal.
*
+ * If `TRUE`, clicking the content widget while flap is revealed, as well as
+ * pressing the <kbd>Esc</kbd> key, will close the flap. If `FALSE`, clicks are
+ * passed through to the content widget.
+ *
* Since: 1.0
*/
void
@@ -2377,6 +2412,9 @@ adw_flap_get_swipe_to_open (AdwFlap *self)
*
* Sets whether @self can be opened with a swipe gesture.
*
+ * The area that can be swiped depends on the [property@Flap:transition-type]
+ * value.
+ *
* Since: 1.0
*/
void
@@ -2422,6 +2460,9 @@ adw_flap_get_swipe_to_close (AdwFlap *self)
*
* Sets whether @self can be closed with a swipe gesture.
*
+ * The area that can be swiped depends on the [property@Flap:transition-type]
+ * value.
+ *
* Since: 1.0
*/
void
@@ -2465,6 +2506,13 @@ adw_flap_get_fold_threshold_policy (AdwFlap *self)
*
* Sets the fold threshold policy for @self.
*
+ * If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, flap will only fold when the
+ * children cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, it
+ * will fold as soon as children don't get their natural size.
+ *
+ * This can be useful if you have a long ellipsizing label and want to let it
+ * ellipsize instead of immediately folding.
+ *
* Since: 1.0
*/
void
diff --git a/src/adw-header-bar.c b/src/adw-header-bar.c
index f3e85352..4466047c 100644
--- a/src/adw-header-bar.c
+++ b/src/adw-header-bar.c
@@ -614,6 +614,21 @@ adw_header_bar_pack_end (AdwHeaderBar *self,
*
* Sets the title widget for @self.
*
+ * When set to `NULL`, the header bar will display the title of the window it
+ * is contained in.
+ *
+ * To use a different title, use [class@WindowTitle]:
+ *
+ * ```xml
+ * <object class="AdwHeaderBar">
+ * <property name="title-widget">
+ * <object class="AdwWindowTitle">
+ * <property name="title" translatable="yes">Title</property>
+ * </object>
+ * </property>
+ * </object>
+ * ```
+ *
* Since: 1.0
*/
void
@@ -720,6 +735,12 @@ adw_header_bar_get_show_start_title_buttons (AdwHeaderBar *self)
*
* Sets whether to show title buttons at the start of @self.
*
+ * See [property@HeaderBar:show-end-title-buttons] for the other side.
+ *
+ * Which buttons are actually shown and where is determined by the
+ * [property@HeaderBar:decoration-layout] property, and by the state of the
+ * window (e.g. a close button will not be shown if the window can't be closed).
+ *
* Since: 1.0
*/
void
@@ -772,6 +793,12 @@ adw_header_bar_get_show_end_title_buttons (AdwHeaderBar *self)
*
* Sets whether to show title buttons at the end of @self.
*
+ * See [property@HeaderBar:show-start-title-buttons] for the other side.
+ *
+ * Which buttons are actually shown and where is determined by the
+ * [property@HeaderBar:decoration-layout] property, and by the state of the
+ * window (e.g. a close button will not be shown if the window can't be closed).
+ *
* Since: 1.0
*/
void
@@ -806,6 +833,17 @@ adw_header_bar_set_show_end_title_buttons (AdwHeaderBar *self,
*
* Sets the decoration layout for @self.
*
+ * If this property is not set, the
+ * [property@Gtk.Settings:gtk-decoration-layout] setting is used.
+ *
+ * The format of the string is button names, separated by commas. A colon
+ * separates the buttons that should appear at the start from those at the end.
+ * Recognized button names are minimize, maximize, close and icon (the window
+ * icon).
+ *
+ * For example, “icon:minimize,maximize,close” specifies an icon at the start,
+ * and minimize, maximize and close buttons at the end.
+ *
* Since: 1.0
*/
void
diff --git a/src/adw-leaflet.c b/src/adw-leaflet.c
index be95385d..10df330e 100644
--- a/src/adw-leaflet.c
+++ b/src/adw-leaflet.c
@@ -277,7 +277,7 @@ adw_leaflet_page_class_init (AdwLeafletPageClass *klass)
/**
* AdwLeafletPage:child: (attributes org.gtk.Property.get=adw_leaflet_page_get_child)
*
- * The child of the page.
+ * The leaflet child to which the page belongs.
*
* Since: 1.0
*/
@@ -2189,7 +2189,8 @@ adw_leaflet_class_init (AdwLeafletClass *klass)
* Whether the leaflet is folded.
*
* The leaflet will be folded if the size allocated to it is smaller than the
- * sum of the fold threshold policy, it will be unfolded otherwise.
+ * sum of the minimum or natural sizes of the children (see
+ * [property@Leaflet:fold-threshold-policy]), it will be unfolded otherwise.
*
* Since: 1.0
*/
@@ -2203,9 +2204,9 @@ adw_leaflet_class_init (AdwLeafletClass *klass)
*
* Determines when the leaflet will fold.
*
- * If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, it will only fold when
- * the children cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`,
- * it will fold as soon as children don't get their natural size.
+ * If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, it will only fold when the
+ * children cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, it
+ * will fold as soon as children don't get their natural size.
*
* This can be useful if you have a long ellipsizing label and want to let it
* ellipsize instead of immediately folding.
@@ -2239,9 +2240,9 @@ adw_leaflet_class_init (AdwLeafletClass *klass)
* The widget currently visible when the leaflet is folded.
*
* The transition is determined by [property@Leaflet:transition-type] and
- * [property@Leaflet:child-transition-params]. The transition can be
- * cancelled by the user, in which case visible child will change back to the
- * previously visible child.
+ * [property@Leaflet:child-transition-params]. The transition can be cancelled
+ * by the user, in which case visible child will change back to the previously
+ * visible child.
*
* Since: 1.0
*/
@@ -2672,7 +2673,7 @@ adw_leaflet_swipeable_init (AdwSwipeableInterface *iface)
* adw_leaflet_page_get_child: (attributes org.gtk.Method.get_property=child)
* @self: a leaflet page
*
- * Gets the leaflet child th which @self belongs.
+ * Gets the leaflet child to which @self belongs.
*
* Returns: (transfer none): the child to which @self belongs
*
@@ -2778,6 +2779,11 @@ adw_leaflet_page_get_navigatable (AdwLeafletPage *self)
*
* Sets whether @self can be navigated to when folded.
*
+ * If `FALSE`, the child will be ignored by [method@Leaflet.get_adjacent_child],
+ * [method@Leaflet.navigate], and swipe gestures.
+ *
+ * This can be used used to prevent switching to widgets like separators.
+ *
* Since: 1.0
*/
void
@@ -3038,6 +3044,10 @@ adw_leaflet_get_page (AdwLeaflet *self,
*
* Gets whether @self is folded.
*
+ * The leaflet will be folded if the size allocated to it is smaller than the
+ * sum of the minimum or natural sizes of the children (see
+ * [property@Leaflet:fold-threshold-policy]), it will be unfolded otherwise.
+ *
* Returns: whether @self is folded.
*
* Since: 1.0
@@ -3123,6 +3133,10 @@ adw_leaflet_get_transition_type (AdwLeaflet *self)
*
* Sets the type of animation used for transitions between modes and children.
*
+ * The transition type can be changed without problems at runtime, so it is
+ * possible to change the animation based on the mode or child that is about to
+ * become current.
+ *
* Since: 1.0
*/
void
@@ -3222,6 +3236,12 @@ adw_leaflet_get_child_transition_params (AdwLeaflet *self)
*
* Sets the child transition spring parameters for @self.
*
+ * The default value is equivalent to:
+ *
+ * ```c
+ * adw_spring_params_new (1, 0.5, 500)
+ * ```
+ *
* Since: 1.0
*/
void
@@ -3268,6 +3288,11 @@ adw_leaflet_get_visible_child (AdwLeaflet *self)
*
* Sets the widget currently visible when the leaflet is folded.
*
+ * The transition is determined by [property@Leaflet:transition-type] and
+ * [property@Leaflet:child-transition-params]. The transition can be cancelled
+ * by the user, in which case visible child will change back to the previously
+ * visible child.
+ *
* Since: 1.0
*/
void
@@ -3317,7 +3342,7 @@ adw_leaflet_get_visible_child_name (AdwLeaflet *self)
*
* Makes the child with the name @name visible.
*
- * See adw_leaflet_set_visible_child() for more details.
+ * See [property@Leaflet:visible-child].
*
* Since: 1.0
*/
@@ -3364,6 +3389,22 @@ adw_leaflet_get_child_transition_running (AdwLeaflet *self)
*
* Sets whether gestures and shortcuts for navigating backward are enabled.
*
+ * The supported gestures are:
+ *
+ * - One-finger swipe on touchscreens
+ * - Horizontal scrolling on touchpads (usually two-finger swipe)
+ * - Back/forward mouse buttons
+ *
+ * The keyboard back/forward keys are also supported, as well as the
+ * <kbd>Alt</kbd>+<kbd>←</kbd> shortcut for horizontal orientation, or
+ * <kbd>Alt</kbd>+<kbd>↑</kbd> for vertical orientation.
+ *
+ * If the orientation is horizontal, for right-to-left locales, gestures and
+ * shortcuts are reversed.
+ *
+ * Only children that have [property@LeafletPage:navigatable] set to `TRUE` can
+ * be navigated to.
+ *
* Since: 1.0
*/
void
@@ -3408,6 +3449,22 @@ adw_leaflet_get_can_navigate_back (AdwLeaflet *self)
*
* Sets whether gestures and shortcuts for navigating forward are enabled.
*
+ * The supported gestures are:
+ *
+ * - One-finger swipe on touchscreens
+ * - Horizontal scrolling on touchpads (usually two-finger swipe)
+ * - Back/forward mouse buttons
+ *
+ * The keyboard back/forward keys are also supported, as well as the
+ * <kbd>Alt</kbd>+<kbd>→</kbd> shortcut for horizontal orientation, or
+ * <kbd>Alt</kbd>+<kbd>↓</kbd> for vertical orientation.
+ *
+ * If the orientation is horizontal, for right-to-left locales, gestures and
+ * shortcuts are reversed.
+ *
+ * Only children that have [property@LeafletPage:navigatable] set to `TRUE` can
+ * be navigated to.
+ *
* Since: 1.0
*/
void
@@ -3639,6 +3696,13 @@ adw_leaflet_get_fold_threshold_policy (AdwLeaflet *self)
*
* Sets the fold threshold policy for @self.
*
+ * If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, it will only fold when the
+ * children cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, it
+ * will fold as soon as children don't get their natural size.
+ *
+ * This can be useful if you have a long ellipsizing label and want to let it
+ * ellipsize instead of immediately folding.
+ *
* Since: 1.0
*/
void
diff --git a/src/adw-preferences-group.c b/src/adw-preferences-group.c
index 1177dcd2..45fd3585 100644
--- a/src/adw-preferences-group.c
+++ b/src/adw-preferences-group.c
@@ -258,12 +258,16 @@ adw_preferences_group_class_init (AdwPreferencesGroupClass *klass)
g_param_spec_string ("title", NULL, NULL,
"",
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS | G_PARAM_EXPLICIT_NOTIFY);
+
/**
* AdwPreferencesGroup:header-suffix: (attributes
org.gtk.Property.get=adw_preferences_group_get_header_suffix
org.gtk.Property.set=adw_preferences_group_set_header_suffix)
*
* The header suffix widget.
*
- * Displayed above the list, next to the title and description. Suffixes are commonly used to show a
button or a spinner for the whole group.
+ * Displayed above the list, next to the title and description.
+ *
+ * Suffixes are commonly used to show a button or a spinner for the whole
+ * group.
*
* Since: 1.1
*/
@@ -581,6 +585,10 @@ adw_preferences_group_get_header_suffix (AdwPreferencesGroup *self)
*
* Sets the suffix for @self's header.
*
+ * Displayed above the list, next to the title and description.
+ *
+ * Suffixes are commonly used to show a button or a spinner for the whole group.
+ *
* Since: 1.1
*/
void
diff --git a/src/adw-preferences-row.c b/src/adw-preferences-row.c
index 1ba124d0..60e0243c 100644
--- a/src/adw-preferences-row.c
+++ b/src/adw-preferences-row.c
@@ -122,6 +122,9 @@ adw_preferences_row_class_init (AdwPreferencesRowClass *klass)
*
* The title of the preference represented by this row.
*
+ * The title is interpreted as Pango markup unless
+ * [property@PreferencesRow:use-markup] is set to `FALSE`.
+ *
* Since: 1.0
*/
props[PROP_TITLE] =
@@ -328,6 +331,8 @@ adw_preferences_row_get_title_selectable (AdwPreferencesRow *self)
*
* Sets whether the user can copy the title from the label
*
+ * See also [property@Gtk.Label:selectable].
+ *
* Since: 1.1
*/
void
@@ -377,6 +382,10 @@ adw_preferences_row_get_use_markup (AdwPreferencesRow *self)
*
* Sets whether to use Pango markup for the title label.
*
+ * Subclasses may also use it for other labels, such as subtitle.
+ *
+ * See also [func@Pango.parse_markup].
+ *
* Since: 1.2
*/
void
diff --git a/src/adw-preferences-window.c b/src/adw-preferences-window.c
index 0eab5513..4f2387c0 100644
--- a/src/adw-preferences-window.c
+++ b/src/adw-preferences-window.c
@@ -780,6 +780,17 @@ adw_preferences_window_set_search_enabled (AdwPreferencesWindow *self,
*
* Sets whether gestures and shortcuts for closing subpages are enabled.
*
+ * The supported gestures are:
+ *
+ * - One-finger swipe on touchscreens
+ * - Horizontal scrolling on touchpads (usually two-finger swipe)
+ * - Back mouse button
+ *
+ * The keyboard back key is also supported, as well as the
+ * <kbd>Alt</kbd>+<kbd>←</kbd> shortcut.
+ *
+ * For right-to-left locales, gestures and shortcuts are reversed.
+ *
* Since: 1.0
*/
void
@@ -1015,6 +1026,8 @@ adw_preferences_window_get_visible_page_name (AdwPreferencesWindow *self)
*
* Makes the page with the given name visible.
*
+ * See [property@ViewStack:visible-child].
+ *
* Since: 1.0
*/
void
diff --git a/src/adw-split-button.c b/src/adw-split-button.c
index 6660a974..6e283a0d 100644
--- a/src/adw-split-button.c
+++ b/src/adw-split-button.c
@@ -348,8 +348,8 @@ adw_split_button_class_init (AdwSplitButtonClass *klass)
* If the menu model is `NULL`, the dropdown is disabled.
*
* A [class@Gtk.Popover] will be created from the menu model with
- * [ctor@Gtk.PopoverMenu.new_from_model]. Actions will be connected
- * as documented for this function.
+ * [ctor@Gtk.PopoverMenu.new_from_model]. Actions will be connected as
+ * documented for this function.
*
* If [property@SplitButton:popover] is already set, it will be dissociated
* from the button, and the property is set to `NULL`.
@@ -385,8 +385,8 @@ adw_split_button_class_init (AdwSplitButtonClass *klass)
*
* The dropdown arrow icon will point at the same direction.
*
- * If the does not fit in the available space in the given direction,
- * GTK will its best to keep it inside the screen and fully visible.
+ * If the does not fit in the available space in the given direction, GTK will
+ * try its best to keep it inside the screen and fully visible.
*
* If you pass `GTK_ARROW_NONE`, it's equivalent to `GTK_ARROW_DOWN`.
*
@@ -628,6 +628,9 @@ adw_split_button_get_label (AdwSplitButton *self)
*
* Sets the label for @self.
*
+ * Setting the label will set [property@SplitButton:icon-name] and
+ * [property@SplitButton:child] to `NULL`.
+ *
* Since: 1.0
*/
void
@@ -678,6 +681,8 @@ adw_split_button_get_use_underline (AdwSplitButton *self)
*
* Sets whether an underline in the text indicates a mnemonic.
*
+ * See [property@SplitButton:label].
+ *
* Since: 1.0
*/
void
@@ -700,9 +705,6 @@ adw_split_button_set_use_underline (AdwSplitButton *self,
*
* Gets the name of the icon used to automatically populate the button.
*
- * If the icon name has not been set with [method@SplitButton.set_icon_name]
- * the return value will be `NULL`.
- *
* Returns: (nullable): the icon name
*
* Since: 1.0
@@ -722,6 +724,9 @@ adw_split_button_get_icon_name (AdwSplitButton *self)
*
* Sets the name of the icon used to automatically populate the button.
*
+ * Setting the icon name will set [property@SplitButton:label] and
+ * [property@SplitButton:child] to `NULL`.
+ *
* Since: 1.0
*/
void
@@ -773,6 +778,9 @@ adw_split_button_get_child (AdwSplitButton *self)
*
* Sets the child widget.
*
+ * Setting the child widget will set [property@SplitButton:label] and
+ * [property@SplitButton:icon-name] to `NULL`.
+ *
* Since: 1.0
*/
void
@@ -823,6 +831,15 @@ adw_split_button_get_menu_model (AdwSplitButton *self)
*
* Sets the menu model from which the popup will be created.
*
+ * If the menu model is `NULL`, the dropdown is disabled.
+ *
+ * A [class@Gtk.Popover] will be created from the menu model with
+ * [ctor@Gtk.PopoverMenu.new_from_model]. Actions will be connected as
+ * documented for this function.
+ *
+ * If [property@SplitButton:popover] is already set, it will be dissociated from
+ * the button, and the property is set to `NULL`.
+ *
* Since: 1.0
*/
void
@@ -862,6 +879,11 @@ adw_split_button_get_popover (AdwSplitButton *self)
*
* Sets the popover that will be popped up when the dropdown is clicked.
*
+ * If the popover is `NULL`, the dropdown is disabled.
+ *
+ * If [property@SplitButton:menu-model] is set, the menu model is dissociated
+ * from the button, and the property is set to `NULL`.
+ *
* Since: 1.0
*/
void
@@ -901,6 +923,13 @@ adw_split_button_get_direction (AdwSplitButton *self)
*
* Sets the direction in which the popup will be popped up.
*
+ * The dropdown arrow icon will point at the same direction.
+ *
+ * If the does not fit in the available space in the given direction, GTK will
+ * try its best to keep it inside the screen and fully visible.
+ *
+ * If you pass `GTK_ARROW_NONE`, it's equivalent to `GTK_ARROW_DOWN`.
+ *
* Since: 1.0
*/
void
diff --git a/src/adw-spring-animation.c b/src/adw-spring-animation.c
index d5b7d00d..9e60812b 100644
--- a/src/adw-spring-animation.c
+++ b/src/adw-spring-animation.c
@@ -603,6 +603,9 @@ adw_spring_animation_get_value_from (AdwSpringAnimation *self)
*
* Sets the value @self will animate from.
*
+ * The animation will start at this value and end at
+ * [property@SpringAnimation:value-to].
+ *
* Since: 1.0
*/
void
@@ -646,6 +649,9 @@ adw_spring_animation_get_value_to (AdwSpringAnimation *self)
*
* Sets the value @self will animate to.
*
+ * The animation will start at [property@SpringAnimation:value-from] and end at
+ * this value.
+ *
* Since: 1.0
*/
void
@@ -734,6 +740,8 @@ adw_spring_animation_get_initial_velocity (AdwSpringAnimation *self)
*
* Sets the initial velocity of @self.
*
+ * Initial velocity affects only the animation curve, but not its duration.
+ *
* Since: 1.0
*/
void
@@ -756,7 +764,7 @@ adw_spring_animation_set_initial_velocity (AdwSpringAnimation *self,
* adw_spring_animation_get_epsilon: (attributes org.gtk.Method.get_property=epsilon)
* @self: a spring animation
*
- * Gets the precision used to determine the duration of @self.
+ * Gets the precision of the spring.
*
* Returns: the epsilon value
*
@@ -775,7 +783,18 @@ adw_spring_animation_get_epsilon (AdwSpringAnimation *self)
* @self: a spring animation
* @epsilon: the new value
*
- * Sets the precision used to determine the duration of @self.
+ * Sets the precision of the spring.
+ *
+ * The level of precision used to determine when the animation has come to a
+ * rest, that is, when the amplitude of the oscillations becomes smaller than
+ * this value.
+ *
+ * If the epsilon value is too small, the animation will take a long time to
+ * stop after the animated value has stopped visibly changing.
+ *
+ * If the epsilon value is too large, the animation will end prematurely.
+ *
+ * The default value is 0.001.
*
* Since: 1.0
*/
@@ -821,6 +840,12 @@ adw_spring_animation_get_clamp (AdwSpringAnimation *self)
*
* Sets whether @self should be clamped.
*
+ * If set to `TRUE`, the animation will abruptly end as soon as it reaches the
+ * final value, preventing overshooting.
+ *
+ * It won't prevent overshooting [property@SpringAnimation:value-from] if a
+ * relative negative [property@SpringAnimation:initial-velocity] is set.
+ *
* Since: 1.0
*/
void
@@ -845,6 +870,8 @@ adw_spring_animation_set_clamp (AdwSpringAnimation *self,
*
* Gets the estimated duration of @self.
*
+ * Can be [const@DURATION_INFINITE] if the spring damping is set to 0.
+ *
* Returns: the estimated duration
*
* Since: 1.0
diff --git a/src/adw-squeezer.c b/src/adw-squeezer.c
index 4cb4134e..b64729e9 100644
--- a/src/adw-squeezer.c
+++ b/src/adw-squeezer.c
@@ -219,7 +219,7 @@ adw_squeezer_page_class_init (AdwSqueezerPageClass *klass)
/**
* AdwSqueezerPage:child: (attributes org.gtk.Property.get=adw_squeezer_page_get_child)
*
- * The child of the page.
+ * The the squeezer child to which the page belongs.
*
* Since: 1.0
*/
@@ -1043,9 +1043,9 @@ adw_squeezer_class_init (AdwSqueezerClass *klass)
*
* Whether all children have the same size for the opposite orientation.
*
- * For example, if a squeezer is horizontal and is homogeneous, it will request
- * the same height for all its children. If it isn't, the squeezer may change
- * size when a different child becomes visible.
+ * For example, if a squeezer is horizontal and is homogeneous, it will
+ * request the same height for all its children. If it isn't, the squeezer may
+ * change size when a different child becomes visible.
*
* Since: 1.0
*/
@@ -1057,12 +1057,13 @@ adw_squeezer_class_init (AdwSqueezerClass *klass)
/**
* AdwSqueezer:switch-threshold-policy: (attributes
org.gtk.Property.get=adw_squeezer_get_switch_threshold_policy
org.gtk.Property.set=adw_squeezer_set_switch_threshold_policy)
*
+ * The switch threshold policy.
+ *
* Determines when the squeezer will switch children.
*
- * If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, it will only switch when
- * the visible child cannot fit anymore. With
- * `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, it will switch as soon as the visible
- * child doesn't get their natural size.
+ * If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, it will only switch when the
+ * visible child cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`,
+ * it will switch as soon as the visible child doesn't get their natural size.
*
* This can be useful if you have a long ellipsizing label and want to let it
* ellipsize instead of immediately switching.
@@ -1093,7 +1094,7 @@ adw_squeezer_class_init (AdwSqueezerClass *klass)
* Whether to allow squeezing beyond the last child's minimum size.
*
* If set to `TRUE`, the squeezer can shrink to the point where no child can
- * be shown. This is functionally equivalent to appending a widget with 0x0
+ * be shown. This is functionally equivalent to appending a widget with 0×0
* minimum size.
*
* Since: 1.0
@@ -1106,7 +1107,7 @@ adw_squeezer_class_init (AdwSqueezerClass *klass)
/**
* AdwSqueezer:transition-duration: (attributes org.gtk.Property.get=adw_squeezer_get_transition_duration
org.gtk.Property.set=adw_squeezer_set_transition_duration)
*
- * The animation duration, in milliseconds.
+ * The transition animation duration, in milliseconds.
*
* Since: 1.0
*/
@@ -1306,6 +1307,15 @@ adw_squeezer_page_get_enabled (AdwSqueezerPage *self)
*
* Sets whether @self is enabled.
*
+ * If a child is disabled, it will be ignored when looking for the child
+ * fitting the available size best.
+ *
+ * This allows to programmatically and prematurely hide a child even if it fits
+ * in the available space.
+ *
+ * This can be used e.g. to ensure a certain child is hidden below a certain
+ * window width, or any other constraint you find suitable.
+ *
* Since: 1.0
*/
void
@@ -1455,6 +1465,10 @@ adw_squeezer_get_homogeneous (AdwSqueezer *self)
*
* Sets whether all children have the same size for the opposite orientation.
*
+ * For example, if a squeezer is horizontal and is homogeneous, it will request
+ * the same height for all its children. If it isn't, the squeezer may change
+ * size when a different child becomes visible.
+ *
* Since: 1.0
*/
void
@@ -1480,7 +1494,7 @@ adw_squeezer_set_homogeneous (AdwSqueezer *self,
* adw_squeezer_get_switch_threshold_policy: (attributes org.gtk.Method.get_property=switch-threshold-policy)
* @self: a squeezer
*
- * Gets the fold threshold policy for @self.
+ * Gets the switch threshold policy for @self.
*
* Since: 1.0
*/
@@ -1498,7 +1512,16 @@ adw_squeezer_get_switch_threshold_policy (AdwSqueezer *self)
* @self: a squeezer
* @policy: the policy to use
*
- * Sets the fold threshold policy for @self.
+ * Sets the switch threshold policy for @self.
+ *
+ * Determines when the squeezer will switch children.
+ *
+ * If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, it will only switch when the
+ * visible child cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`,
+ * it will switch as soon as the visible child doesn't get their natural size.
+ *
+ * This can be useful if you have a long ellipsizing label and want to let it
+ * ellipsize instead of immediately switching.
*
* Since: 1.0
*/
@@ -1544,6 +1567,10 @@ adw_squeezer_get_allow_none (AdwSqueezer *self)
*
* Sets whether to allow squeezing beyond the last child's minimum size.
*
+ * If set to `TRUE`, the squeezer can shrink to the point where no child can be
+ * shown. This is functionally equivalent to appending a widget with 0×0 minimum
+ * size.
+ *
* Since: 1.0
*/
void
@@ -1651,6 +1678,10 @@ adw_squeezer_set_transition_type (AdwSqueezer *self,
*
* Gets whether a transition is currently running for @self.
*
+ * If a transition is impossible, the property value will be set to `TRUE` and
+ * then immediately to `FALSE`, so it's possible to rely on its notifications
+ * to know that a transition has happened.
+ *
* Returns: whether a transition is currently running
*
* Since: 1.0
@@ -1688,6 +1719,11 @@ adw_squeezer_get_interpolate_size (AdwSqueezer *self)
*
* Sets whether @self interpolates its size when changing the visible child.
*
+ * If `TRUE`, the squeezer will interpolate its size between the one of the
+ * previous visible child and the one of the new visible child, according to the
+ * set transition duration and the orientation, e.g. if the squeezer is
+ * horizontal, it will interpolate the its height.
+ *
* Since: 1.0
*/
void
@@ -1748,6 +1784,12 @@ adw_squeezer_get_xalign (AdwSqueezer *self)
*
* Sets the horizontal alignment, from 0 (start) to 1 (end).
*
+ * This affects the children allocation during transitions, when they exceed the
+ * size of the squeezer.
+ *
+ * For example, 0.5 means the child will be centered, 0 means it will keep the
+ * start side aligned and overflow the end side, and 1 means the opposite.
+ *
* Since: 1.0
*/
void
@@ -1791,6 +1833,12 @@ adw_squeezer_get_yalign (AdwSqueezer *self)
*
* Sets the vertical alignment, from 0 (top) to 1 (bottom).
*
+ * This affects the children allocation during transitions, when they exceed the
+ * size of the squeezer.
+ *
+ * For example, 0.5 means the child will be centered, 0 means it will keep the
+ * top side aligned and overflow the bottom side, and 1 means the opposite.
+ *
* Since: 1.0
*/
void
diff --git a/src/adw-status-page.c b/src/adw-status-page.c
index 1c7daf03..5b1aa60b 100644
--- a/src/adw-status-page.c
+++ b/src/adw-status-page.c
@@ -194,7 +194,7 @@ adw_status_page_class_init (AdwStatusPageClass *klass)
*
* The name of the icon to be used.
*
- * Changing this will clear [property@StatusPage:paintable] out.
+ * Changing this will set [property@StatusPage:paintable] to `NULL`.
*
* Since: 1.0
*/
@@ -206,9 +206,9 @@ adw_status_page_class_init (AdwStatusPageClass *klass)
/**
* AdwStatusPage:paintable: (attributes org.gtk.Property.get=adw_status_page_get_paintable
org.gtk.Property.set=adw_status_page_set_paintable)
*
- * The @GdkPaintable to be used.
+ * The paintable to be used.
*
- * Changing this will clear [property@StatusPage:icon-name] out.
+ * Changing this will set [property@StatusPage:icon-name] to `NULL`.
*
* Since: 1.0
*/
@@ -341,6 +341,8 @@ adw_status_page_get_icon_name (AdwStatusPage *self)
*
* Sets the icon name for @self.
*
+ * Changing this will set [property@StatusPage:paintable] to `NULL`.
+ *
* Since: 1.0
*/
void
@@ -392,6 +394,8 @@ adw_status_page_get_paintable (AdwStatusPage *self)
*
* Sets the paintable for @self.
*
+ * Changing this will set [property@StatusPage:icon-name] to `NULL`.
+ *
* Since: 1.0
*/
void
@@ -443,6 +447,8 @@ adw_status_page_get_title (AdwStatusPage *self)
*
* Sets the title for @self.
*
+ * The title is displayed below the icon.
+ *
* Since: 1.0
*/
void
@@ -484,6 +490,8 @@ adw_status_page_get_description (AdwStatusPage *self)
*
* Sets the description for @self.
*
+ * The description is displayed below the title.
+ *
* Since: 1.0
*/
void
diff --git a/src/adw-style-manager.c b/src/adw-style-manager.c
index e7b4e446..1c896c0c 100644
--- a/src/adw-style-manager.c
+++ b/src/adw-style-manager.c
@@ -625,6 +625,31 @@ adw_style_manager_get_color_scheme (AdwStyleManager *self)
* [property@StyleManager:dark] property can be used to query the current
* effective appearance.
*
+ * The `ADW_COLOR_SCHEME_PREFER_LIGHT` color scheme results in the application
+ * using light appearance unless the system prefers dark colors. This is the
+ * default value.
+ *
+ * The `ADW_COLOR_SCHEME_PREFER_DARK` color scheme results in the application
+ * using dark appearance, but can still switch to the light appearance if the
+ * system can prefers it, for example, when the high contrast preference is
+ * enabled.
+ *
+ * The `ADW_COLOR_SCHEME_FORCE_LIGHT` and `ADW_COLOR_SCHEME_FORCE_DARK` values
+ * ignore the system preference entirely. They are useful if the application
+ * wants to match its UI to its content or to provide a separate color scheme
+ * switcher.
+ *
+ * If a per-[class@Gdk.Display] style manager has its color scheme set to
+ * `ADW_COLOR_SCHEME_DEFAULT`, it will inherit the color scheme from the
+ * default style manager.
+ *
+ * For the default style manager, `ADW_COLOR_SCHEME_DEFAULT` is equivalent to
+ * `ADW_COLOR_SCHEME_PREFER_LIGHT`.
+ *
+ * The [property@StyleManager:system-supports-color-schemes] property can be
+ * used to check if the current environment provides a color scheme
+ * preference.
+ *
* Since: 1.0
*/
void
@@ -664,6 +689,10 @@ adw_style_manager_set_color_scheme (AdwStyleManager *self,
*
* Gets whether the system supports color schemes.
*
+ * This can be used to check if the current environment provides a color scheme
+ * preference. For example, applications might want to show a separate
+ * appearance switcher if it's set to `FALSE`.
+ *
* Returns: whether the system supports color schemes
*
* Since: 1.0
@@ -682,6 +711,9 @@ adw_style_manager_get_system_supports_color_schemes (AdwStyleManager *self)
*
* Gets whether the application is using dark appearance.
*
+ * This can be used to query the current appearance, as requested via
+ * [property@StyleManager:color-scheme].
+ *
* Returns: whether the application is using dark appearance
*
* Since: 1.0
@@ -700,6 +732,8 @@ adw_style_manager_get_dark (AdwStyleManager *self)
*
* Gets whether the application is using high contrast appearance.
*
+ * This cannot be overridden by applications.
+ *
* Returns: whether the application is using high contrast appearance
*
* Since: 1.0
diff --git a/src/adw-swipe-tracker.c b/src/adw-swipe-tracker.c
index 66e42b6e..944b11e6 100644
--- a/src/adw-swipe-tracker.c
+++ b/src/adw-swipe-tracker.c
@@ -1251,6 +1251,9 @@ adw_swipe_tracker_get_enabled (AdwSwipeTracker *self)
*
* Sets whether @self is enabled.
*
+ * When it's not enabled, no events will be processed. Usually widgets will want
+ * to expose this via a property.
+ *
* Since: 1.0
*/
void
@@ -1299,6 +1302,9 @@ adw_swipe_tracker_get_reversed (AdwSwipeTracker *self)
*
* Sets whether to reverse the swipe direction.
*
+ * If the swipe tracker is horizontal, it can be used for supporting RTL text
+ * direction.
+ *
* Since: 1.0
*/
void
@@ -1386,6 +1392,9 @@ adw_swipe_tracker_get_allow_long_swipes (AdwSwipeTracker *self)
*
* Sets whether to allow swiping for more than one snap point at a time.
*
+ * If the value is `FALSE`, each swipe can only move to the adjacent snap
+ * points.
+ *
* Since: 1.0
*/
void
diff --git a/src/adw-tab-bar.c b/src/adw-tab-bar.c
index e891b98a..a117f8f4 100644
--- a/src/adw-tab-bar.c
+++ b/src/adw-tab-bar.c
@@ -858,6 +858,11 @@ adw_tab_bar_get_autohide (AdwTabBar *self)
*
* Sets whether the tabs automatically hide.
*
+ * If set to `TRUE`, the tab bar disappears when [property@TabBar:view] has 0
+ * or 1 tab, no pinned tabs, and no tab is being transferred.
+ *
+ * See [property@TabBar:tabs-revealed].
+ *
* Since: 1.0
*/
void
@@ -884,6 +889,8 @@ adw_tab_bar_set_autohide (AdwTabBar *self,
*
* Gets whether the tabs are currently revealed.
*
+ * See [property@TabBar:autohide].
+ *
* Returns: whether the tabs are currently revealed
*
* Since: 1.0
@@ -921,6 +928,9 @@ adw_tab_bar_get_expand_tabs (AdwTabBar *self)
*
* Sets whether tabs expand to full width.
*
+ * If set to `TRUE`, the tabs will always vary width filling the whole width
+ * when possible, otherwise tabs will always have the minimum possible size.
+ *
* Since: 1.0
*/
void
@@ -964,6 +974,9 @@ adw_tab_bar_get_inverted (AdwTabBar *self)
*
* Sets whether tabs tabs use inverted layout.
*
+ * If set to `TRUE`, non-pinned tabs will have the close button at the beginning
+ * and the indicator at the end rather than the opposite.
+ *
* Since: 1.0
*/
void
@@ -1023,6 +1036,8 @@ adw_tab_bar_setup_extra_drop_target (AdwTabBar *self,
*
* Gets whether @self is overflowing.
*
+ * If `TRUE`, all tabs cannot be displayed at once and require scrolling.
+ *
* Returns: whether @self is overflowing
*
* Since: 1.0
diff --git a/src/adw-tab-view.c b/src/adw-tab-view.c
index 9edba541..62f52537 100644
--- a/src/adw-tab-view.c
+++ b/src/adw-tab-view.c
@@ -1811,6 +1811,8 @@ adw_tab_page_get_child (AdwTabPage *self)
*
* Gets the parent page of @self.
*
+ * See [method@TabView.add_page] and [method@TabView.close_page].
+ *
* Returns: (transfer none) (nullable): the parent page
*
* Since: 1.0
@@ -1847,6 +1849,8 @@ adw_tab_page_get_selected (AdwTabPage *self)
*
* Gets whether @self is pinned.
*
+ * See [method@TabView.set_page_pinned].
+ *
* Returns: whether @self is pinned
*
* Since: 1.0
@@ -1882,6 +1886,9 @@ adw_tab_page_get_title (AdwTabPage *self)
* @self: a tab page
* @title: the title of @self
*
+ * [class@TabBar] will display it in the center of the tab unless it's pinned,
+ * and will use it as a tooltip unless [property@TabPage:tooltip] is set.
+ *
* Sets the title of @self.
*
* Since: 1.0
@@ -1926,6 +1933,11 @@ adw_tab_page_get_tooltip (AdwTabPage *self)
*
* Sets the tooltip of @self.
*
+ * The tooltip can be marked up with the Pango text markup language.
+ *
+ * If not set, [class@TabBar] will use [property@TabPage:title] as a tooltip
+ * instead.
+ *
* Since: 1.0
*/
void
@@ -1968,6 +1980,11 @@ adw_tab_page_get_icon (AdwTabPage *self)
*
* Sets the icon of @self.
*
+ * [class@TabBar] displays the icon next to the title.
+ *
+ * It will not show the icon if [property@TabPage:loading] is set to `TRUE`,
+ * or if the page is pinned and [propertyTabPage:indicator-icon] is set.
+ *
* Since: 1.0
*/
void
@@ -2010,6 +2027,11 @@ adw_tab_page_get_loading (AdwTabPage *self)
*
* Sets wether @self is loading.
*
+ * If set to `TRUE`, [class@TabBar] will display a spinner in place of icon.
+ *
+ * If the page is pinned and [property@TabPage:indicator-icon] is set, the
+ * loading status will not be visible.
+ *
* Since: 1.0
*/
void
@@ -2052,7 +2074,21 @@ adw_tab_page_get_indicator_icon (AdwTabPage *self)
* @indicator_icon: (nullable): the indicator icon of @self
*
* Sets the indicator icon of @self.
-
+ *
+ * A common use case is an audio or camera indicator in a web browser.
+ *
+ * [class@TabBar] will show it at the beginning of the tab, alongside icon
+ * representing [property@TabPage:icon] or loading spinner.
+ *
+ * If the page is pinned, the indicator will be shown instead of icon or
+ * spinner.
+ *
+ * [property@TabPage:indicator-tooltip] can be used to set the tooltip on the
+ * indicator icon.
+ *
+ * If [property@TabPage:indicator-activatable] is set to `TRUE`, the
+ * indicator icon can act as a button.
+ *
* Since: 1.0
*/
void
@@ -2143,6 +2179,11 @@ adw_tab_page_get_indicator_activatable (AdwTabPage *self)
*
* Sets whether the indicator of @self is activatable.
*
+ * If set to `TRUE`, [signal@TabView::indicator-activated] will be emitted
+ * when the indicator icon is clicked.
+ *
+ * If [property@TabPage:indicator-icon] is not set, does nothing.
+ *
* Since: 1.0
*/
void
@@ -2186,6 +2227,10 @@ adw_tab_page_get_needs_attention (AdwTabPage *self)
*
* Sets whether @self needs attention.
*
+ * [class@TabBar] will display a glow under the tab representing the page if
+ * set to `TRUE`. If the tab is not visible, the corresponding edge of the tab
+ * bar will be highlighted.
+ *
* Since: 1.0
*/
void
@@ -2243,6 +2288,8 @@ adw_tab_view_get_n_pages (AdwTabView *self)
*
* Gets the number of pinned pages in @self.
*
+ * See [method@TabView.set_page_pinned].
+ *
* Returns: the number of pinned pages in @self
*
* Since: 1.0
@@ -2261,6 +2308,12 @@ adw_tab_view_get_n_pinned_pages (AdwTabView *self)
*
* Whether a page is being transferred.
*
+ * The corresponding property will be set to `TRUE` when a drag-n-drop tab
+ * transfer starts on any `AdwTabView`, and to `FALSE` after it ends.
+ *
+ * During the transfer, children cannot receive pointer input and a tab can
+ * be safely dropped on the tab view.
+ *
* Returns: whether a page is being transferred
*
* Since: 1.0
@@ -2469,6 +2522,15 @@ adw_tab_view_get_default_icon (AdwTabView *self)
*
* Sets the default page icon for @self.
*
+ * If a page doesn't provide its own icon via [property@TabPage:icon], a default
+ * icon may be used instead for contexts where having an icon is necessary.
+ *
+ * [class@TabBar] will use default icon for pinned tabs in case the page is not
+ * loading, doesn't have an icon and an indicator. Default icon is never used
+ * for tabs that aren't pinned.
+ *
+ * By default, the `adw-tab-icon-missing-symbolic` icon is used.
+ *
* Since: 1.0
*/
void
@@ -2511,6 +2573,10 @@ adw_tab_view_get_menu_model (AdwTabView *self)
*
* Sets the tab context menu model for @self.
*
+ * When a context menu is shown for a tab, it will be constructed from the
+ * provided menu model. Use the [signal@TabView::setup-menu] signal to set up
+ * the menu actions for the particular tab.
+ *
* Since: 1.0
*/
void
diff --git a/src/adw-timed-animation.c b/src/adw-timed-animation.c
index 8344af2d..d6932dc9 100644
--- a/src/adw-timed-animation.c
+++ b/src/adw-timed-animation.c
@@ -399,6 +399,12 @@ adw_timed_animation_get_value_from (AdwTimedAnimation *self)
*
* Sets the value @self will animate from.
*
+ * The animation will start at this value and end at
+ * [property@TimedAnimation:value-to].
+ *
+ * If [property@TimedAnimation:reverse] is `TRUE`, the animation will end at
+ * this value instead.
+ *
* Since: 1.0
*/
void
@@ -440,6 +446,12 @@ adw_timed_animation_get_value_to (AdwTimedAnimation *self)
*
* Sets the value @self will animate to.
*
+ * The animation will start at [property@TimedAnimation:value-from] and end at
+ * this value.
+ *
+ * If [property@TimedAnimation:reverse] is `TRUE`, the animation will start
+ * at this value instead.
+ *
* Since: 1.0
*/
void
diff --git a/src/adw-toast.c b/src/adw-toast.c
index 8c59c65c..d4fb52f0 100644
--- a/src/adw-toast.c
+++ b/src/adw-toast.c
@@ -353,8 +353,6 @@ adw_toast_class_init (AdwToastClass *klass)
*
* The parameter for action invocations.
*
- * See [property@Toast:action-name].
- *
* Since: 1.0
*/
props[PROP_ACTION_TARGET] =
@@ -556,6 +554,12 @@ adw_toast_get_title (AdwToast *self)
*
* Sets the title that will be displayed on the toast.
*
+ * The title can be marked up with the Pango text markup language.
+ *
+ * Setting a title will unset [property@Toast:custom-title].
+ *
+ * If [property@Toast:custom-title] is set, it will be used instead.
+ *
* Since: 1.0
*/
void
@@ -605,7 +609,11 @@ adw_toast_get_button_label (AdwToast *self)
*
* Sets the label to show on the button.
*
- * It set to `NULL`, the button won't be shown.
+ * Underlines in the button text can be used to indicate a mnemonic.
+ *
+ * If set to `NULL`, the button won't be shown.
+ *
+ * See [property@Toast:action-name].
*
* Since: 1.0
*/
@@ -649,6 +657,10 @@ adw_toast_get_action_name (AdwToast *self)
*
* Sets the name of the associated action.
*
+ * It will be activated when clicking the button.
+ *
+ * See [property@Toast:action-target].
+ *
* Since: 1.0
*/
void
@@ -819,8 +831,8 @@ adw_toast_get_priority (AdwToast *self)
*
* If @priority is `ADW_TOAST_PRIORITY_NORMAL`, the toast will be queued.
*
- * If @priority is `ADW_TOAST_PRIORITY_HIGH`, the toast will be displayed immediately,
- * pushing the previous toast into the queue instead.
+ * If @priority is `ADW_TOAST_PRIORITY_HIGH`, the toast will be displayed
+ * immediately, pushing the previous toast into the queue instead.
*
* Since: 1.0
*/
@@ -916,6 +928,11 @@ adw_toast_dismiss (AdwToast *self)
*
* Sets the custom title widget of @self.
*
+ * It will be displayed instead of the title if set. In this case,
+ * [property@Toast:title] is ignored.
+ *
+ * Setting a custom title will unset [property@Toast:title].
+ *
* Since: 1.2
*/
void
diff --git a/src/adw-view-stack.c b/src/adw-view-stack.c
index 40c1e816..fe0b8cb8 100644
--- a/src/adw-view-stack.c
+++ b/src/adw-view-stack.c
@@ -255,7 +255,7 @@ adw_view_stack_page_class_init (AdwViewStackPageClass *class)
/**
* AdwViewStackPage:child: (attributes org.gtk.Property.get=adw_view_stack_page_get_child)
*
- * The child of the page.
+ * The stack child to which the page belongs.
*
* Since: 1.0
*/
@@ -317,7 +317,7 @@ adw_view_stack_page_class_init (AdwViewStackPageClass *class)
/**
* AdwViewStackPage:badge-number: (attributes org.gtk.Property.get=adw_view_stack_page_get_badge_number
org.gtk.Property.set=adw_view_stack_page_set_badge_number)
*
- * A number associated with the page.
+ * The badge number for this page.
*
* [class@ViewSwitcher] can display it as a badge next to the page icon. It is
* commonly used to display a number of unread items within the page.
@@ -898,7 +898,10 @@ adw_view_stack_class_init (AdwViewStackClass *klass)
/**
* AdwViewStack:hhomogeneous: (attributes org.gtk.Property.get=adw_view_stack_get_hhomogeneous
org.gtk.Property.set=adw_view_stack_set_hhomogeneous)
*
- * Whether the stack allocates the same width for all children.
+ * Whether the stack is horizontally homogeneous.
+ *
+ * If the stack is horizontally homogeneous, it allocates the same width for
+ * all children.
*
* If it's `FALSE`, the stack may change width when a different child becomes
* visible.
@@ -913,7 +916,10 @@ adw_view_stack_class_init (AdwViewStackClass *klass)
/**
* AdwViewStack:vhomogeneous: (attributes org.gtk.Property.get=adw_view_stack_get_vhomogeneous
org.gtk.Property.set=adw_view_stack_set_vhomogeneous)
*
- * Whether the stack allocates the same height for all children.
+ * Whether the stack is vertically homogeneous.
+ *
+ * If the stack is vertically homogeneous, it allocates the same height for
+ * all children.
*
* If it's `FALSE`, the stack may change height when a different child becomes
* visible.
@@ -1048,6 +1054,9 @@ adw_view_stack_page_get_visible (AdwViewStackPage *self)
*
* Sets whether @page is visible in its `AdwViewStack`.
*
+ * This is independent from the [property@Gtk.Widget:visible] property of
+ * [property@ViewStackPage:child].
+ *
* Since: 1.0
*/
void
@@ -1073,7 +1082,7 @@ adw_view_stack_page_set_visible (AdwViewStackPage *self,
* adw_view_stack_page_get_needs_attention: (attributes org.gtk.Method.get_property=needs-attention)
* @self: a view stack page
*
- * Gets whether the page is marked as “needs attention”.
+ * Gets whether the page requires the user attention.
*
* Returns: whether the page needs attention
*
@@ -1092,7 +1101,9 @@ adw_view_stack_page_get_needs_attention (AdwViewStackPage *self)
* @self: a view stack page
* @needs_attention: the new value to set
*
- * Sets whether the page is marked as “needs attention”.
+ * Sets whether the page requires the user attention.
+ *
+ * [class@ViewSwitcher] will display it as a dot next to the page icon.
*
* Since: 1.0
*/
@@ -1137,6 +1148,11 @@ adw_view_stack_page_get_badge_number (AdwViewStackPage *self)
*
* Sets the badge number for this page.
*
+ * [class@ViewSwitcher] can display it as a badge next to the page icon. It is
+ * commonly used to display a number of unread items within the page.
+ *
+ * It can be used together with [property@ViewStack{age}:needs-attention].
+ *
* Since: 1.0
*/
void
@@ -1615,6 +1631,8 @@ adw_view_stack_get_visible_child_name (AdwViewStack *self)
*
* Makes the child with @name visible.
*
+ * See [property@ViewStack:visible-child].
+ *
* Since: 1.0
*/
void
@@ -1647,6 +1665,12 @@ adw_view_stack_set_visible_child_name (AdwViewStack *self,
*
* Sets @self to be horizontally homogeneous or not.
*
+ * If the stack is horizontally homogeneous, it allocates the same width for
+ * all children.
+ *
+ * If it's `FALSE`, the stack may change width when a different child becomes
+ * visible.
+ *
* Since: 1.0
*/
void
@@ -1693,6 +1717,12 @@ adw_view_stack_get_hhomogeneous (AdwViewStack *self)
*
* Sets @self to be vertically homogeneous or not.
*
+ * If the stack is vertically homogeneous, it allocates the same height for
+ * all children.
+ *
+ * If it's `FALSE`, the stack may change height when a different child becomes
+ * visible.
+ *
* Since: 1.0
*/
void
diff --git a/src/adw-view-switcher-title.c b/src/adw-view-switcher-title.c
index f20ba291..254e2660 100644
--- a/src/adw-view-switcher-title.c
+++ b/src/adw-view-switcher-title.c
@@ -297,8 +297,8 @@ adw_view_switcher_title_class_init (AdwViewSwitcherTitleClass *klass)
*
* The title to display.
*
- * The title should give a user additional details. A good title should not
- * include the application name.
+ * The title typically identifies the current view or content item, and
+ * generally does not use the application name.
*
* Since: 1.0
*/
@@ -312,7 +312,7 @@ adw_view_switcher_title_class_init (AdwViewSwitcherTitleClass *klass)
*
* The subtitle to display.
*
- * The subtitle should give a user additional details.
+ * The subtitle should give the user additional details.
*
* Since: 1.0
*/
@@ -482,6 +482,9 @@ adw_view_switcher_title_get_title (AdwViewSwitcherTitle *self)
*
* Sets the title of @self.
*
+ * The title typically identifies the current view or content item, and
+ * generally does not use the application name.
+ *
* Since: 1.0
*/
void
@@ -523,6 +526,8 @@ adw_view_switcher_title_get_subtitle (AdwViewSwitcherTitle *self)
*
* Sets the subtitle of @self.
*
+ * The subtitle should give the user additional details.
+ *
* Since: 1.0
*/
void
@@ -564,6 +569,13 @@ adw_view_switcher_title_get_view_switcher_enabled (AdwViewSwitcherTitle *self)
*
* Sets whether @self's view switcher is enabled.
*
+ * If it is disabled, the title will be displayed instead. This allows to
+ * programmatically hide the view switcher even if it fits in the available
+ * space.
+ *
+ * This can be used e.g. to ensure the view switcher is hidden below a certain
+ * window width, or any other constraint you find suitable.
+ *
* Since: 1.0
*/
void
@@ -589,6 +601,9 @@ adw_view_switcher_title_set_view_switcher_enabled (AdwViewSwitcherTitle *self,
*
* Gets whether the title of @self is currently visible.
*
+ * If the title is visible, it means the view switcher is hidden an it may be
+ * wanted to show an alternative switcher, e.g. a [class@ViewSwitcherBar].
+ *
* Returns: whether the title of @self is currently visible
*
* Since: 1.0
diff --git a/src/adw-window-title.c b/src/adw-window-title.c
index 19e0047d..8b25f476 100644
--- a/src/adw-window-title.c
+++ b/src/adw-window-title.c
@@ -138,7 +138,7 @@ adw_window_title_class_init (AdwWindowTitleClass *klass)
*
* The subtitle to display.
*
- * The subtitle should give a user additional details.
+ * The subtitle should give the user additional details.
*
* Since: 1.0
*/
@@ -205,6 +205,9 @@ adw_window_title_get_title (AdwWindowTitle *self)
*
* Sets the title of @self.
*
+ * The title typically identifies the current view or content item, and
+ * generally does not use the application name.
+ *
* Since: 1.0
*/
void
@@ -248,6 +251,8 @@ adw_window_title_get_subtitle (AdwWindowTitle *self)
*
* Sets the subtitle of @self.
*
+ * The subtitle should give the user additional details.
+ *
* Since: 1.0
*/
void
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
