From 9168f6055ea0b417f8beb64eefc18e5f904a9191 Mon Sep 17 00:00:00 2001 From: Andy Holmes Date: Wed, 20 May 2020 16:50:09 -0700 Subject: [PATCH] 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 eb170488f..e08d0afc4 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 4d7c705c3..2eadd57ed 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 d7bd03d30..ee09d0265 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 a31f72772..895e688ac 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 c2c48a510..0e440fa53 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 df0d1ea0c..6040e4182 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 82ea80235..4673a7888 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 3f916e8a3..1ab48c878 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: + * + * |[ + * 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 10dfe1dd1..fdf0168c9 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: - * - * - * focus: the widget has focus - * - * - * indeterminate: the widget is showing the hint text or actor - * - * + * + * - `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 0753d7902..1ac6d28b8 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 982e81433..e6cb393d8 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 8c5b8d35a..f20a25c7e 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 d6a6c4c22..f35cb96bb 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 84f4918c7..92f1c1415 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 9c4ad31d4..54f16b155 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 7c240a525..80df97955 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 0bc4769a5..59e9ca820 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 656fa322f..30b5a4c79 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 349c8c840..6af6a9519 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 234318274..93f06c122 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: + * + * |[ + * 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 5ce73d015..0ece3ccef 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 f3a22f034..96e654fda 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 0359534e2..947d8fc89 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 f10737b80..6d8c90d15 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 ca9675895..cbfc9d064 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 - * - * - * 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 - * - * + * + * 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 53c0ad05d..520e29f4f 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 3f08833a8..e9716fe63 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 29ed55337..bfce54572 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 9a4d28fb1..f00c98733 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,