[gnome-shell] St Documentation: add and improve documentation for public classes
- From: Florian Müllner <fmuellner src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-shell] St Documentation: add and improve documentation for public classes
- Date: Sat, 8 Aug 2020 11:31:49 +0000 (UTC)
commit 9168f6055ea0b417f8beb64eefc18e5f904a9191
Author: Andy Holmes <andrew g r holmes gmail com>
Date: Wed May 20 16:50:09 2020 -0700
St Documentation: add and improve documentation for public classes
Much of St is undocumented, aside from input/output arguments. This is
no doubt because a lot of it parallels Gtk closely, but is worth
improving since many new programmers are not familiar with Gtk.
closes https://gitlab.gnome.org/GNOME/gnome-shell/-/issues/2983
src/st/st-adjustment.c | 204 +++++++++++++++++++++++++++++--
src/st/st-bin.c | 6 +-
src/st/st-border-image.c | 38 +++++-
src/st/st-box-layout.c | 8 +-
src/st/st-button.c | 49 ++++++--
src/st/st-button.h | 2 +-
src/st/st-clipboard.c | 13 +-
src/st/st-drawing-area.c | 31 +++--
src/st/st-entry.c | 116 +++++++++++++-----
src/st/st-focus-manager.c | 4 +-
src/st/st-generic-accessible.c | 18 ++-
src/st/st-icon-colors.c | 4 +-
src/st/st-icon.c | 37 +++++-
src/st/st-image-content.c | 5 +-
src/st/st-label.c | 30 +++--
src/st/st-password-entry.c | 31 ++++-
src/st/st-scroll-bar.c | 28 ++++-
src/st/st-scroll-view-fade.c | 24 ++++
src/st/st-scroll-view.c | 108 +++++++++++++++--
src/st/st-scrollable.c | 67 ++++++++++-
src/st/st-settings.c | 62 ++++++++--
src/st/st-shadow.c | 9 +-
src/st/st-texture-cache.c | 38 ++++--
src/st/st-theme-context.c | 28 +++--
src/st/st-theme-node.c | 264 +++++++++++++++++++++++++++++++++--------
src/st/st-theme-node.h | 63 ++++++++++
src/st/st-theme.c | 22 +++-
src/st/st-widget.c | 31 +++--
src/st/st-widget.h | 11 ++
29 files changed, 1149 insertions(+), 202 deletions(-)
---
diff --git a/src/st/st-adjustment.c b/src/st/st-adjustment.c
index eb170488f8..e08d0afc4c 100644
--- a/src/st/st-adjustment.c
+++ b/src/st/st-adjustment.c
@@ -279,11 +279,23 @@ st_adjustment_class_init (StAdjustmentClass *klass)
object_class->set_property = st_adjustment_set_property;
object_class->dispose = st_adjustment_dispose;
+ /**
+ * StAdjustment:actor:
+ *
+ * If the adjustment is used as #ClutterAnimatable for a
+ * #ClutterPropertyTransition, this property is used to determine which
+ * monitor should drive the animation.
+ */
props[PROP_ACTOR] =
g_param_spec_object ("actor", "Actor", "Actor",
CLUTTER_TYPE_ACTOR,
ST_PARAM_READWRITE);
+ /**
+ * StAdjustment:lower:
+ *
+ * The minimum value of the adjustment.
+ */
props[PROP_LOWER] =
g_param_spec_double ("lower", "Lower", "Lower bound",
-G_MAXDOUBLE, G_MAXDOUBLE, 0.0,
@@ -291,6 +303,14 @@ st_adjustment_class_init (StAdjustmentClass *klass)
G_PARAM_CONSTRUCT |
G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * StAdjustment:upper:
+ *
+ * The maximum value of the adjustment.
+ *
+ * Note that values will be restricted by `upper - page-size` if
+ * #StAdjustment:page-size is non-zero.
+ */
props[PROP_UPPER] =
g_param_spec_double ("upper", "Upper", "Upper bound",
-G_MAXDOUBLE, G_MAXDOUBLE, 0.0,
@@ -298,6 +318,11 @@ st_adjustment_class_init (StAdjustmentClass *klass)
G_PARAM_CONSTRUCT |
G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * StAdjustment:value:
+ *
+ * The value of the adjustment.
+ */
props[PROP_VALUE] =
g_param_spec_double ("value", "Value", "Current value",
-G_MAXDOUBLE, G_MAXDOUBLE, 0.0,
@@ -305,6 +330,11 @@ st_adjustment_class_init (StAdjustmentClass *klass)
G_PARAM_CONSTRUCT |
G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * StAdjustment:step-increment:
+ *
+ * The step increment of the adjustment.
+ */
props[PROP_STEP_INC] =
g_param_spec_double ("step-increment", "Step Increment", "Step increment",
0.0, G_MAXDOUBLE, 0.0,
@@ -312,6 +342,11 @@ st_adjustment_class_init (StAdjustmentClass *klass)
G_PARAM_CONSTRUCT |
G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * StAdjustment:page-increment:
+ *
+ * The page increment of the adjustment.
+ */
props[PROP_PAGE_INC] =
g_param_spec_double ("page-increment", "Page Increment", "Page increment",
0.0, G_MAXDOUBLE, 0.0,
@@ -319,6 +354,14 @@ st_adjustment_class_init (StAdjustmentClass *klass)
G_PARAM_CONSTRUCT |
G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * StAdjustment:page-size:
+ *
+ * The page size of the adjustment.
+ *
+ * Note that the page-size is irrelevant and should be set to zero if the
+ * adjustment is used for a simple scalar value.
+ */
props[PROP_PAGE_SIZE] =
g_param_spec_double ("page-size", "Page Size", "Page size",
0.0, G_MAXDOUBLE, 0.0,
@@ -350,6 +393,20 @@ st_adjustment_init (StAdjustment *self)
priv->is_constructing = TRUE;
}
+/**
+ * st_adjustment_new:
+ * @actor: (nullable): a #ClutterActor
+ * @value: the initial value
+ * @lower: the minimum value
+ * @upper: the maximum value
+ * @step_increment: the step increment
+ * @page_increment: the page increment
+ * @page_size: the page size
+ *
+ * Creates a new #StAdjustment
+ *
+ * Returns: a new #StAdjustment
+ */
StAdjustment *
st_adjustment_new (ClutterActor *actor,
gdouble value,
@@ -370,6 +427,14 @@ st_adjustment_new (ClutterActor *actor,
NULL);
}
+/**
+ * st_adjustment_get_value:
+ * @adjustment: a #StAdjustment
+ *
+ * Gets the current value of the adjustment. See st_adjustment_set_value().
+ *
+ * Returns: The current value of the adjustment
+ */
gdouble
st_adjustment_get_value (StAdjustment *adjustment)
{
@@ -378,6 +443,14 @@ st_adjustment_get_value (StAdjustment *adjustment)
return ((StAdjustmentPrivate *)st_adjustment_get_instance_private (adjustment))->value;
}
+/**
+ * st_adjustment_set_value:
+ * @adjustment: a #StAdjustment
+ * @value: the new value
+ *
+ * Sets the #StAdjustment value. The value is clamped to lie between
+ * #StAdjustment:lower and #StAdjustment:upper - #StAdjustment:page-size.
+ */
void
st_adjustment_set_value (StAdjustment *adjustment,
gdouble value)
@@ -404,6 +477,15 @@ st_adjustment_set_value (StAdjustment *adjustment,
}
}
+/**
+ * st_adjustment_clamp_page:
+ * @adjustment: a #StAdjustment
+ * @lower: the lower value
+ * @upper: the upper value
+ *
+ * Set #StAdjustment:value to a value clamped between @lower and @upper. The
+ * clamping described by st_adjustment_set_value() still applies.
+ */
void
st_adjustment_clamp_page (StAdjustment *adjustment,
gdouble lower,
@@ -437,6 +519,23 @@ st_adjustment_clamp_page (StAdjustment *adjustment,
g_object_notify_by_pspec (G_OBJECT (adjustment), props[PROP_VALUE]);
}
+/**
+ * st_adjustment_set_lower:
+ * @adjustment: a #StAdjustment
+ * @lower: the new minimum value
+ *
+ * Sets the minimum value of the adjustment.
+ *
+ * When setting multiple adjustment properties via their individual
+ * setters, multiple #GObject::notify and #StAdjustment::changed
+ * signals will be emitted. However, it’s possible to compress the
+ * #GObject::notify signals into one by calling
+ * g_object_freeze_notify() and g_object_thaw_notify() around the
+ * calls to the individual setters.
+ *
+ * Alternatively, using st_adjustment_set_values() will compress both
+ * #GObject::notify and #StAdjustment::changed emissions.
+ */
static gboolean
st_adjustment_set_lower (StAdjustment *adjustment,
gdouble lower)
@@ -461,6 +560,21 @@ st_adjustment_set_lower (StAdjustment *adjustment,
return FALSE;
}
+/**
+ * st_adjustment_set_upper:
+ * @adjustment: a #StAdjustment
+ * @upper: the new maximum value
+ *
+ * Sets the maximum value of the adjustment.
+ *
+ * Note that values will be restricted by `upper - page-size`
+ * if the page-size property is nonzero.
+ *
+ * See st_adjustment_set_lower() about how to compress multiple
+ * signal emissions when setting multiple adjustment properties.
+ *
+ * Returns: %TRUE if the value was changed
+ */
static gboolean
st_adjustment_set_upper (StAdjustment *adjustment,
gdouble upper)
@@ -485,6 +599,18 @@ st_adjustment_set_upper (StAdjustment *adjustment,
return FALSE;
}
+/**
+ * st_adjustment_set_step_increment:
+ * @adjustment: a #StAdjustment
+ * @step: the new step increment
+ *
+ * Sets the step increment of the adjustment.
+ *
+ * See st_adjustment_set_lower() about how to compress multiple
+ * signal emissions when setting multiple adjustment properties.
+ *
+ * Returns: %TRUE if the value was changed
+ */
static gboolean
st_adjustment_set_step_increment (StAdjustment *adjustment,
gdouble step)
@@ -505,6 +631,18 @@ st_adjustment_set_step_increment (StAdjustment *adjustment,
return FALSE;
}
+/**
+ * st_adjustment_set_page_increment:
+ * @adjustment: a #StAdjustment
+ * @page: the new page increment
+ *
+ * Sets the page increment of the adjustment.
+ *
+ * See st_adjustment_set_lower() about how to compress multiple
+ * signal emissions when setting multiple adjustment properties.
+ *
+ * Returns: %TRUE if the value was changed
+ */
static gboolean
st_adjustment_set_page_increment (StAdjustment *adjustment,
gdouble page)
@@ -525,6 +663,18 @@ st_adjustment_set_page_increment (StAdjustment *adjustment,
return FALSE;
}
+/**
+ * st_adjustment_set_page_size:
+ * @adjustment: a #StAdjustment
+ * @size: the new page size
+ *
+ * Sets the page size of the adjustment.
+ *
+ * See st_adjustment_set_lower() about how to compress multiple
+ * signal emissions when setting multiple adjustment properties.
+ *
+ * Returns: %TRUE if the value was changed
+ */
static gboolean
st_adjustment_set_page_size (StAdjustment *adjustment,
gdouble size)
@@ -549,6 +699,23 @@ st_adjustment_set_page_size (StAdjustment *adjustment,
return FALSE;
}
+/**
+ * st_adjustment_set_values:
+ * @adjustment: a #StAdjustment
+ * @value: the new value
+ * @lower: the new minimum value
+ * @upper: the new maximum value
+ * @step_increment: the new step increment
+ * @page_increment: the new page increment
+ * @page_size: the new page size
+ *
+ * Sets all properties of the adjustment at once.
+ *
+ * Use this function to avoid multiple emissions of the #GObject::notify and
+ * #StAdjustment::changed signals. See st_adjustment_set_lower() for an
+ * alternative way of compressing multiple emissions of #GObject::notify into
+ * one.
+ */
void
st_adjustment_set_values (StAdjustment *adjustment,
gdouble value,
@@ -593,12 +760,12 @@ st_adjustment_set_values (StAdjustment *adjustment,
/**
* st_adjustment_get_values:
* @adjustment: an #StAdjustment
- * @value: (out): the current value
- * @lower: (out): the lower bound
- * @upper: (out): the upper bound
- * @step_increment: (out): the step increment
- * @page_increment: (out): the page increment
- * @page_size: (out): the page size
+ * @value: (out) (optional): the current value
+ * @lower: (out) (optional): the lower bound
+ * @upper: (out) (optional): the upper bound
+ * @step_increment: (out) (optional): the step increment
+ * @page_increment: (out) (optional): the page increment
+ * @page_size: (out) (optional): the page size
*
* Gets all of @adjustment's values at once.
*/
@@ -722,7 +889,13 @@ on_transition_stopped (ClutterTransition *transition,
/**
* st_adjustment_get_transition:
- * Returns: (transfer none) (nullable):
+ * @adjustment: a #StAdjustment
+ * @name: a transition name
+ *
+ * Get the #ClutterTransition for @name previously added with
+ * st_adjustment_add_transition() or %NULL if not found.
+ *
+ * Returns: (transfer none) (nullable): a #ClutterTransition
*/
ClutterTransition *
st_adjustment_get_transition (StAdjustment *adjustment,
@@ -745,6 +918,15 @@ st_adjustment_get_transition (StAdjustment *adjustment,
return clos->transition;
}
+/**
+ * st_adjustment_add_transition:
+ * @adjustment: a #StAdjustment
+ * @name: a unique name for the transition
+ * @transtion: a #ClutterTransition
+ *
+ * Add a #ClutterTransition for the adjustment. If the transiton stops, it will
+ * be automatically removed if #ClutterTransition:remove-on-complete is %TRUE.
+ */
void
st_adjustment_add_transition (StAdjustment *adjustment,
const char *name,
@@ -785,6 +967,14 @@ st_adjustment_add_transition (StAdjustment *adjustment,
clutter_timeline_start (CLUTTER_TIMELINE (transition));
}
+/**
+ * st_adjusmtent_remove_transition:
+ * @adjusment: a #StAdjustment
+ * @name: the name of the transition to remove
+ *
+ * Remove a #ClutterTransition previously added by st_adjustment_add_transtion()
+ * with @name.
+ */
void
st_adjustment_remove_transition (StAdjustment *adjustment,
const char *name)
diff --git a/src/st/st-bin.c b/src/st/st-bin.c
index 4d7c705c31..2eadd57ed0 100644
--- a/src/st/st-bin.c
+++ b/src/st/st-bin.c
@@ -327,7 +327,7 @@ st_bin_init (StBin *bin)
*
* Creates a new #StBin, a simple container for one child.
*
- * Return value: the newly created #StBin actor
+ * Returns: the newly created #StBin actor
*/
StWidget *
st_bin_new (void)
@@ -378,9 +378,9 @@ st_bin_set_child (StBin *bin,
* st_bin_get_child:
* @bin: a #StBin
*
- * Retrieves a pointer to the child of @bin.
+ * Gets the #ClutterActor child for @bin.
*
- * Return value: (transfer none): a #ClutterActor, or %NULL
+ * Returns: (transfer none) (nullable): a #ClutterActor, or %NULL
*/
ClutterActor *
st_bin_get_child (StBin *bin)
diff --git a/src/st/st-border-image.c b/src/st/st-border-image.c
index d7bd03d305..ee09d02650 100644
--- a/src/st/st-border-image.c
+++ b/src/st/st-border-image.c
@@ -66,6 +66,19 @@ st_border_image_init (StBorderImage *image)
{
}
+/**
+ * st_border_image_new:
+ * @file: a #GFile
+ * @border_top: the top border
+ * @border_right: the right border
+ * @border_bottom: the bottom border
+ * @border_left: the left border
+ * @scale_factor: the scale factor
+ *
+ * Creates a new #StBorderImage.
+ *
+ * Returns: a new #StBorderImage.
+ */
StBorderImage *
st_border_image_new (GFile *file,
int border_top,
@@ -90,9 +103,11 @@ st_border_image_new (GFile *file,
/**
* st_border_image_get_file:
- * @image: a #StBorder_Image
+ * @image: a #StBorderImage
*
- * Returns: (transfer none): the #GFile for the #StBorder_Image
+ * Get the #GFile for @image.
+ *
+ * Returns: (transfer none): a #GFile
*/
GFile *
st_border_image_get_file (StBorderImage *image)
@@ -102,6 +117,17 @@ st_border_image_get_file (StBorderImage *image)
return image->file;
}
+/**
+ * st_border_image_get_border:
+ * @image: a #StBorderImage
+ * @border_top: (out) (optional): the top border
+ * @border_right: (out) (optional): the right border
+ * @border_bottom: (out) (optional): the bottom border
+ * @border_left: (out) (optional): the left border
+ *
+ * Get the border widths for @image, taking into account the scale factor
+ * provided at construction.
+ */
void
st_border_image_get_borders (StBorderImage *image,
int *border_top,
@@ -123,12 +149,12 @@ st_border_image_get_borders (StBorderImage *image,
/**
* st_border_image_equal:
- * @image: a #StBorder_Image
- * @other: a different #StBorder_Image
+ * @image: a #StBorderImage
+ * @other: a different #StBorderImage
*
- * Check if two border_image objects are identical.
+ * Check if two #StBorderImage objects are identical.
*
- * Return value: %TRUE if the two border image objects are identical
+ * Returns: %TRUE if the two border image objects are identical
*/
gboolean
st_border_image_equal (StBorderImage *image,
diff --git a/src/st/st-box-layout.c b/src/st/st-box-layout.c
index a31f727721..895e688acc 100644
--- a/src/st/st-box-layout.c
+++ b/src/st/st-box-layout.c
@@ -181,8 +181,8 @@ st_box_layout_class_init (StBoxLayoutClass *klass)
/**
* StBoxLayout:vertical:
*
- * A convenience property for getting the #ClutterBoxLayout:vertical
- * property of the layout for #StBoxLayout.
+ * A convenience property for the #ClutterBoxLayout:vertical property of the
+ * internal layout for #StBoxLayout.
*/
pspec = g_param_spec_boolean ("vertical",
"Vertical",
@@ -195,8 +195,8 @@ st_box_layout_class_init (StBoxLayoutClass *klass)
/**
* StBoxLayout:pack-start:
*
- * A convenience property for getting the #ClutterBoxLayout:pack-start
- * property of the layout for #StBoxLayout.
+ * A convenience property for the #ClutterBoxLayout:pack-start property of the
+ * internal layout for #StBoxLayout.
*/
pspec = g_param_spec_boolean ("pack-start",
"Pack Start",
diff --git a/src/st/st-button.c b/src/st/st-button.c
index c2c48a5101..0e440fa534 100644
--- a/src/st/st-button.c
+++ b/src/st/st-button.c
@@ -484,6 +484,11 @@ st_button_class_init (StButtonClass *klass)
widget_class->style_changed = st_button_style_changed;
widget_class->get_accessible_type = st_button_accessible_get_type;
+ /**
+ * StButton:label:
+ *
+ * The label of the #StButton.
+ */
props[PROP_LABEL] =
g_param_spec_string ("label",
"Label",
@@ -491,6 +496,11 @@ st_button_class_init (StButtonClass *klass)
NULL,
ST_PARAM_READWRITE);
+ /**
+ * StButton:button-mask:
+ *
+ * Which buttons will trigger the #StButton::clicked signal.
+ */
props[PROP_BUTTON_MASK] =
g_param_spec_flags ("button-mask",
"Button mask",
@@ -498,6 +508,11 @@ st_button_class_init (StButtonClass *klass)
ST_TYPE_BUTTON_MASK, ST_BUTTON_ONE,
ST_PARAM_READWRITE);
+ /**
+ * StButton:toggle-mode:
+ *
+ * Whether the #StButton is operating in toggle mode (on/off).
+ */
props[PROP_TOGGLE_MODE] =
g_param_spec_boolean ("toggle-mode",
"Toggle Mode",
@@ -505,6 +520,15 @@ st_button_class_init (StButtonClass *klass)
FALSE,
ST_PARAM_READWRITE);
+ /**
+ * StButton:checked:
+ *
+ * If #StButton:toggle-mode is %TRUE, indicates if the #StButton is toggled
+ * "on" or "off".
+ *
+ * When the value is %TRUE, the #StButton will have the `checked` CSS
+ * pseudo-class set.
+ */
props[PROP_CHECKED] =
g_param_spec_boolean ("checked",
"Checked",
@@ -512,6 +536,12 @@ st_button_class_init (StButtonClass *klass)
FALSE,
ST_PARAM_READWRITE);
+ /**
+ * StButton:pressed:
+ *
+ * In contrast to #StButton:checked, this property indicates whether the
+ * #StButton is being actively pressed, rather than just in the "on" state.
+ */
props[PROP_PRESSED] =
g_param_spec_boolean ("pressed",
"Pressed",
@@ -583,9 +613,10 @@ st_button_new_with_label (const gchar *text)
* st_button_get_label:
* @button: a #StButton
*
- * Get the text displayed on the button
+ * Get the text displayed on the button. If the label is empty, an empty string
+ * will be returned instead of %NULL.
*
- * Returns: the text for the button. This must not be freed by the application
+ * Returns: (transfer none): the text for the button
*/
const gchar *
st_button_get_label (StButton *button)
@@ -598,9 +629,9 @@ st_button_get_label (StButton *button)
/**
* st_button_set_label:
* @button: a #Stbutton
- * @text: text to set the label to
+ * @text: (nullable): text to set the label to
*
- * Sets the text displayed on the button
+ * Sets the text displayed on the button.
*/
void
st_button_set_label (StButton *button,
@@ -726,7 +757,7 @@ st_button_set_toggle_mode (StButton *button,
* st_button_get_checked:
* @button: a #StButton
*
- * Get the state of the button that is in toggle mode.
+ * Get the #StButton:checked property of a #StButton that is in toggle mode.
*
* Returns: %TRUE if the button is checked, or %FALSE if not
*/
@@ -743,8 +774,8 @@ st_button_get_checked (StButton *button)
* @button: a #Stbutton
* @checked: %TRUE or %FALSE
*
- * Sets the pressed state of the button. This is only really useful if the
- * button has #toggle-mode mode set to %TRUE.
+ * Set the #StButton:checked property of the button. This is only really useful
+ * if the button has #StButton:toggle-mode property set to %TRUE.
*/
void
st_button_set_checked (StButton *button,
@@ -773,9 +804,9 @@ st_button_set_checked (StButton *button,
* @button: an #StButton
*
* If this widget is holding a pointer grab, this function will
- * will ungrab it, and reset the pressed state. The effect is
+ * will ungrab it, and reset the #StButton:pressed state. The effect is
* similar to if the user had released the mouse button, but without
- * emitting the clicked signal.
+ * emitting the #StButton::clicked signal.
*
* This function is useful if for example you want to do something
* after the user is holding the mouse button for a given period of
diff --git a/src/st/st-button.h b/src/st/st-button.h
index df0d1ea0c5..6040e4182f 100644
--- a/src/st/st-button.h
+++ b/src/st/st-button.h
@@ -63,7 +63,7 @@ void st_button_fake_release (StButton *button);
* @ST_BUTTON_TWO: button 2 (middle)
* @ST_BUTTON_THREE: button 3 (right)
*
- * A mask representing which mouse buttons an StButton responds to.
+ * A mask representing which mouse buttons an #StButton responds to.
*/
typedef enum {
ST_BUTTON_ONE = (1 << 0),
diff --git a/src/st/st-clipboard.c b/src/st/st-clipboard.c
index 82ea802350..4673a7888a 100644
--- a/src/st/st-clipboard.c
+++ b/src/st/st-clipboard.c
@@ -195,7 +195,6 @@ st_clipboard_get_mimetypes (StClipboard *clipboard,
*
* Request the data from the clipboard in text form. @callback is executed
* when the data is retreived.
- *
*/
void
st_clipboard_get_text (StClipboard *clipboard,
@@ -244,7 +243,6 @@ st_clipboard_get_text (StClipboard *clipboard,
*
* Request the data from the clipboard in #GBytes form. @callback is executed
* when the data is retrieved.
- *
*/
void
st_clipboard_get_content (StClipboard *clipboard,
@@ -287,7 +285,9 @@ st_clipboard_get_content (StClipboard *clipboard,
* @mimetype: content mimetype
* @bytes: content data
*
- * Sets the clipboard content.
+ * Sets the clipboard content to @bytes.
+ *
+ * @mimetype is a semi-colon separated list of mime-type strings.
**/
void
st_clipboard_set_content (StClipboard *clipboard,
@@ -334,6 +334,13 @@ st_clipboard_set_text (StClipboard *clipboard,
g_bytes_unref (bytes);
}
+/**
+ * st_clipboard_set_selection: (skip)
+ *
+ * Sets the #MetaSelection of the default #StClipboard.
+ *
+ * This function is called during the initialization of GNOME Shell.
+ */
void
st_clipboard_set_selection (MetaSelection *selection)
{
diff --git a/src/st/st-drawing-area.c b/src/st/st-drawing-area.c
index 3f916e8a3b..1ab48c8785 100644
--- a/src/st/st-drawing-area.c
+++ b/src/st/st-drawing-area.c
@@ -150,8 +150,8 @@ st_drawing_area_init (StDrawingArea *area)
* st_drawing_area_queue_repaint:
* @area: the #StDrawingArea
*
- * Will cause the actor to emit a ::repaint signal before it is next
- * drawn to the scene. Useful if some parameters for the area being
+ * Will cause the actor to emit a #StDrawingArea::repaint signal before it is
+ * next drawn to the scene. Useful if some parameters for the area being
* drawn other than the size or style have changed. Note that
* clutter_actor_queue_redraw() will simply result in the same
* contents being drawn to the scene again.
@@ -169,9 +169,26 @@ st_drawing_area_queue_repaint (StDrawingArea *area)
* @area: the #StDrawingArea
*
* Gets the Cairo context to paint to. This function must only be called
- * from a signal hander for the ::repaint signal.
+ * from a signal hander or virtual function for the #StDrawingArea::repaint
+ * signal.
*
- * Return Value: (transfer none): the Cairo context for the paint operation
+ * JavaScript code must call the special dispose function before returning from
+ * the signal handler or virtual function to avoid leaking memory:
+ *
+ * |[<!-- language="JavaScript" -->
+ * function onRepaint(area) {
+ * let cr = area.get_context();
+ *
+ * // Draw to the context
+ *
+ * cr.$dispose();
+ * }
+ *
+ * let area = new St.DrawingArea();
+ * area.connect('repaint', onRepaint);
+ * ]|
+ *
+ * Returns: (transfer none): the Cairo context for the paint operation
*/
cairo_t *
st_drawing_area_get_context (StDrawingArea *area)
@@ -189,12 +206,12 @@ st_drawing_area_get_context (StDrawingArea *area)
/**
* st_drawing_area_get_surface_size:
* @area: the #StDrawingArea
- * @width: (out): location to store the width of the painted area
- * @height: (out): location to store the height of the painted area
+ * @width: (out) (optional): location to store the width of the painted area
+ * @height: (out) (optional): location to store the height of the painted area
*
* Gets the size of the cairo surface being painted to, which is equal
* to the size of the content area of the widget. This function must
- * only be called from a signal hander for the ::repaint signal.
+ * only be called from a signal hander for the #StDrawingArea::repaint signal.
*/
void
st_drawing_area_get_surface_size (StDrawingArea *area,
diff --git a/src/st/st-entry.c b/src/st/st-entry.c
index 10dfe1dd16..fdf0168c97 100644
--- a/src/st/st-entry.c
+++ b/src/st/st-entry.c
@@ -29,14 +29,9 @@
* applications to set further properties.
*
* #StEntry supports the following pseudo style states:
- * <itemizedlist>
- * <listitem>
- * <para>focus: the widget has focus</para>
- * </listitem>
- * <listitem>
- * <para>indeterminate: the widget is showing the hint text or actor</para>
- * </listitem>
- * </itemizedlist>
+ *
+ * - `focus`: the widget has focus
+ * - `indeterminate`: the widget is showing the hint text or actor
*/
#ifdef HAVE_CONFIG_H
@@ -897,6 +892,11 @@ st_entry_class_init (StEntryClass *klass)
widget_class->navigate_focus = st_entry_navigate_focus;
widget_class->get_accessible_type = st_entry_accessible_get_type;
+ /**
+ * StEntry:clutter-text:
+ *
+ * The internal #ClutterText actor supporting the #StEntry.
+ */
props[PROP_CLUTTER_TEXT] =
g_param_spec_object ("clutter-text",
"Clutter Text",
@@ -904,6 +904,11 @@ st_entry_class_init (StEntryClass *klass)
CLUTTER_TYPE_TEXT,
ST_PARAM_READABLE);
+ /**
+ * StEntry:primary-icon:
+ *
+ * The #ClutterActor acting as the primary icon at the start of the #StEntry.
+ */
props[PROP_PRIMARY_ICON] =
g_param_spec_object ("primary-icon",
"Primary Icon",
@@ -911,6 +916,11 @@ st_entry_class_init (StEntryClass *klass)
CLUTTER_TYPE_ACTOR,
ST_PARAM_READWRITE);
+ /**
+ * StEntry:secondary-icon:
+ *
+ * The #ClutterActor acting as the secondary icon at the end of the #StEntry.
+ */
props[PROP_SECONDARY_ICON] =
g_param_spec_object ("secondary-icon",
"Secondary Icon",
@@ -918,6 +928,12 @@ st_entry_class_init (StEntryClass *klass)
CLUTTER_TYPE_ACTOR,
ST_PARAM_READWRITE);
+ /**
+ * StEntry:hint-text:
+ *
+ * The text to display when the entry is empty and unfocused. Setting this
+ * will replace the actor of #StEntry::hint-actor.
+ */
props[PROP_HINT_TEXT] =
g_param_spec_string ("hint-text",
"Hint Text",
@@ -926,6 +942,12 @@ st_entry_class_init (StEntryClass *klass)
NULL,
ST_PARAM_READWRITE);
+ /**
+ * StEntry:hint-actor:
+ *
+ * A #ClutterActor to display when the entry is empty and unfocused. Setting
+ * this will replace the actor displaying #StEntry:hint-text.
+ */
props[PROP_HINT_ACTOR] =
g_param_spec_object ("hint-actor",
"Hint Actor",
@@ -934,6 +956,11 @@ st_entry_class_init (StEntryClass *klass)
CLUTTER_TYPE_ACTOR,
ST_PARAM_READWRITE);
+ /**
+ * StEntry:text:
+ *
+ * The current text value of the #StEntry.
+ */
props[PROP_TEXT] =
g_param_spec_string ("text",
"Text",
@@ -941,6 +968,12 @@ st_entry_class_init (StEntryClass *klass)
NULL,
ST_PARAM_READWRITE);
+ /**
+ * StEntry:input-purpose:
+ *
+ * The #ClutterInputContentPurpose that helps on-screen keyboards and similar
+ * input methods to decide which keys should be presented to the user.
+ */
props[PROP_INPUT_PURPOSE] =
g_param_spec_enum ("input-purpose",
"Purpose",
@@ -949,6 +982,13 @@ st_entry_class_init (StEntryClass *klass)
CLUTTER_INPUT_CONTENT_PURPOSE_NORMAL,
ST_PARAM_READWRITE);
+ /**
+ * StEntry:input-hints:
+ *
+ * The #ClutterInputContentHintFlags providing additional hints (beyond
+ * #StEntry:input-purpose) that allow input methods to fine-tune their
+ * behaviour.
+ */
props[PROP_INPUT_HINTS] =
g_param_spec_flags ("input-hints",
"hints",
@@ -964,8 +1004,7 @@ st_entry_class_init (StEntryClass *klass)
* StEntry::primary-icon-clicked:
* @self: the #StEntry
*
- *
- * Emitted when the primary icon is clicked
+ * Emitted when the primary icon is clicked.
*/
entry_signals[PRIMARY_ICON_CLICKED] =
g_signal_new ("primary-icon-clicked",
@@ -974,11 +1013,12 @@ st_entry_class_init (StEntryClass *klass)
G_STRUCT_OFFSET (StEntryClass, primary_icon_clicked),
NULL, NULL, NULL,
G_TYPE_NONE, 0);
+
/**
* StEntry::secondary-icon-clicked:
* @self: the #StEntry
*
- * Emitted when the secondary icon is clicked
+ * Emitted when the secondary icon is clicked.
*/
entry_signals[SECONDARY_ICON_CLICKED] =
g_signal_new ("secondary-icon-clicked",
@@ -1040,9 +1080,9 @@ st_entry_init (StEntry *entry)
/**
* st_entry_new:
- * @text: text to set the entry to
+ * @text: (nullable): text to set the entry to
*
- * Create a new #StEntry with the specified entry
+ * Create a new #StEntry with the specified text.
*
* Returns: a new #StEntry
*/
@@ -1063,9 +1103,10 @@ st_entry_new (const gchar *text)
* st_entry_get_text:
* @entry: a #StEntry
*
- * Get the text displayed on the entry
+ * Get the text displayed on the entry. If @entry is empty, an empty string will
+ * be returned instead of %NULL.
*
- * Returns: the text for the entry. This must not be freed by the application
+ * Returns: (transfer none): the text for the entry
*/
const gchar *
st_entry_get_text (StEntry *entry)
@@ -1084,7 +1125,8 @@ st_entry_get_text (StEntry *entry)
* @entry: a #StEntry
* @text: (nullable): text to set the entry to
*
- * Sets the text displayed on the entry
+ * Sets the text displayed on the entry. If @text is %NULL, the #ClutterText
+ * will instead be set to an empty string.
*/
void
st_entry_set_text (StEntry *entry,
@@ -1106,10 +1148,9 @@ st_entry_set_text (StEntry *entry,
* st_entry_get_clutter_text:
* @entry: a #StEntry
*
- * Retrieve the internal #ClutterText so that extra parameters can be set
+ * Retrieve the internal #ClutterText so that extra parameters can be set.
*
- * Returns: (transfer none): the #ClutterText used by #StEntry. The entry is
- * owned by the #StEntry and should not be unref'ed by the application.
+ * Returns: (transfer none): the #ClutterText used by @entry
*/
ClutterActor*
st_entry_get_clutter_text (StEntry *entry)
@@ -1125,8 +1166,8 @@ st_entry_get_clutter_text (StEntry *entry)
* @text: (nullable): text to set as the entry hint
*
* Sets the text to display when the entry is empty and unfocused. When the
- * entry is displaying the hint, it has a pseudo class of "indeterminate".
- * A value of NULL unsets the hint.
+ * entry is displaying the hint, it has a pseudo class of `indeterminate`.
+ * A value of %NULL unsets the hint.
*/
void
st_entry_set_hint_text (StEntry *entry,
@@ -1146,10 +1187,13 @@ st_entry_set_hint_text (StEntry *entry,
* st_entry_get_hint_text:
* @entry: a #StEntry
*
- * Gets the text that is displayed when the entry is empty and unfocused
+ * Gets the text that is displayed when the entry is empty and unfocused or
+ * %NULL if the #StEntry:hint-actor was set to an actor that is not a #StLabel.
*
- * Returns: the current value of the hint property. This string is owned by the
- * #StEntry and should not be freed or modified.
+ * Unlike st_entry_get_text() this function may return %NULL if
+ * #StEntry:hint-actor is not a #StLabel.
+ *
+ * Returns: (nullable) (transfer none): the current value of the hint property
*/
const gchar *
st_entry_get_hint_text (StEntry *entry)
@@ -1200,6 +1244,8 @@ st_entry_set_input_purpose (StEntry *entry,
* @entry: a #StEntry
*
* Gets the value of the #StEntry:input-purpose property.
+ *
+ * Returns: the input purpose of the entry
*/
ClutterInputContentPurpose
st_entry_get_input_purpose (StEntry *entry)
@@ -1245,6 +1291,8 @@ st_entry_set_input_hints (StEntry *entry,
* @entry: a #StEntry
*
* Gets the value of the #StEntry:input-hints property.
+ *
+ * Returns: the input hints for the entry
*/
ClutterInputContentHintFlags
st_entry_get_input_hints (StEntry *entry)
@@ -1305,7 +1353,7 @@ _st_entry_set_icon (StEntry *entry,
* @entry: a #StEntry
* @icon: (nullable): a #ClutterActor
*
- * Set the primary icon of the entry to @icon
+ * Set the primary icon of the entry to @icon.
*/
void
st_entry_set_primary_icon (StEntry *entry,
@@ -1324,7 +1372,9 @@ st_entry_set_primary_icon (StEntry *entry,
* st_entry_get_primary_icon:
* @entry: a #StEntry
*
- * Returns: (transfer none): a #ClutterActor
+ * Get the value of the #StEntry:primary-icon property.
+ *
+ * Returns: (nullable) (transfer none): a #ClutterActor
*/
ClutterActor *
st_entry_get_primary_icon (StEntry *entry)
@@ -1342,7 +1392,7 @@ st_entry_get_primary_icon (StEntry *entry)
* @entry: a #StEntry
* @icon: (nullable): an #ClutterActor
*
- * Set the secondary icon of the entry to @icon
+ * Set the secondary icon of the entry to @icon.
*/
void
st_entry_set_secondary_icon (StEntry *entry,
@@ -1361,7 +1411,9 @@ st_entry_set_secondary_icon (StEntry *entry,
* st_entry_get_secondary_icon:
* @entry: a #StEntry
*
- * Returns: (transfer none): a #ClutterActor
+ * Get the value of the #StEntry:secondary-icon property.
+ *
+ * Returns: (nullable) (transfer none): a #ClutterActor
*/
ClutterActor *
st_entry_get_secondary_icon (StEntry *entry)
@@ -1377,9 +1429,9 @@ st_entry_get_secondary_icon (StEntry *entry)
/**
* st_entry_set_hint_actor:
* @entry: a #StEntry
- * @hint_actor: (allow-none): a #ClutterActor
+ * @hint_actor: (nullable): a #ClutterActor
*
- * Set the hint actor of the entry to @hint_actor
+ * Set the hint actor of the entry to @hint_actor.
*/
void
st_entry_set_hint_actor (StEntry *entry,
@@ -1412,7 +1464,9 @@ st_entry_set_hint_actor (StEntry *entry,
* st_entry_get_hint_actor:
* @entry: a #StEntry
*
- * Returns: (transfer none): a #ClutterActor
+ * Get the value of the #StEntry:hint-actor property.
+ *
+ * Returns: (nullable) (transfer none): a #ClutterActor
*/
ClutterActor *
st_entry_get_hint_actor (StEntry *entry)
diff --git a/src/st/st-focus-manager.c b/src/st/st-focus-manager.c
index 0753d79029..1ac6d28b80 100644
--- a/src/st/st-focus-manager.c
+++ b/src/st/st-focus-manager.c
@@ -133,7 +133,7 @@ st_focus_manager_stage_event (ClutterActor *stage,
*
* Gets the #StFocusManager for @stage, creating it if necessary.
*
- * Return value: (transfer none): the focus manager for @stage
+ * Returns: (transfer none): the focus manager for @stage
*/
StFocusManager *
st_focus_manager_get_for_stage (ClutterStage *stage)
@@ -215,7 +215,7 @@ st_focus_manager_remove_group (StFocusManager *manager,
* Checks if @widget is inside a focus group, and if so, returns
* the root of that group.
*
- * Return value: (transfer none): the focus group root, or %NULL if
+ * Returns: (transfer none): the focus group root, or %NULL if
* @widget is not in a focus group
*/
StWidget *
diff --git a/src/st/st-generic-accessible.c b/src/st/st-generic-accessible.c
index 982e81433b..e6cb393d83 100644
--- a/src/st/st-generic-accessible.c
+++ b/src/st/st-generic-accessible.c
@@ -72,7 +72,7 @@ st_generic_accessible_class_init (StGenericAccessibleClass *klass)
* @self. Right now we only care about doubles, so the value is
* directly returned by the signal.
*
- * Return value: value of the current element.
+ * Returns: value of the current element.
*/
st_generic_accessible_signals[GET_CURRENT_VALUE] =
g_signal_new ("get-current-value",
@@ -90,7 +90,7 @@ st_generic_accessible_class_init (StGenericAccessibleClass *klass)
* @self. Right now we only care about doubles, so the value is
* directly returned by the signal.
*
- * Return value: maximum value of the accessible.
+ * Returns: maximum value of the accessible.
*/
st_generic_accessible_signals[GET_MAXIMUM_VALUE] =
g_signal_new ("get-maximum-value",
@@ -108,7 +108,7 @@ st_generic_accessible_class_init (StGenericAccessibleClass *klass)
* @self. Right now we only care about doubles, so the value is
* directly returned by the signal.
*
- * Return value: minimum value of the accessible.
+ * Returns: minimum value of the accessible.
*/
st_generic_accessible_signals[GET_MINIMUM_VALUE] =
g_signal_new ("get-minimum-value",
@@ -126,7 +126,7 @@ st_generic_accessible_class_init (StGenericAccessibleClass *klass)
* @self. Right now we only care about doubles, so the value is
* directly returned by the signal.
*
- * Return value: value of the current element.
+ * Returns: value of the current element.
*/
st_generic_accessible_signals[GET_MINIMUM_INCREMENT] =
g_signal_new ("get-minimum-increment",
@@ -221,6 +221,16 @@ atk_value_iface_init (AtkValueIface *iface)
iface->set_current_value = st_generic_accessible_set_current_value;
}
+/**
+ * st_generic_accessible_new_for_actor:
+ * @actor: a #Clutter Actor
+ *
+ * Create a new #StGenericAccessible for @actor.
+ *
+ * This is useful only for custom widgets that need a proxy for #AtkObject.
+ *
+ * Returns: (transfer full): a new #AtkObject
+ */
AtkObject*
st_generic_accessible_new_for_actor (ClutterActor *actor)
{
diff --git a/src/st/st-icon-colors.c b/src/st/st-icon-colors.c
index 8c5b8d35ab..f20a25c7ea 100644
--- a/src/st/st-icon-colors.c
+++ b/src/st/st-icon-colors.c
@@ -26,7 +26,7 @@
*
* Creates a new #StIconColors. All colors are initialized to transparent black.
*
- * Return value: a newly created #StIconColors. Free with st_icon_colors_unref()
+ * Returns: a newly created #StIconColors. Free with st_icon_colors_unref()
*/
StIconColors *
st_icon_colors_new (void)
@@ -107,6 +107,8 @@ st_icon_colors_copy (StIconColors *colors)
* @colors: a #StIconColors
* @other: another #StIconColors
*
+ * Check if two #StIconColors objects are identical.
+ *
* Returns: %TRUE if the #StIconColors are equal
*/
gboolean
diff --git a/src/st/st-icon.c b/src/st/st-icon.c
index d6a6c4c22a..f35cb96bb5 100644
--- a/src/st/st-icon.c
+++ b/src/st/st-icon.c
@@ -255,6 +255,11 @@ st_icon_class_init (StIconClass *klass)
widget_class->style_changed = st_icon_style_changed;
actor_class->resource_scale_changed = st_icon_resource_scale_changed;
+ /**
+ * StIcon:gicon:
+ *
+ * The #GIcon being displayed by this #StIcon.
+ */
props[PROP_GICON] =
g_param_spec_object ("gicon",
"GIcon",
@@ -262,6 +267,11 @@ st_icon_class_init (StIconClass *klass)
G_TYPE_ICON,
ST_PARAM_READWRITE);
+ /**
+ * StIcon:fallback-gicon:
+ *
+ * The fallback #GIcon to display if #StIcon:gicon fails to load.
+ */
props[PROP_FALLBACK_GICON] =
g_param_spec_object ("fallback-gicon",
"Fallback GIcon",
@@ -269,6 +279,11 @@ st_icon_class_init (StIconClass *klass)
G_TYPE_ICON,
ST_PARAM_READWRITE);
+ /**
+ * StIcon:icon-name:
+ *
+ * The name of the icon if the icon being displayed is a #GThemedIcon.
+ */
props[PROP_ICON_NAME] =
g_param_spec_string ("icon-name",
"Icon name",
@@ -276,6 +291,12 @@ st_icon_class_init (StIconClass *klass)
NULL,
ST_PARAM_READWRITE);
+ /**
+ * StIcon:icon-size:
+ *
+ * The size of the icon, if greater than `0`. Other the icon sise is derived
+ * from the current style.
+ */
props[PROP_ICON_SIZE] =
g_param_spec_int ("icon-size",
"Icon size",
@@ -283,6 +304,12 @@ st_icon_class_init (StIconClass *klass)
-1, G_MAXINT, -1,
ST_PARAM_READWRITE);
+ /**
+ * StIcon:fallback-icon-name:
+ *
+ * The fallback icon name of the #StIcon. See st_icon_set_fallback_icon_name()
+ * for details.
+ */
props[PROP_FALLBACK_ICON_NAME] =
g_param_spec_string ("fallback-icon-name",
"Fallback icon name",
@@ -524,7 +551,7 @@ st_icon_update_icon_size (StIcon *icon)
/**
* st_icon_new:
*
- * Create a newly allocated #StIcon
+ * Create a newly allocated #StIcon.
*
* Returns: A newly allocated #StIcon
*/
@@ -538,10 +565,10 @@ st_icon_new (void)
* st_icon_get_icon_name:
* @icon: an #StIcon
*
- * This is a convenience method to get the icon name of the #GThemedIcon that
- * is currently set.
+ * This is a convenience method to get the icon name of the current icon, if it
+ * is currenyly a #GThemedIcon, or %NULL otherwise.
*
- * Returns: (transfer none): The name of the icon or %NULL if no icon is set
+ * Returns: (transfer none) (nullable): The name of the icon or %NULL
*/
const gchar *
st_icon_get_icon_name (StIcon *icon)
@@ -592,7 +619,7 @@ st_icon_set_icon_name (StIcon *icon,
*
* Gets the current #GIcon in use.
*
- * Returns: (transfer none): The current #GIcon, if set, otherwise %NULL
+ * Returns: (nullable) (transfer none): The current #GIcon, if set, otherwise %NULL
*/
GIcon *
st_icon_get_gicon (StIcon *icon)
diff --git a/src/st/st-image-content.c b/src/st/st-image-content.c
index 84f4918c7b..92f1c14156 100644
--- a/src/st/st-image-content.c
+++ b/src/st/st-image-content.c
@@ -329,7 +329,10 @@ g_loadable_icon_interface_init (GLoadableIconIface *iface)
*
* Creates a new #StImageContent, a simple content for sized images.
*
- * Return value: (transfer full): the newly created #StImageContent content
+ * See #ClutterImage for setting the actual image to display or #StIcon for
+ * displaying icons.
+ *
+ * Returns: (transfer full): the newly created #StImageContent content
* Use g_object_unref() when done.
*/
ClutterContent *
diff --git a/src/st/st-label.c b/src/st/st-label.c
index 9c4ad31d43..54f16b1550 100644
--- a/src/st/st-label.c
+++ b/src/st/st-label.c
@@ -274,6 +274,11 @@ st_label_class_init (StLabelClass *klass)
widget_class->style_changed = st_label_style_changed;
widget_class->get_accessible_type = st_label_accessible_get_type;
+ /**
+ * StLabel:clutter-text:
+ *
+ * The internal #ClutterText actor supporting the label
+ */
props[PROP_CLUTTER_TEXT] =
g_param_spec_object ("clutter-text",
"Clutter Text",
@@ -281,6 +286,11 @@ st_label_class_init (StLabelClass *klass)
CLUTTER_TYPE_TEXT,
ST_PARAM_READABLE);
+ /**
+ * StLabel:text:
+ *
+ * The current text being display in the #StLabel.
+ */
props[PROP_TEXT] =
g_param_spec_string ("text",
"Text",
@@ -314,9 +324,9 @@ st_label_init (StLabel *label)
/**
* st_label_new:
- * @text: text to set the label to
+ * @text: (nullable): text to set the label to
*
- * Create a new #StLabel with the specified label
+ * Create a new #StLabel with the label specified by @text.
*
* Returns: a new #StLabel
*/
@@ -335,9 +345,10 @@ st_label_new (const gchar *text)
* st_label_get_text:
* @label: a #StLabel
*
- * Get the text displayed on the label
+ * Get the text displayed on the label.
*
- * Returns: the text for the label. This must not be freed by the application
+ * Returns: (transfer none): the text for the label. This must not be freed by
+ * the application
*/
const gchar *
st_label_get_text (StLabel *label)
@@ -350,9 +361,9 @@ st_label_get_text (StLabel *label)
/**
* st_label_set_text:
* @label: a #StLabel
- * @text: text to set the label to
+ * @text: (nullable): text to set the label to
*
- * Sets the text displayed on the label
+ * Sets the text displayed by the label.
*/
void
st_label_set_text (StLabel *label,
@@ -382,10 +393,11 @@ st_label_set_text (StLabel *label,
* st_label_get_clutter_text:
* @label: a #StLabel
*
- * Retrieve the internal #ClutterText so that extra parameters can be set
+ * Retrieve the internal #ClutterText used by @label so that extra parameters
+ * can be set.
*
- * Returns: (transfer none): ethe #ClutterText used by #StLabel. The label
- * is owned by the #StLabel and should not be unref'ed by the application.
+ * Returns: (transfer none): the #ClutterText used by #StLabel. The actor
+ * is owned by the #StLabel and should not be destroyed by the application.
*/
ClutterActor*
st_label_get_clutter_text (StLabel *label)
diff --git a/src/st/st-password-entry.c b/src/st/st-password-entry.c
index 7c240a5252..80df97955d 100644
--- a/src/st/st-password-entry.c
+++ b/src/st/st-password-entry.c
@@ -133,12 +133,23 @@ st_password_entry_class_init (StPasswordEntryClass *klass)
st_entry_class->secondary_icon_clicked = st_password_entry_secondary_icon_clicked;
+ /**
+ * StPasswordEntry:password-visible:
+ *
+ * Whether the text in the entry is masked for privacy.
+ */
props[PROP_PASSWORD_VISIBLE] = g_param_spec_boolean ("password-visible",
"Password visible",
- "Whether to text in the entry is masked or not",
+ "Whether the text in the entry is masked or not",
FALSE,
ST_PARAM_READWRITE);
+ /**
+ * StPasswordEntry:show-peek-icon:
+ *
+ * Whether to display an icon button to toggle the masking enabled by the
+ * #StPasswordEntry:password-visible property.
+ */
props[PROP_SHOW_PEEK_ICON] = g_param_spec_boolean ("show-peek-icon",
"Show peek icon",
"Whether to show the password peek icon",
@@ -202,12 +213,15 @@ st_password_entry_new (void)
/**
* st_password_entry_set_show_peek_icon:
* @entry: a #StPasswordEntry
- * @value: #TRUE to show the peek-icon in the entry, #FALSE otherwise
+ * @value: %TRUE to show the peek-icon in the entry
*
- * Sets whether to show or hide the peek-icon in the password entry.
+ * Sets whether to show or hide the peek-icon in the password entry. If %TRUE,
+ * a icon button for temporarily unmasking the password will be shown at the
+ * end of the entry.
*/
void
-st_password_entry_set_show_peek_icon (StPasswordEntry *entry, gboolean value)
+st_password_entry_set_show_peek_icon (StPasswordEntry *entry,
+ gboolean value)
{
StPasswordEntryPrivate *priv;
@@ -231,6 +245,8 @@ st_password_entry_set_show_peek_icon (StPasswordEntry *entry, gboolean value)
* @entry: a #StPasswordEntry
*
* Gets whether peek-icon is shown or hidden in the password entry.
+ *
+ * Returns: %TRUE if visible
*/
gboolean
st_password_entry_get_show_peek_icon (StPasswordEntry *entry)
@@ -246,12 +262,13 @@ st_password_entry_get_show_peek_icon (StPasswordEntry *entry)
/**
* st_password_entry_set_password_visible:
* @entry: a #StPasswordEntry
- * @value: #TRUE to show the password in the entry, #FALSE otherwise
+ * @value: %TRUE to show the password in the entry, #FALSE otherwise
*
* Sets whether to show or hide text in the password entry.
*/
void
-st_password_entry_set_password_visible (StPasswordEntry *entry, gboolean value)
+st_password_entry_set_password_visible (StPasswordEntry *entry,
+ gboolean value)
{
StPasswordEntryPrivate *priv;
ClutterActor *clutter_text;
@@ -284,6 +301,8 @@ st_password_entry_set_password_visible (StPasswordEntry *entry, gboolean value)
* @entry: a #StPasswordEntry
*
* Gets whether the text is masked in the password entry.
+ *
+ * Returns: %TRUE if visible
*/
gboolean
st_password_entry_get_password_visible (StPasswordEntry *entry)
diff --git a/src/st/st-scroll-bar.c b/src/st/st-scroll-bar.c
index 0bc4769a50..59e9ca8207 100644
--- a/src/st/st-scroll-bar.c
+++ b/src/st/st-scroll-bar.c
@@ -538,11 +538,21 @@ st_scroll_bar_class_init (StScrollBarClass *klass)
widget_class->style_changed = st_scroll_bar_style_changed;
+ /**
+ * StScrollBar:adjustment:
+ *
+ * The #StAdjustment controlling the #StScrollBar.
+ */
props[PROP_ADJUSTMENT] =
g_param_spec_object ("adjustment", "Adjustment", "The adjustment",
ST_TYPE_ADJUSTMENT,
ST_PARAM_READWRITE);
+ /**
+ * StScrollBar:vertical:
+ *
+ * Whether the #StScrollBar is vertical. If %FALSE it is horizontal.
+ */
props[PROP_VERTICAL] =
g_param_spec_boolean ("vertical",
"Vertical Orientation",
@@ -552,6 +562,13 @@ st_scroll_bar_class_init (StScrollBarClass *klass)
g_object_class_install_properties (object_class, N_PROPS, props);
+
+ /**
+ * StScrollBar::scroll-start:
+ * @bar: a #StScrollBar
+ *
+ * Emitted when the #StScrollBar begins scrolling.
+ */
signals[SCROLL_START] =
g_signal_new ("scroll-start",
G_TYPE_FROM_CLASS (klass),
@@ -560,6 +577,12 @@ st_scroll_bar_class_init (StScrollBarClass *klass)
NULL, NULL, NULL,
G_TYPE_NONE, 0);
+ /**
+ * StScrollBar::scroll-stop:
+ * @bar: a #StScrollBar
+ *
+ * Emitted when the #StScrollBar finishes scrolling.
+ */
signals[SCROLL_STOP] =
g_signal_new ("scroll-stop",
G_TYPE_FROM_CLASS (klass),
@@ -982,10 +1005,9 @@ st_scroll_bar_set_adjustment (StScrollBar *bar,
* st_scroll_bar_get_adjustment:
* @bar: a #StScrollbar
*
- * Gets the adjustment object that stores the current position
- * of the scrollbar.
+ * Gets the #StAdjustment that controls the current position of @bar.
*
- * Return value: (transfer none): the adjustment
+ * Returns: (transfer none): an #StAdjustment
*/
StAdjustment *
st_scroll_bar_get_adjustment (StScrollBar *bar)
diff --git a/src/st/st-scroll-view-fade.c b/src/st/st-scroll-view-fade.c
index 656fa322fe..30b5a4c79f 100644
--- a/src/st/st-scroll-view-fade.c
+++ b/src/st/st-scroll-view-fade.c
@@ -389,6 +389,12 @@ st_scroll_view_fade_class_init (StScrollViewFadeClass *klass)
offscreen_class->create_texture = st_scroll_view_fade_create_texture;
offscreen_class->paint_target = st_scroll_view_fade_paint_target;
+ /**
+ * StScrollViewFade:vfade-offset:
+ *
+ * The height of area which is faded at the top and bottom edges of the
+ * #StScrollViewFade.
+ */
props[PROP_VFADE_OFFSET] =
g_param_spec_float ("vfade-offset",
"Vertical Fade Offset",
@@ -396,6 +402,12 @@ st_scroll_view_fade_class_init (StScrollViewFadeClass *klass)
0.f, G_MAXFLOAT, DEFAULT_FADE_OFFSET,
ST_PARAM_READWRITE);
+ /**
+ * StScrollViewFade:hfade-offset:
+ *
+ * The height of area which is faded at the left and right edges of the
+ * #StScrollViewFade.
+ */
props[PROP_HFADE_OFFSET] =
g_param_spec_float ("hfade-offset",
"Horizontal Fade Offset",
@@ -403,6 +415,11 @@ st_scroll_view_fade_class_init (StScrollViewFadeClass *klass)
0.f, G_MAXFLOAT, DEFAULT_FADE_OFFSET,
ST_PARAM_READWRITE);
+ /**
+ * StScrollViewFade:fade-edges:
+ *
+ * Whether the faded area should extend to the edges of the #StScrollViewFade.
+ */
props[PROP_FADE_EDGES] =
g_param_spec_boolean ("fade-edges",
"Fade Edges",
@@ -420,6 +437,13 @@ st_scroll_view_fade_init (StScrollViewFade *self)
self->hfade_offset = DEFAULT_FADE_OFFSET;
}
+/**
+ * st_scroll_view_fade_new:
+ *
+ * Create a new #StScrollViewFade.
+ *
+ * Returns: (transfer full): a new #StScrollViewFade
+ */
ClutterEffect *
st_scroll_view_fade_new (void)
{
diff --git a/src/st/st-scroll-view.c b/src/st/st-scroll-view.c
index 349c8c8409..6af6a95190 100644
--- a/src/st/st-scroll-view.c
+++ b/src/st/st-scroll-view.c
@@ -172,8 +172,8 @@ st_scroll_view_get_property (GObject *object,
*/
void
st_scroll_view_update_fade_effect (StScrollView *scroll,
- float vfade_offset,
- float hfade_offset)
+ float vfade_offset,
+ float hfade_offset)
{
StScrollViewPrivate *priv = ST_SCROLL_VIEW (scroll)->priv;
@@ -830,6 +830,11 @@ st_scroll_view_class_init (StScrollViewClass *klass)
widget_class->style_changed = st_scroll_view_style_changed;
+ /**
+ * StScrollView:hscroll:
+ *
+ * The horizontal #StScrollBar for the #StScrollView.
+ */
props[PROP_HSCROLL] =
g_param_spec_object ("hscroll",
"StScrollBar",
@@ -837,6 +842,11 @@ st_scroll_view_class_init (StScrollViewClass *klass)
ST_TYPE_SCROLL_BAR,
ST_PARAM_READABLE);
+ /**
+ * StScrollView:vscroll:
+ *
+ * The vertical #StScrollBar for the #StScrollView.
+ */
props[PROP_VSCROLL] =
g_param_spec_object ("vscroll",
"StScrollBar",
@@ -844,6 +854,11 @@ st_scroll_view_class_init (StScrollViewClass *klass)
ST_TYPE_SCROLL_BAR,
ST_PARAM_READABLE);
+ /**
+ * StScrollView:vscrollbar-policy:
+ *
+ * The #StPolicyType for when to show the vertical #StScrollBar.
+ */
props[PROP_VSCROLLBAR_POLICY] =
g_param_spec_enum ("vscrollbar-policy",
"Vertical Scrollbar Policy",
@@ -852,6 +867,11 @@ st_scroll_view_class_init (StScrollViewClass *klass)
ST_POLICY_AUTOMATIC,
ST_PARAM_READWRITE);
+ /**
+ * StScrollView:hscrollbar-policy:
+ *
+ * The #StPolicyType for when to show the horizontal #StScrollBar.
+ */
props[PROP_HSCROLLBAR_POLICY] =
g_param_spec_enum ("hscrollbar-policy",
"Horizontal Scrollbar Policy",
@@ -860,6 +880,11 @@ st_scroll_view_class_init (StScrollViewClass *klass)
ST_POLICY_AUTOMATIC,
ST_PARAM_READWRITE);
+ /**
+ * StScrollView:hscrollbar-visible:
+ *
+ * Whether the horizontal #StScrollBar is visible.
+ */
props[PROP_HSCROLLBAR_VISIBLE] =
g_param_spec_boolean ("hscrollbar-visible",
"Horizontal Scrollbar Visibility",
@@ -867,6 +892,11 @@ st_scroll_view_class_init (StScrollViewClass *klass)
TRUE,
ST_PARAM_READABLE);
+ /**
+ * StScrollView:vscrollbar-visible:
+ *
+ * Whether the vertical #StScrollBar is visible.
+ */
props[PROP_VSCROLLBAR_VISIBLE] =
g_param_spec_boolean ("vscrollbar-visible",
"Vertical Scrollbar Visibility",
@@ -874,6 +904,11 @@ st_scroll_view_class_init (StScrollViewClass *klass)
TRUE,
ST_PARAM_READABLE);
+ /**
+ * StScrollView:enable-mouse-scrolling:
+ *
+ * Whether to enable automatic mouse wheel scrolling.
+ */
props[PROP_MOUSE_SCROLL] =
g_param_spec_boolean ("enable-mouse-scrolling",
"Enable Mouse Scrolling",
@@ -881,6 +916,11 @@ st_scroll_view_class_init (StScrollViewClass *klass)
TRUE,
ST_PARAM_READWRITE);
+ /**
+ * StScrollView:overlay-scrollbars:
+ *
+ * Whether scrollbars are painted on top of the content.
+ */
props[PROP_OVERLAY_SCROLLBARS] =
g_param_spec_boolean ("overlay-scrollbars",
"Use Overlay Scrollbars",
@@ -995,6 +1035,13 @@ clutter_container_iface_init (ClutterContainerIface *iface)
iface->remove = st_scroll_view_remove;
}
+/**
+ * st_scroll_view_new:
+ *
+ * Create a new #StScrollView.
+ *
+ * Returns: (transfer full): a new #StScrollView
+ */
StWidget *
st_scroll_view_new (void)
{
@@ -1005,9 +1052,9 @@ st_scroll_view_new (void)
* st_scroll_view_get_hscroll_bar:
* @scroll: a #StScrollView
*
- * Gets the horizontal scrollbar of the scrollbiew
+ * Gets the horizontal #StScrollBar of the #StScrollView.
*
- * Return value: (transfer none): the horizontal #StScrollBar
+ * Returns: (transfer none): the horizontal scrollbar
*/
ClutterActor *
st_scroll_view_get_hscroll_bar (StScrollView *scroll)
@@ -1021,9 +1068,9 @@ st_scroll_view_get_hscroll_bar (StScrollView *scroll)
* st_scroll_view_get_vscroll_bar:
* @scroll: a #StScrollView
*
- * Gets the vertical scrollbar of the scrollbiew
+ * Gets the vertical scrollbar of the #StScrollView.
*
- * Return value: (transfer none): the vertical #StScrollBar
+ * Returns: (transfer none): the vertical #StScrollBar
*/
ClutterActor *
st_scroll_view_get_vscroll_bar (StScrollView *scroll)
@@ -1033,6 +1080,14 @@ st_scroll_view_get_vscroll_bar (StScrollView *scroll)
return scroll->priv->vscroll;
}
+/**
+ * st_scroll_view_get_column_size:
+ * @scroll: a #StScrollView
+ *
+ * Get the step increment of the horizontal plane.
+ *
+ * Returns: the horizontal step increment
+ */
gfloat
st_scroll_view_get_column_size (StScrollView *scroll)
{
@@ -1047,6 +1102,13 @@ st_scroll_view_get_column_size (StScrollView *scroll)
return column_size;
}
+/**
+ * st_scroll_view_set_column_size:
+ * @scroll: a #StScrollView
+ * @column_size: horizontal step increment
+ *
+ * Set the step increment of the horizontal plane to @column_size.
+ */
void
st_scroll_view_set_column_size (StScrollView *scroll,
gfloat column_size)
@@ -1069,6 +1131,14 @@ st_scroll_view_set_column_size (StScrollView *scroll,
}
}
+/**
+ * st_scroll_view_get_row_size:
+ * @scroll: a #StScrollView
+ *
+ * Get the step increment of the vertical plane.
+ *
+ * Returns: the vertical step increment
+ */
gfloat
st_scroll_view_get_row_size (StScrollView *scroll)
{
@@ -1083,6 +1153,13 @@ st_scroll_view_get_row_size (StScrollView *scroll)
return row_size;
}
+/**
+ * st_scroll_view_set_row_size:
+ * @scroll: a #StScrollView
+ * @row_size: vertical step increment
+ *
+ * Set the step increment of the vertical plane to @row_size.
+ */
void
st_scroll_view_set_row_size (StScrollView *scroll,
gfloat row_size)
@@ -1105,6 +1182,13 @@ st_scroll_view_set_row_size (StScrollView *scroll,
}
}
+/**
+ * st_scroll_view_set_mouse_scrolling:
+ * @scroll: a #StScrollView
+ * @enabled: %TRUE or %FALSE
+ *
+ * Sets automatic mouse wheel scrolling to enabled or disabled.
+ */
void
st_scroll_view_set_mouse_scrolling (StScrollView *scroll,
gboolean enabled)
@@ -1125,6 +1209,14 @@ st_scroll_view_set_mouse_scrolling (StScrollView *scroll,
}
}
+/**
+ * st_scroll_view_get_mouse_scrolling:
+ * @scroll: a #StScrollView
+ *
+ * Get whether automatic mouse wheel scrolling is enabled or disabled.
+ *
+ * Returns: %TRUE if enabled, %FALSE otherwise
+ */
gboolean
st_scroll_view_get_mouse_scrolling (StScrollView *scroll)
{
@@ -1167,7 +1259,9 @@ st_scroll_view_set_overlay_scrollbars (StScrollView *scroll,
* st_scroll_view_get_overlay_scrollbars:
* @scroll: A #StScrollView
*
- * Gets the value set by st_scroll_view_set_overlay_scrollbars().
+ * Gets whether scrollbars are painted on top of the content.
+ *
+ * Returns: %TRUE if enabled, %FALSE otherwise
*/
gboolean
st_scroll_view_get_overlay_scrollbars (StScrollView *scroll)
diff --git a/src/st/st-scrollable.c b/src/st/st-scrollable.c
index 234318274f..93f06c1222 100644
--- a/src/st/st-scrollable.c
+++ b/src/st/st-scrollable.c
@@ -86,6 +86,40 @@ st_scrollable_default_init (StScrollableInterface *g_iface)
if (!initialized)
{
+ /**
+ * StScrollable:hadjustment:
+ *
+ * The horizontal #StAdjustment used by the #StScrollable.
+ *
+ * Implementations should override this property to provide read-write
+ * access to the #StAdjustment.
+ *
+ * JavaScript code may override this as demonstrated below:
+ *
+ * |[<!-- language="JavaScript" -->
+ * var MyScrollable = GObject.registerClass({
+ * Properties: {
+ * 'hadjustment': GObject.ParamSpec.override(
+ * 'hadjustment',
+ * St.Scrollable
+ * )
+ * }
+ * }, class MyScrollable extends St.Scrollable {
+ *
+ * get hadjustment() {
+ * return this._hadjustment || null;
+ * }
+ *
+ * set hadjustment(adjustment) {
+ * if (this.hadjustment === adjustment)
+ * return;
+ *
+ * this._hadjustment = adjustment;
+ * this.notify('hadjustment');
+ * }
+ * });
+ * ]|
+ */
g_object_interface_install_property (g_iface,
g_param_spec_object ("hadjustment",
"StAdjustment",
@@ -93,6 +127,17 @@ st_scrollable_default_init (StScrollableInterface *g_iface)
ST_TYPE_ADJUSTMENT,
ST_PARAM_READWRITE));
+ /**
+ * StScrollable:vadjustment:
+ *
+ * The vertical #StAdjustment used by the #StScrollable.
+ *
+ * Implementations should override this property to provide read-write
+ * access to the #StAdjustment.
+ *
+ * See #StScrollable:hadjustment for an example of how to override this
+ * property in JavaScript code.
+ */
g_object_interface_install_property (g_iface,
g_param_spec_object ("vadjustment",
"StAdjustment",
@@ -104,6 +149,18 @@ st_scrollable_default_init (StScrollableInterface *g_iface)
}
}
+/**
+ * st_scrollable_set_adjustments:
+ * @scrollable: a #StScrollable
+ * @hadjustment: the horizontal #StAdjustment
+ * @vadjustment: the vertical #StAdjustment
+ *
+ * This method should be implemented by classes implementing the #StScrollable
+ * interface.
+ *
+ * JavaScript code should do this by overriding the `vfunc_set_adjustments()`
+ * method.
+ */
void
st_scrollable_set_adjustments (StScrollable *scrollable,
StAdjustment *hadjustment,
@@ -116,11 +173,17 @@ st_scrollable_set_adjustments (StScrollable *scrollable,
/**
* st_scroll_bar_get_adjustments:
- * @hadjustment: (transfer none) (out) (optional) (nullable): location to store the horizontal adjustment,
or %NULL
- * @vadjustment: (transfer none) (out) (optional) (nullable): location to store the vertical adjustment, or
%NULL
+ * @hadjustment: (transfer none) (out) (optional): location to store the horizontal adjustment, or %NULL
+ * @vadjustment: (transfer none) (out) (optional): location to store the vertical adjustment, or %NULL
*
* Gets the adjustment objects that store the offsets of the scrollable widget
* into its possible scrolling area.
+ *
+ * This method should be implemented by classes implementing the #StScrollable
+ * interface.
+ *
+ * JavaScript code should do this by overriding the `vfunc_get_adjustments()`
+ * method.
*/
void
st_scrollable_get_adjustments (StScrollable *scrollable,
diff --git a/src/st/st-settings.c b/src/st/st-settings.c
index 5ce73d0153..0ece3ccef7 100644
--- a/src/st/st-settings.c
+++ b/src/st/st-settings.c
@@ -199,41 +199,89 @@ st_settings_class_init (StSettingsClass *klass)
object_class->set_property = st_settings_set_property;
object_class->get_property = st_settings_get_property;
+ /**
+ * StSettings:enable-animations:
+ *
+ * Whether animations are enabled.
+ */
props[PROP_ENABLE_ANIMATIONS] = g_param_spec_boolean ("enable-animations",
"Enable animations",
"Enable animations",
TRUE,
ST_PARAM_READABLE);
+
+ /**
+ * StSettings:primary-paste:
+ *
+ * Whether pasting from the `PRIMARY` selection is supported (eg. middle-click
+ * paste).
+ */
props[PROP_PRIMARY_PASTE] = g_param_spec_boolean ("primary-paste",
"Primary paste",
"Primary paste",
TRUE,
ST_PARAM_READABLE);
+
+ /**
+ * StSettings:drag-threshold:
+ *
+ * The threshold before a drag operation begins.
+ */
props[PROP_DRAG_THRESHOLD] = g_param_spec_int ("drag-threshold",
"Drag threshold",
"Drag threshold",
0, G_MAXINT, 8,
ST_PARAM_READABLE);
+
+ /**
+ * StSettings:font-name:
+ *
+ * The current font name.
+ */
props[PROP_FONT_NAME] = g_param_spec_string ("font-name",
"font name",
"font name",
"",
ST_PARAM_READABLE);
+
+ /**
+ * StSettings:gtk-theme:
+ *
+ * The current GTK theme.
+ */
props[PROP_GTK_THEME] = g_param_spec_string ("gtk-theme",
- "GTK+ Theme",
- "GTK+ Theme",
+ "GTK Theme",
+ "GTK Theme",
"",
ST_PARAM_READABLE);
+
+ /**
+ * StSettings:gtk-icon-theme:
+ *
+ * The current GTK icon theme
+ */
props[PROP_GTK_ICON_THEME] = g_param_spec_string ("gtk-icon-theme",
- "GTK+ Icon Theme",
- "GTK+ Icon Theme",
+ "GTK Icon Theme",
+ "GTK Icon Theme",
"",
ST_PARAM_READABLE);
+
+ /**
+ * StSettings:magnifier-active:
+ *
+ * Whether the accessibility magnifier is active.
+ */
props[PROP_MAGNIFIER_ACTIVE] = g_param_spec_boolean("magnifier-active",
"Magnifier is active",
- "Weather the a11y magnifier is active",
+ "Whether the a11y magnifier is active",
FALSE,
ST_PARAM_READABLE);
+
+ /**
+ * StSettings:slow-down-factor:
+ *
+ * The slow-down factor applied to all animation durations.
+ */
props[PROP_SLOW_DOWN_FACTOR] = g_param_spec_double("slow-down-factor",
"Slow down factor",
"Factor applied to all animation durations",
@@ -338,9 +386,9 @@ st_settings_init (StSettings *settings)
/**
* st_settings_get:
*
- * Gets the #StSettings
+ * Gets the global #StSettings object.
*
- * Returns: (transfer none): a settings object
+ * Returns: (transfer none): the global #StSettings object
**/
StSettings *
st_settings_get (void)
diff --git a/src/st/st-shadow.c b/src/st/st-shadow.c
index f3a22f0346..96e654fda0 100644
--- a/src/st/st-shadow.c
+++ b/src/st/st-shadow.c
@@ -117,7 +117,7 @@ st_shadow_unref (StShadow *shadow)
* compare non-identically if they differ only by floating point rounding
* errors.
*
- * Return value: %TRUE if the two shadows are identical
+ * Returns: %TRUE if the two shadows are identical
*/
gboolean
st_shadow_equal (StShadow *shadow,
@@ -216,6 +216,13 @@ st_shadow_helper_new (StShadow *shadow)
return helper;
}
+/**
+ * st_shadow_helper_update:
+ * @helper: a #StShadowHelper
+ * @source: a #ClutterActor
+ *
+ * Update @helper from @source.
+ */
void
st_shadow_helper_update (StShadowHelper *helper,
ClutterActor *source)
diff --git a/src/st/st-texture-cache.c b/src/st/st-texture-cache.c
index 0359534e2e..947d8fc89e 100644
--- a/src/st/st-texture-cache.c
+++ b/src/st/st-texture-cache.c
@@ -100,6 +100,12 @@ st_texture_cache_class_init (StTextureCacheClass *klass)
gobject_class->dispose = st_texture_cache_dispose;
gobject_class->finalize = st_texture_cache_finalize;
+ /**
+ * StTextureCache::icon-theme-changed:
+ * @self: a #StTextureCache
+ *
+ * Emitted when the icon theme is changed.
+ */
signals[ICON_THEME_CHANGED] =
g_signal_new ("icon-theme-changed",
G_TYPE_FROM_CLASS (klass),
@@ -108,6 +114,13 @@ st_texture_cache_class_init (StTextureCacheClass *klass)
NULL, NULL, NULL,
G_TYPE_NONE, 0);
+ /**
+ * StTextureCache::texture-file-changed:
+ * @self: a #StTextureCache
+ * @file: a #GFile
+ *
+ * Emitted when the source file of a texture is changed.
+ */
signals[TEXTURE_FILE_CHANGED] =
g_signal_new ("texture-file-changed",
G_TYPE_FROM_CLASS (klass),
@@ -799,7 +812,7 @@ st_texture_cache_free_bind (gpointer data)
/**
* st_texture_cache_bind_cairo_surface_property:
- * @cache:
+ * @cache: A #StTextureCache
* @object: A #GObject with a property @property_name of type #cairo_surface_t
* @property_name: Name of a property
*
@@ -810,7 +823,7 @@ st_texture_cache_free_bind (gpointer data)
* If the source object is destroyed, the texture will continue to show the last
* value of the property.
*
- * Return value: (transfer none): A new #GIcon
+ * Returns: (transfer none): A new #GIcon
*/
GIcon *
st_texture_cache_bind_cairo_surface_property (StTextureCache *cache,
@@ -879,7 +892,7 @@ st_texture_cache_load (StTextureCache *cache,
/**
* ensure_request:
- * @cache:
+ * @cache: A #StTextureCache
* @key: A cache key
* @policy: Cache policy
* @request: (out): If no request is outstanding, one will be created and returned here
@@ -932,8 +945,8 @@ ensure_request (StTextureCache *cache,
/**
* st_texture_cache_load_gicon:
- * @cache: The texture cache instance
- * @theme_node: (nullable): The #StThemeNode to use for colors, or NULL
+ * @cache: A #StTextureCache
+ * @theme_node: (nullable): The #StThemeNode to use for colors, or %NULL
* if the icon must not be recolored
* @icon: the #GIcon to load
* @size: Size of themed
@@ -944,7 +957,7 @@ ensure_request (StTextureCache *cache,
* icon isn't loaded already, the texture will be filled
* asynchronously.
*
- * Return Value: (transfer none): A new #ClutterActor for the icon, or %NULL if not found
+ * Returns: (transfer none) (nullable): A new #ClutterActor for the icon, or %NULL if not found
*/
ClutterActor *
st_texture_cache_load_gicon (StTextureCache *cache,
@@ -1371,7 +1384,7 @@ st_texture_cache_load_sliced_image (StTextureCache *cache,
/**
* st_texture_cache_load_file_async:
- * @cache: The texture cache instance
+ * @cache: A #StTextureCache
* @file: a #GFile of the image file from which to create a pixbuf
* @available_width: available width for the image, can be -1 if not limited
* @available_height: available height for the image, can be -1 if not limited
@@ -1382,7 +1395,7 @@ st_texture_cache_load_sliced_image (StTextureCache *cache,
* size of zero. At some later point, either the image will be loaded successfully
* and at that point size will be negotiated, or upon an error, no image will be set.
*
- * Return value: (transfer none): A new #ClutterActor with no image loaded initially.
+ * Returns: (transfer none): A new #ClutterActor with no image loaded initially.
*/
ClutterActor *
st_texture_cache_load_file_async (StTextureCache *cache,
@@ -1612,7 +1625,7 @@ static StTextureCache *instance = NULL;
/**
* st_texture_cache_get_default:
*
- * Return value: (transfer none): The global texture cache
+ * Returns: (transfer none): The global texture cache
*/
StTextureCache*
st_texture_cache_get_default (void)
@@ -1622,6 +1635,13 @@ st_texture_cache_get_default (void)
return instance;
}
+/**
+ * st_texture_cache_rescan_icon_theme:
+ *
+ * Rescan the current icon theme, if necessary.
+ *
+ * Returns: %TRUE if the icon theme has changed and needed to be reloaded.
+ */
gboolean
st_texture_cache_rescan_icon_theme (StTextureCache *cache)
{
diff --git a/src/st/st-theme-context.c b/src/st/st-theme-context.c
index f10737b803..6d8c90d152 100644
--- a/src/st/st-theme-context.c
+++ b/src/st/st-theme-context.c
@@ -118,16 +118,23 @@ st_theme_context_class_init (StThemeContextClass *klass)
/**
* StThemeContext:scale-factor:
*
- * The scaling factor used or high dpi scaling.
+ * The scaling factor used for HiDPI scaling.
*/
g_object_class_install_property (object_class,
PROP_SCALE_FACTOR,
g_param_spec_int ("scale-factor",
"Scale factor",
- "Integer scale factor used for high dpi scaling",
+ "Integer scale factor used for HiDPI scaling",
0, G_MAXINT, 1,
ST_PARAM_READWRITE));
+ /**
+ * StThemeContext::changed:
+ * @self: a #StThemeContext
+ *
+ * Emitted when the icon theme, font, resolution, scale factor or the current
+ * theme's custom stylesheets change.
+ */
signals[CHANGED] =
g_signal_new ("changed",
G_TYPE_FROM_CLASS (klass),
@@ -214,6 +221,8 @@ st_theme_context_get_property (GObject *object,
* This can be useful in testing scenarios, or if using StThemeContext
* with something other than #ClutterActor objects, but you generally
* should use st_theme_context_get_for_stage() instead.
+ *
+ * Returns: (transfer full): a new #StThemeContext
*/
StThemeContext *
st_theme_context_new (void)
@@ -296,7 +305,7 @@ on_icon_theme_changed (StTextureCache *cache,
*
* Gets a singleton theme context associated with the stage.
*
- * Return value: (transfer none): the singleton theme context for the stage
+ * Returns: (transfer none): the singleton theme context for the stage
*/
StThemeContext *
st_theme_context_get_for_stage (ClutterStage *stage)
@@ -320,6 +329,7 @@ st_theme_context_get_for_stage (ClutterStage *stage)
/**
* st_theme_context_set_theme:
* @context: a #StThemeContext
+ * @theme: a #StTheme
*
* Sets the default set of theme stylesheets for the context. This theme will
* be used for the root node and for nodes descending from it, unless some other
@@ -358,7 +368,7 @@ st_theme_context_set_theme (StThemeContext *context,
*
* Gets the default theme for the context. See st_theme_context_set_theme()
*
- * Return value: (transfer none): the default theme for the context
+ * Returns: (transfer none): the default theme for the context
*/
StTheme *
st_theme_context_get_theme (StThemeContext *context)
@@ -376,7 +386,7 @@ st_theme_context_get_theme (StThemeContext *context)
* Sets the default font for the theme context. This is the font that
* is inherited by the root node of the tree of theme nodes. If the
* font is not overriden, then this font will be used. If the font is
- * partially modified (for example, with 'font-size: 110%', then that
+ * partially modified (for example, with 'font-size: 110%'), then that
* modification is based on this font.
*/
void
@@ -401,7 +411,7 @@ st_theme_context_set_font (StThemeContext *context,
*
* Gets the default font for the theme context. See st_theme_context_set_font().
*
- * Return value: the default font for the theme context.
+ * Returns: the default font for the theme context.
*/
const PangoFontDescription *
st_theme_context_get_font (StThemeContext *context)
@@ -419,7 +429,7 @@ st_theme_context_get_font (StThemeContext *context)
* context. For the node tree associated with a stage, this node represents
* styles applied to the stage itself.
*
- * Return value: (transfer none): the root node of the context's style tree
+ * Returns: (transfer none): the root node of the context's style tree
*/
StThemeNode *
st_theme_context_get_root_node (StThemeContext *context)
@@ -439,7 +449,7 @@ st_theme_context_get_root_node (StThemeContext *context)
* Return an existing node matching @node, or if that isn't possible,
* @node itself.
*
- * Return value: (transfer none): a node with the same properties as @node
+ * Returns: (transfer none): a node with the same properties as @node
*/
StThemeNode *
st_theme_context_intern_node (StThemeContext *context,
@@ -461,7 +471,7 @@ st_theme_context_intern_node (StThemeContext *context,
*
* Return the current scale factor of @context.
*
- * Return value: a scale factor
+ * Returns: an integer scale factor
*/
int
st_theme_context_get_scale_factor (StThemeContext *context)
diff --git a/src/st/st-theme-node.c b/src/st/st-theme-node.c
index ca9675895b..cbfc9d064a 100644
--- a/src/st/st-theme-node.c
+++ b/src/st/st-theme-node.c
@@ -180,11 +180,11 @@ split_on_whitespace (const gchar *s)
* @pseudo_class: (nullable): a whitespace-separated list of pseudo-classes
* (like 'hover' or 'visited') to match CSS rules against
*
- * Creates a new #StThemeNode. Once created, a node is immutable. Of any
+ * Creates a new #StThemeNode. Once created, a node is immutable. If any
* of the attributes of the node (like the @element_class) change the node
* and its child nodes must be destroyed and recreated.
*
- * Return value: (transfer full): the theme node
+ * Returns: (transfer full): a new #StThemeNode
*/
StThemeNode *
st_theme_node_new (StThemeContext *context,
@@ -229,8 +229,8 @@ st_theme_node_new (StThemeContext *context,
*
* Gets the parent themed element node.
*
- * Return value: (transfer none): the parent #StThemeNode, or %NULL if this
- * is the root node of the tree of theme elements.
+ * Returns: (nullable) (transfer none): the parent #StThemeNode, or %NULL if
+ * this is the root node of the tree of theme elements.
*/
StThemeNode *
st_theme_node_get_parent (StThemeNode *node)
@@ -246,7 +246,7 @@ st_theme_node_get_parent (StThemeNode *node)
*
* Gets the theme stylesheet set that styles this node
*
- * Return value: (transfer none): the theme stylesheet set
+ * Returns: (transfer none): the theme stylesheet set
*/
StTheme *
st_theme_node_get_theme (StThemeNode *node)
@@ -256,6 +256,14 @@ st_theme_node_get_theme (StThemeNode *node)
return node->theme;
}
+/**
+ * st_theme_node_get_element_type:
+ * @node: a #StThemeNode
+ *
+ * Get the element #GType for @node.
+ *
+ * Returns: the element type
+ */
GType
st_theme_node_get_element_type (StThemeNode *node)
{
@@ -264,6 +272,14 @@ st_theme_node_get_element_type (StThemeNode *node)
return node->element_type;
}
+/**
+ * st_theme_node_get_element_id:
+ * @node: a #StThemeNode
+ *
+ * Get the unqiue element ID for @node.
+ *
+ * Returns: (transfer none): the element's ID
+ */
const char *
st_theme_node_get_element_id (StThemeNode *node)
{
@@ -274,6 +290,9 @@ st_theme_node_get_element_id (StThemeNode *node)
/**
* st_theme_node_get_element_classes:
+ * @node: a #StThemeNode
+ *
+ * Get the list of element classes for @node.
*
* Returns: (transfer none): the element's classes
*/
@@ -287,6 +306,9 @@ st_theme_node_get_element_classes (StThemeNode *node)
/**
* st_theme_node_get_pseudo_classes:
+ * @node: a #StThemeNode
+ *
+ * Get the list of pseudo-classes for @node (eg. `:focused`).
*
* Returns: (transfer none): the element's pseudo-classes
*/
@@ -307,21 +329,13 @@ st_theme_node_get_pseudo_classes (StThemeNode *node)
* the same CSS rules and have the same style properties. However, two
* nodes that have ended up with identical style properties do not
* necessarily compare equal.
- * In detail, @node_a and @node_b are considered equal iff
- * <itemizedlist>
- * <listitem>
- * <para>they share the same #StTheme and #StThemeContext</para>
- * </listitem>
- * <listitem>
- * <para>they have the same parent</para>
- * </listitem>
- * <listitem>
- * <para>they have the same element type</para>
- * </listitem>
- * <listitem>
- * <para>their id, class, pseudo-class and inline-style match</para>
- * </listitem>
- * </itemizedlist>
+ *
+ * In detail, @node_a and @node_b are considered equal if and only if:
+ *
+ * - they share the same #StTheme and #StThemeContext
+ * - they have the same parent
+ * - they have the same element type
+ * - their id, class, pseudo-class and inline-style match
*
* Returns: %TRUE if @node_a equals @node_b
*/
@@ -383,6 +397,14 @@ st_theme_node_equal (StThemeNode *node_a, StThemeNode *node_b)
return TRUE;
}
+/**
+ * st_theme_node_hash:
+ * @node: a #StThemeNode
+ *
+ * Converts @node to a hash value.
+ *
+ * Returns: a hash value corresponding to @node
+ */
guint
st_theme_node_hash (StThemeNode *node)
{
@@ -637,7 +659,7 @@ get_color_from_term (StThemeNode *node,
*
* See also st_theme_node_get_color(), which provides a simpler API.
*
- * Return value: %TRUE if the property was found in the properties for this
+ * Returns: %TRUE if the property was found in the properties for this
* theme node (or in the properties of parent nodes when inheriting.)
*/
gboolean
@@ -727,7 +749,7 @@ st_theme_node_get_color (StThemeNode *node,
*
* See also st_theme_node_get_double(), which provides a simpler API.
*
- * Return value: %TRUE if the property was found in the properties for this
+ * Returns: %TRUE if the property was found in the properties for this
* theme node (or in the properties of parent nodes when inheriting.)
*/
gboolean
@@ -780,7 +802,7 @@ st_theme_node_lookup_double (StThemeNode *node,
* Generically looks up a property containing a single time value,
* which is converted to milliseconds.
*
- * Return value: %TRUE if the property was found in the properties for this
+ * Returns: %TRUE if the property was found in the properties for this
* theme node (or in the properties of parent nodes when inheriting.)
*/
gboolean
@@ -837,7 +859,7 @@ st_theme_node_lookup_time (StThemeNode *node,
* and lets you handle the case where the theme does not specify the
* indicated value.
*
- * Return value: the value found. If @property_name is not
+ * Returns: the value found. If @property_name is not
* found, a warning will be logged and 0 will be returned.
*/
gdouble
@@ -872,7 +894,7 @@ st_theme_node_get_double (StThemeNode *node,
*
* See also st_theme_node_get_url(), which provides a simpler API.
*
- * Return value: %TRUE if the property was found in the properties for this
+ * Returns: %TRUE if the property was found in the properties for this
* theme node (or in the properties of parent nodes when inheriting.)
*/
gboolean
@@ -928,7 +950,7 @@ st_theme_node_lookup_url (StThemeNode *node,
* and lets you handle the case where the theme does not specify the
* indicated value.
*
- * Returns: (transfer full): the newly allocated value if found.
+ * Returns: (nullable) (transfer full): the newly allocated value if found.
* If @property_name is not found, a warning will be logged and %NULL
* will be returned.
*/
@@ -1169,7 +1191,7 @@ get_length_internal (StThemeNode *node,
*
* See also st_theme_node_get_length(), which provides a simpler API.
*
- * Return value: %TRUE if the property was found in the properties for this
+ * Returns: %TRUE if the property was found in the properties for this
* theme node (or in the properties of parent nodes when inheriting.)
*/
gboolean
@@ -1204,9 +1226,10 @@ st_theme_node_lookup_length (StThemeNode *node,
* this does not print a warning if the property is not found; it just
* returns 0.
*
- * See also st_theme_node_lookup_length(), which provides more options.
+ * See also st_theme_node_lookup_length(), which provides more options. The
+ * returned value is in physical pixels, as opposed to logical pixels.
*
- * Return value: the length, in pixels, or 0 if the property was not found.
+ * Returns: the length, in pixels, or 0 if the property was not found.
*/
gdouble
st_theme_node_get_length (StThemeNode *node,
@@ -1807,6 +1830,15 @@ _st_theme_node_ensure_geometry (StThemeNode *node)
node->height = node->min_height;
}
+/**
+ * st_theme_node_get_border_width:
+ * @node: a #StThemeNode
+ * @side: a #StCorner
+ *
+ * Get the border width for @node on @side, in physical pixels.
+ *
+ * Returns: the border width in physical pixels
+ */
int
st_theme_node_get_border_width (StThemeNode *node,
StSide side)
@@ -1819,6 +1851,15 @@ st_theme_node_get_border_width (StThemeNode *node,
return node->border_width[side];
}
+/**
+ * st_theme_node_get_border_radius:
+ * @node: a #StThemeNode
+ * @corner: a #StCorner
+ *
+ * Get the border radius for @node at @corner, in physical pixels.
+ *
+ * Returns: the border radius in physical pixels
+ */
int
st_theme_node_get_border_radius (StThemeNode *node,
StCorner corner)
@@ -1831,6 +1872,14 @@ st_theme_node_get_border_radius (StThemeNode *node,
return node->border_radius[corner];
}
+/**
+ * st_theme_node_get_outline_width:
+ * @node: a #StThemeNode
+ *
+ * Get the width of the outline for @node, in physical pixels.
+ *
+ * Returns: the width in physical pixels
+ */
int
st_theme_node_get_outline_width (StThemeNode *node)
{
@@ -1859,6 +1908,14 @@ st_theme_node_get_outline_color (StThemeNode *node,
*color = node->outline_color;
}
+/**
+ * st_theme_node_get_width:
+ * @node: a #StThemeNode
+ *
+ * Get the width for @node, in physical pixels.
+ *
+ * Returns: the width in physical pixels
+ */
int
st_theme_node_get_width (StThemeNode *node)
{
@@ -1868,6 +1925,14 @@ st_theme_node_get_width (StThemeNode *node)
return node->width;
}
+/**
+ * st_theme_node_get_height:
+ * @node: a #StThemeNode
+ *
+ * Get the height for @node, in physical pixels.
+ *
+ * Returns: the height in physical pixels
+ */
int
st_theme_node_get_height (StThemeNode *node)
{
@@ -1877,6 +1942,14 @@ st_theme_node_get_height (StThemeNode *node)
return node->height;
}
+/**
+ * st_theme_node_get_min_width:
+ * @node: a #StThemeNode
+ *
+ * Get the minimum width for @node, in physical pixels.
+ *
+ * Returns: the minimum width in physical pixels
+ */
int
st_theme_node_get_min_width (StThemeNode *node)
{
@@ -1886,6 +1959,14 @@ st_theme_node_get_min_width (StThemeNode *node)
return node->min_width;
}
+/**
+ * st_theme_node_get_min_height:
+ * @node: a #StThemeNode
+ *
+ * Get the minimum height for @node, in physical pixels.
+ *
+ * Returns: the minimum height in physical pixels
+ */
int
st_theme_node_get_min_height (StThemeNode *node)
{
@@ -1895,6 +1976,14 @@ st_theme_node_get_min_height (StThemeNode *node)
return node->min_height;
}
+/**
+ * st_theme_node_get_max_width:
+ * @node: a #StThemeNode
+ *
+ * Get the maximum width for @node, in physical pixels.
+ *
+ * Returns: the maximum width in physical pixels
+ */
int
st_theme_node_get_max_width (StThemeNode *node)
{
@@ -1904,6 +1993,14 @@ st_theme_node_get_max_width (StThemeNode *node)
return node->max_width;
}
+/**
+ * st_theme_node_get_max_height:
+ * @node: a #StThemeNode
+ *
+ * Get the maximum height for @node, in physical pixels.
+ *
+ * Returns: the maximum height in physical pixels
+ */
int
st_theme_node_get_max_height (StThemeNode *node)
{
@@ -2270,6 +2367,16 @@ st_theme_node_get_border_color (StThemeNode *node,
*color = node->border_color[side];
}
+/**
+ * st_theme_node_get_padding:
+ * @node: a #StThemeNode
+ * @side: a #StSide
+ *
+ * Get the padding for @node on @side, in physical pixels. This corresponds to
+ * the CSS properties such as `padding-top`.
+ *
+ * Returns: the padding size in physical pixels
+ */
double
st_theme_node_get_padding (StThemeNode *node,
StSide side)
@@ -2282,6 +2389,16 @@ st_theme_node_get_padding (StThemeNode *node,
return node->padding[side];
}
+/**
+ * st_theme_node_get_margin:
+ * @node: a #StThemeNode
+ * @side: a #StSide
+ *
+ * Get the margin for @node on @side, in physical pixels. This corresponds to
+ * the CSS properties such as `margin-top`.
+ *
+ * Returns: the margin size in physical pixels
+ */
double
st_theme_node_get_margin (StThemeNode *node,
StSide side)
@@ -2326,6 +2443,15 @@ st_theme_node_get_transition_duration (StThemeNode *node)
return factor * node->transition_duration;
}
+/**
+ * st_theme_node_get_icon_style:
+ * @node: a #StThemeNode
+ *
+ * Get the icon style for @node (eg. symbolic, regular). This corresponds to the
+ * special `-st-icon-style` CSS property.
+ *
+ * Returns: the icon style for @node
+ */
StIconStyle
st_theme_node_get_icon_style (StThemeNode *node)
{
@@ -2368,6 +2494,14 @@ st_theme_node_get_icon_style (StThemeNode *node)
return ST_ICON_STYLE_REQUESTED;
}
+/**
+ * st_theme_node_get_text_decoration
+ * @node: a #StThemeNode
+ *
+ * Get the text decoration for @node (eg. underline, line-through, etc).
+ *
+ * Returns: the text decoration for @node
+ */
StTextDecoration
st_theme_node_get_text_decoration (StThemeNode *node)
{
@@ -2435,6 +2569,14 @@ st_theme_node_get_text_decoration (StThemeNode *node)
return 0;
}
+/**
+ * st_theme_node_get_text_align:
+ * @node: a #StThemeNode
+ *
+ * Get the text alignment of @node.
+ *
+ * Returns: the alignment of text for @node
+ */
StTextAlign
st_theme_node_get_text_align(StThemeNode *node)
{
@@ -2486,9 +2628,9 @@ st_theme_node_get_text_align(StThemeNode *node)
* st_theme_node_get_letter_spacing:
* @node: a #StThemeNode
*
- * Gets the value for the letter-spacing style property, in pixels.
+ * Gets the value for the letter-spacing style property, in physical pixels.
*
- * Return value: the value of the letter-spacing property, if
+ * Returns: the value of the letter-spacing property, if
* found, or zero if such property has not been found.
*/
gdouble
@@ -2763,6 +2905,14 @@ font_variant_from_term (CRTerm *term,
return TRUE;
}
+/**
+ * st_theme_node_get_font:
+ * @node: a #StThemeNode
+ *
+ * Get the current font of @node as a #PangoFontDescription
+ *
+ * Returns: (transfer none): the current font
+ */
const PangoFontDescription *
st_theme_node_get_font (StThemeNode *node)
{
@@ -2956,6 +3106,14 @@ st_theme_node_get_font (StThemeNode *node)
return node->font_desc;
}
+/**
+ * st_theme_node_get_font_features:
+ * @node: a #StThemeNode
+ *
+ * Get the CSS font-features for @node.
+ *
+ * Returns: (transfer full): font-features as a string
+ */
gchar *
st_theme_node_get_font_features (StThemeNode *node)
{
@@ -2995,7 +3153,7 @@ st_theme_node_get_font_features (StThemeNode *node)
*
* Gets the value for the border-image style property
*
- * Return value: (transfer none): the border image, or %NULL
+ * Returns: (transfer none): the border image, or %NULL
* if there is no border image.
*/
StBorderImage *
@@ -3132,10 +3290,9 @@ st_theme_node_get_border_image (StThemeNode *node)
* st_theme_node_get_horizontal_padding:
* @node: a #StThemeNode
*
- * Gets the total horizonal padding (left + right padding)
+ * Gets the total horizonal padding (left + right padding), in physical pixels.
*
- * Return value: the total horizonal padding
- * in pixels
+ * Returns: the total horizonal padding in physical pixels
*/
double
st_theme_node_get_horizontal_padding (StThemeNode *node)
@@ -3151,10 +3308,9 @@ st_theme_node_get_horizontal_padding (StThemeNode *node)
* st_theme_node_get_vertical_padding:
* @node: a #StThemeNode
*
- * Gets the total vertical padding (top + bottom padding)
+ * Gets the total vertical padding (top + bottom padding), in physical pixels.
*
- * Return value: the total vertical padding
- * in pixels
+ * Returns: the total vertical padding in physical pixels
*/
double
st_theme_node_get_vertical_padding (StThemeNode *node)
@@ -3317,9 +3473,9 @@ parse_shadow_property (StThemeNode *node,
*
* See also st_theme_node_get_shadow(), which provides a simpler API.
*
- * Return value: %TRUE if the property was found in the properties for this
- * theme node (or in the properties of parent nodes when inheriting.), %FALSE
- * if the property was not found, or was explicitly set to 'none'.
+ * Returns: %TRUE if the property was found in the properties for this
+ * theme node (or in the properties of parent nodes when inheriting.), %FALSE
+ * if the property was not found, or was explicitly set to 'none'.
*/
gboolean
st_theme_node_lookup_shadow (StThemeNode *node,
@@ -3402,7 +3558,8 @@ st_theme_node_lookup_shadow (StThemeNode *node,
*
* See also st_theme_node_lookup_shadow (), which provides more options.
*
- * Return value: (transfer full): the shadow, or %NULL if the property was not found.
+ * Returns: (nullable) (transfer full): the shadow, or %NULL if the property was
+ * not found.
*/
StShadow *
st_theme_node_get_shadow (StThemeNode *node,
@@ -3422,7 +3579,7 @@ st_theme_node_get_shadow (StThemeNode *node,
*
* Gets the value for the box-shadow style property
*
- * Return value: (transfer none): the node's shadow, or %NULL
+ * Returns: (nullable) (transfer none): the node's shadow, or %NULL
* if node has no shadow
*/
StShadow *
@@ -3455,8 +3612,8 @@ st_theme_node_get_box_shadow (StThemeNode *node)
*
* Gets the value for the -st-background-image-shadow style property
*
- * Return value: (transfer none): the node's background image shadow, or %NULL
- * if node has no such shadow
+ * Returns: (nullable) (transfer none): the node's background image shadow, or
+ * %NULL if node has no such shadow
*/
StShadow *
st_theme_node_get_background_image_shadow (StThemeNode *node)
@@ -3496,7 +3653,7 @@ st_theme_node_get_background_image_shadow (StThemeNode *node)
*
* Gets the value for the text-shadow style property
*
- * Return value: (transfer none): the node's text-shadow, or %NULL
+ * Returns: (nullable) (transfer none): the node's text-shadow, or %NULL
* if node has no text-shadow
*/
StShadow *
@@ -3542,7 +3699,7 @@ st_theme_node_get_text_shadow (StThemeNode *node)
* Gets the colors that should be used for colorizing symbolic icons according
* the style of this node.
*
- * Return value: (transfer none): the icon colors to use for this theme node
+ * Returns: (transfer none): the icon colors to use for this theme node
*/
StIconColors *
st_theme_node_get_icon_colors (StThemeNode *node)
@@ -3941,6 +4098,8 @@ st_theme_node_get_paint_box (StThemeNode *node,
* Tests if two theme nodes have the same borders and padding; this can be
* used to optimize having to relayout when the style applied to a Clutter
* actor changes colors without changing the geometry.
+ *
+ * Returns: %TRUE if equal, %FALSE otherwise
*/
gboolean
st_theme_node_geometry_equal (StThemeNode *node,
@@ -3988,7 +4147,7 @@ st_theme_node_geometry_equal (StThemeNode *node,
* for @other. Note that in some cases this function may return %TRUE even
* if there is no visible difference in the painting.
*
- * Return value: %TRUE if the two theme nodes paint identically. %FALSE if the
+ * Returns: %TRUE if the two theme nodes paint identically. %FALSE if the
* two nodes potentially paint differently.
*/
gboolean
@@ -4077,6 +4236,15 @@ st_theme_node_paint_equal (StThemeNode *node,
return TRUE;
}
+/**
+ * st_theme_node_to_string:
+ * @node: a #StThemeNode
+ *
+ * Serialize @node to a string of its #GType name, CSS ID, classes and
+ * pseudo-classes.
+ *
+ * Returns: the serialized theme node
+ */
gchar *
st_theme_node_to_string (StThemeNode *node)
{
diff --git a/src/st/st-theme-node.h b/src/st/st-theme-node.h
index 53c0ad05d7..520e29f4f4 100644
--- a/src/st/st-theme-node.h
+++ b/src/st/st-theme-node.h
@@ -43,6 +43,11 @@ G_BEGIN_DECLS
* accessors for standard CSS properties that add caching and handling of various
* details of the CSS specification. #StThemeNode also has convenience functions to help
* in implementing a #ClutterActor with borders and padding.
+ *
+ * Note that pixel measurements take the #StThemeContext:scale-factor into
+ * account so all values are in physical pixels, as opposed to logical pixels.
+ * Physical pixels correspond to actor sizes, not necessarily to pixels on
+ * display devices (eg. when `scale-monitor-framebuffer` is enabled).
*/
typedef struct _StTheme StTheme;
@@ -51,6 +56,15 @@ typedef struct _StThemeContext StThemeContext;
#define ST_TYPE_THEME_NODE (st_theme_node_get_type ())
G_DECLARE_FINAL_TYPE (StThemeNode, st_theme_node, ST, THEME_NODE, GObject)
+/**
+ * StSide:
+ * @ST_SIDE_TOP: The top side.
+ * @ST_SIDE_RIGHT: The right side.
+ * @ST_SIDE_BOTTOM: The bottom side.
+ * @ST_SIDE_LEFT: The left side.
+ *
+ * Used to target a particular side of a #StThemeNode element.
+ */
typedef enum {
ST_SIDE_TOP,
ST_SIDE_RIGHT,
@@ -58,6 +72,15 @@ typedef enum {
ST_SIDE_LEFT
} StSide;
+/**
+ * StCorner:
+ * @ST_CORNER_TOPLEFT: The top-right corner.
+ * @ST_CORNER_TOPRIGHT: The top-right corner.
+ * @ST_CORNER_BOTTOMRIGHT: The bottom-right corner.
+ * @ST_CORNER_BOTTOMLEFT: The bottom-left corner.
+ *
+ * Used to target a particular corner of a #StThemeNode element.
+ */
typedef enum {
ST_CORNER_TOPLEFT,
ST_CORNER_TOPRIGHT,
@@ -66,6 +89,18 @@ typedef enum {
} StCorner;
/* These are the CSS values; that doesn't mean we have to implement blink... */
+/**
+ * StTextDecoration:
+ * @ST_TEXT_DECORATION_: Text is underlined
+ * @ST_TEXT_DECORATION_OVERLINE: Text is overlined
+ * @ST_TEXT_DECORATION_LINE_THROUGH: Text is striked out
+ * @ST_TEXT_DECORATION_BLINK: Text blinks
+ *
+ * Flags used to determine the decoration of text.
+ *
+ * Not that neither %ST_TEXT_DECORATION_OVERLINE or %ST_TEXT_DECORATION_BLINK
+ * are implemented, currently.
+ */
typedef enum {
ST_TEXT_DECORATION_UNDERLINE = 1 << 0,
ST_TEXT_DECORATION_OVERLINE = 1 << 1,
@@ -73,6 +108,15 @@ typedef enum {
ST_TEXT_DECORATION_BLINK = 1 << 3
} StTextDecoration;
+/**
+ * StTextAlign:
+ * @ST_TEXT_ALIGN_LEFT: Text is aligned at the beginning of the label.
+ * @ST_TEXT_ALIGN_CENTER: Text is aligned in the middle of the label.
+ * @ST_TEXT_ALIGN_RIGHT: Text is aligned at the end of the label.
+ * @ST_GRADIENT_JUSTIFY: Text is justified in the label.
+ *
+ * Used to align text in a label.
+ */
typedef enum {
ST_TEXT_ALIGN_LEFT = PANGO_ALIGN_LEFT,
ST_TEXT_ALIGN_CENTER = PANGO_ALIGN_CENTER,
@@ -80,6 +124,15 @@ typedef enum {
ST_TEXT_ALIGN_JUSTIFY
} StTextAlign;
+/**
+ * StGradientType:
+ * @ST_GRADIENT_NONE: No gradient.
+ * @ST_GRADIENT_VERTICAL: A vertical gradient.
+ * @ST_GRADIENT_HORIZONTAL: A horizontal gradient.
+ * @ST_GRADIENT_RADIAL: Lookup the style requested in the icon name.
+ *
+ * Used to specify options when rendering gradients.
+ */
typedef enum {
ST_GRADIENT_NONE,
ST_GRADIENT_VERTICAL,
@@ -87,6 +140,16 @@ typedef enum {
ST_GRADIENT_RADIAL
} StGradientType;
+/**
+ * StIconStyle:
+ * @ST_ICON_STYLE_REQUESTED: Lookup the style requested in the icon name.
+ * @ST_ICON_STYLE_REGULAR: Try to always load regular icons, even when symbolic
+ * icon names are given.
+ * @ST_ICON_STYLE_SYMBOLIC: Try to always load symbolic icons, even when regular
+ * icon names are given.
+ *
+ * Used to specify options when looking up icons.
+ */
typedef enum {
ST_ICON_STYLE_REQUESTED,
ST_ICON_STYLE_REGULAR,
diff --git a/src/st/st-theme.c b/src/st/st-theme.c
index 3f08833a8a..e9716fe631 100644
--- a/src/st/st-theme.c
+++ b/src/st/st-theme.c
@@ -250,6 +250,16 @@ insert_stylesheet (StTheme *theme,
g_hash_table_insert (theme->files_by_stylesheet, stylesheet, file);
}
+/**
+ * st_theme_load_stylesheet:
+ * @theme: a #StTheme
+ * @file: a #GFile
+ * @error: (optional): a #GError
+ *
+ * Load the stylesheet associated with @file.
+ *
+ * Returns: %TRUE if successful
+ */
gboolean
st_theme_load_stylesheet (StTheme *theme,
GFile *file,
@@ -271,6 +281,14 @@ st_theme_load_stylesheet (StTheme *theme,
return TRUE;
}
+/**
+ * st_theme_unload_stylesheet:
+ * @theme: a #StTheme
+ * @file: a #GFile
+ *
+ * Unload the stylesheet associated with @file. If @file was not loaded this
+ * function does nothing.
+ */
void
st_theme_unload_stylesheet (StTheme *theme,
GFile *file)
@@ -301,6 +319,8 @@ st_theme_unload_stylesheet (StTheme *theme,
* st_theme_get_custom_stylesheets:
* @theme: an #StTheme
*
+ * Get a list of the stylesheet files loaded with st_theme_load_stylesheet().
+ *
* Returns: (transfer full) (element-type GFile): the list of stylesheet files
* that were loaded with st_theme_load_stylesheet()
*/
@@ -461,7 +481,7 @@ st_theme_get_property (GObject *object,
* @default_stylesheet: The lowest priority stylesheet, representing global default styling;
* this is associated with the CSS "user agent" stylesheet, may be %NULL
*
- * Return value: the newly created theme object
+ * Returns: the newly created theme object
**/
StTheme *
st_theme_new (GFile *application_stylesheet,
diff --git a/src/st/st-widget.c b/src/st/st-widget.c
index 29ed553370..bfce545722 100644
--- a/src/st/st-widget.c
+++ b/src/st/st-widget.c
@@ -562,7 +562,7 @@ get_root_theme_node (ClutterStage *stage)
* Note: it is a fatal error to call this on a widget that is
* not been added to a stage.
*
- * Return value: (transfer none): the theme node for the widget.
+ * Returns: (transfer none): the theme node for the widget.
* This is owned by the widget. When attributes of the widget
* or the environment that affect the styling change (for example
* the style_class property of the widget), it will be recreated,
@@ -653,7 +653,7 @@ st_widget_get_theme_node (StWidget *widget)
* node hasn't been computed. If %NULL is returned, then ::style-changed
* will be reliably emitted before the widget is allocated or painted.
*
- * Return value: (transfer none): the theme node for the widget.
+ * Returns: (transfer none): the theme node for the widget.
* This is owned by the widget. When attributes of the widget
* or the environment that affect the styling change (for example
* the style_class property of the widget), it will be recreated,
@@ -949,7 +949,7 @@ st_widget_class_init (StWidgetClass *klass)
ST_PARAM_READWRITE);
/**
- * ClutterActor:label-actor:
+ * StWidget:label-actor:
*
* An actor that labels this widget.
*/
@@ -1006,8 +1006,7 @@ st_widget_class_init (StWidgetClass *klass)
* StWidget::popup-menu:
* @widget: the #StWidget
*
- * Emitted when the user has requested a context menu (eg, via a
- * keybinding)
+ * Emitted when the user has requested a context menu (eg, via a keybinding)
*/
signals[POPUP_MENU] =
g_signal_new ("popup-menu",
@@ -1388,8 +1387,8 @@ st_widget_set_style (StWidget *actor,
*
* Get the current inline style string. See st_widget_set_style().
*
- * Returns: The inline style string, or %NULL. The string is owned by the
- * #StWidget and should not be modified or freed.
+ * Returns: (transfer none) (nullable): The inline style string, or %NULL. The
+ * string is owned by the #StWidget and should not be modified or freed.
*/
const gchar*
st_widget_get_style (StWidget *actor)
@@ -1745,8 +1744,8 @@ st_widget_recompute_style (StWidget *widget,
* st_widget_ensure_style:
* @widget: A #StWidget
*
- * Ensures that @widget has read its style information.
- *
+ * Ensures that @widget has read its style information and propagated any
+ * changes to its children.
*/
void
st_widget_ensure_style (StWidget *widget)
@@ -1808,7 +1807,7 @@ st_widget_set_track_hover (StWidget *widget,
* st_widget_get_track_hover:
* @widget: A #StWidget
*
- * Returns the current value of the track-hover property. See
+ * Returns the current value of the #StWidget:track-hover property. See
* st_widget_set_track_hover() for more information.
*
* Returns: current value of track-hover on @widget
@@ -1942,7 +1941,7 @@ st_widget_get_can_focus (StWidget *widget)
* st_widget_popup_menu:
* @self: A #StWidget
*
- * Asks the widget to pop-up a context menu.
+ * Asks the widget to pop-up a context menu by emitting #StWidget::popup-menu.
*/
void
st_widget_popup_menu (StWidget *self)
@@ -2229,7 +2228,7 @@ st_widget_real_navigate_focus (StWidget *widget,
* time, using a %NULL @from, which should cause it to reset the focus
* to the first available widget in the given direction.
*
- * Return value: %TRUE if clutter_actor_grab_key_focus() has been
+ * Returns: %TRUE if clutter_actor_grab_key_focus() has been
* called on an actor. %FALSE if not.
*/
gboolean
@@ -2275,7 +2274,7 @@ append_actor_text (GString *desc,
* includes the class name and actor name (if any), plus if @actor
* is an #StWidget, its style class and pseudo class names.
*
- * Return value: the debug name.
+ * Returns: the debug name.
*/
char *
st_describe_actor (ClutterActor *actor)
@@ -2350,7 +2349,7 @@ st_describe_actor (ClutterActor *actor)
*
* Gets the label that identifies @widget if it is defined
*
- * Return value: (transfer none): the label that identifies the widget
+ * Returns: (transfer none): the label that identifies the widget
*/
ClutterActor *
st_widget_get_label_actor (StWidget *widget)
@@ -2433,7 +2432,7 @@ st_widget_set_accessible_name (StWidget *widget,
* Gets the accessible name for this widget. See
* st_widget_set_accessible_name() for more information.
*
- * Return value: a character string representing the accessible name
+ * Returns: a character string representing the accessible name
* of the widget.
*/
const gchar *
@@ -2488,7 +2487,7 @@ st_widget_set_accessible_role (StWidget *widget,
* Gets the #AtkRole for this widget. See
* st_widget_set_accessible_role() for more information.
*
- * Return value: accessible #AtkRole for this widget
+ * Returns: accessible #AtkRole for this widget
*/
AtkRole
st_widget_get_accessible_role (StWidget *widget)
diff --git a/src/st/st-widget.h b/src/st/st-widget.h
index 9a4d28fb18..f00c98733f 100644
--- a/src/st/st-widget.h
+++ b/src/st/st-widget.h
@@ -38,6 +38,17 @@ G_BEGIN_DECLS
#define ST_TYPE_WIDGET (st_widget_get_type ())
G_DECLARE_DERIVABLE_TYPE (StWidget, st_widget, ST, WIDGET, ClutterActor)
+/**
+ * StDirectionType:
+ * @ST_DIR_TAB_FORWARD: Move forward.
+ * @ST_DIR_TAB_BACKWARD: Move backward.
+ * @ST_DIR_UP: Move up.
+ * @ST_DIR_DOWN: Move down.
+ * @ST_DIR_LEFT: Move left.
+ * @ST_DIR_RIGHT: Move right.
+ *
+ * Enumeration for focus direction.
+ */
typedef enum
{
ST_DIR_TAB_FORWARD,
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
