isa/gnome-shell
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

St Documentation: add and improve documentation for public classes

Browse Source 
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
This commit is contained in:
Andy Holmes 2020-05-20 16:50:09 -07:00 committed by Florian Müllner
parent 8993de76f0
commit 9168f6055e
29 changed files with 1149 additions and 202 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

204
src/st/st-adjustment.c
View File

@ -279,11 +279,23 @@ st_adjustment_class_init (StAdjustmentClass *klass)
object_class->set_property = st_adjustment_set_property; object_class->set_property = st_adjustment_set_property;
object_class->dispose = st_adjustment_dispose; 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] = props[PROP_ACTOR] =
g_param_spec_object ("actor", "Actor", "Actor", g_param_spec_object ("actor", "Actor", "Actor",
CLUTTER_TYPE_ACTOR, CLUTTER_TYPE_ACTOR,
ST_PARAM_READWRITE); ST_PARAM_READWRITE);
/**
* StAdjustment:lower:
*
* The minimum value of the adjustment.
*/
props[PROP_LOWER] = props[PROP_LOWER] =
g_param_spec_double ("lower", "Lower", "Lower bound", g_param_spec_double ("lower", "Lower", "Lower bound",
-G_MAXDOUBLE, G_MAXDOUBLE, 0.0, -G_MAXDOUBLE, G_MAXDOUBLE, 0.0,
@ -291,6 +303,14 @@ st_adjustment_class_init (StAdjustmentClass *klass)
G_PARAM_CONSTRUCT | G_PARAM_CONSTRUCT |
G_PARAM_EXPLICIT_NOTIFY); 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] = props[PROP_UPPER] =
g_param_spec_double ("upper", "Upper", "Upper bound", g_param_spec_double ("upper", "Upper", "Upper bound",
-G_MAXDOUBLE, G_MAXDOUBLE, 0.0, -G_MAXDOUBLE, G_MAXDOUBLE, 0.0,
@ -298,6 +318,11 @@ st_adjustment_class_init (StAdjustmentClass *klass)
G_PARAM_CONSTRUCT | G_PARAM_CONSTRUCT |
G_PARAM_EXPLICIT_NOTIFY); G_PARAM_EXPLICIT_NOTIFY);
/**
* StAdjustment:value:
*
* The value of the adjustment.
*/
props[PROP_VALUE] = props[PROP_VALUE] =
g_param_spec_double ("value", "Value", "Current value", g_param_spec_double ("value", "Value", "Current value",
-G_MAXDOUBLE, G_MAXDOUBLE, 0.0, -G_MAXDOUBLE, G_MAXDOUBLE, 0.0,
@ -305,6 +330,11 @@ st_adjustment_class_init (StAdjustmentClass *klass)
G_PARAM_CONSTRUCT | G_PARAM_CONSTRUCT |
G_PARAM_EXPLICIT_NOTIFY); G_PARAM_EXPLICIT_NOTIFY);
/**
* StAdjustment:step-increment:
*
* The step increment of the adjustment.
*/
props[PROP_STEP_INC] = props[PROP_STEP_INC] =
g_param_spec_double ("step-increment", "Step Increment", "Step increment", g_param_spec_double ("step-increment", "Step Increment", "Step increment",
0.0, G_MAXDOUBLE, 0.0, 0.0, G_MAXDOUBLE, 0.0,
@ -312,6 +342,11 @@ st_adjustment_class_init (StAdjustmentClass *klass)
G_PARAM_CONSTRUCT | G_PARAM_CONSTRUCT |
G_PARAM_EXPLICIT_NOTIFY); G_PARAM_EXPLICIT_NOTIFY);
/**
* StAdjustment:page-increment:
*
* The page increment of the adjustment.
*/
props[PROP_PAGE_INC] = props[PROP_PAGE_INC] =
g_param_spec_double ("page-increment", "Page Increment", "Page increment", g_param_spec_double ("page-increment", "Page Increment", "Page increment",
0.0, G_MAXDOUBLE, 0.0, 0.0, G_MAXDOUBLE, 0.0,
@ -319,6 +354,14 @@ st_adjustment_class_init (StAdjustmentClass *klass)
G_PARAM_CONSTRUCT | G_PARAM_CONSTRUCT |
G_PARAM_EXPLICIT_NOTIFY); 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] = props[PROP_PAGE_SIZE] =
g_param_spec_double ("page-size", "Page Size", "Page size", g_param_spec_double ("page-size", "Page Size", "Page size",
0.0, G_MAXDOUBLE, 0.0, 0.0, G_MAXDOUBLE, 0.0,
@ -350,6 +393,20 @@ st_adjustment_init (StAdjustment *self)
priv->is_constructing = TRUE; 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 * StAdjustment *
st_adjustment_new (ClutterActor *actor, st_adjustment_new (ClutterActor *actor,
gdouble value, gdouble value,
@ -370,6 +427,14 @@ st_adjustment_new (ClutterActor *actor,
NULL); 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 gdouble
st_adjustment_get_value (StAdjustment *adjustment) 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; 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 void
st_adjustment_set_value (StAdjustment *adjustment, st_adjustment_set_value (StAdjustment *adjustment,
gdouble value) 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 void
st_adjustment_clamp_page (StAdjustment *adjustment, st_adjustment_clamp_page (StAdjustment *adjustment,
gdouble lower, gdouble lower,
@ -437,6 +519,23 @@ st_adjustment_clamp_page (StAdjustment *adjustment,
g_object_notify_by_pspec (G_OBJECT (adjustment), props[PROP_VALUE]); 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 static gboolean
st_adjustment_set_lower (StAdjustment *adjustment, st_adjustment_set_lower (StAdjustment *adjustment,
gdouble lower) gdouble lower)
@ -461,6 +560,21 @@ st_adjustment_set_lower (StAdjustment *adjustment,
return FALSE; 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 static gboolean
st_adjustment_set_upper (StAdjustment *adjustment, st_adjustment_set_upper (StAdjustment *adjustment,
gdouble upper) gdouble upper)
@ -485,6 +599,18 @@ st_adjustment_set_upper (StAdjustment *adjustment,
return FALSE; 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 static gboolean
st_adjustment_set_step_increment (StAdjustment *adjustment, st_adjustment_set_step_increment (StAdjustment *adjustment,
gdouble step) gdouble step)
@ -505,6 +631,18 @@ st_adjustment_set_step_increment (StAdjustment *adjustment,
return FALSE; 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 static gboolean
st_adjustment_set_page_increment (StAdjustment *adjustment, st_adjustment_set_page_increment (StAdjustment *adjustment,
gdouble page) gdouble page)
@ -525,6 +663,18 @@ st_adjustment_set_page_increment (StAdjustment *adjustment,
return FALSE; 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 static gboolean
st_adjustment_set_page_size (StAdjustment *adjustment, st_adjustment_set_page_size (StAdjustment *adjustment,
gdouble size) gdouble size)
@ -549,6 +699,23 @@ st_adjustment_set_page_size (StAdjustment *adjustment,
return FALSE; 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 void
st_adjustment_set_values (StAdjustment *adjustment, st_adjustment_set_values (StAdjustment *adjustment,
gdouble value, gdouble value,
@ -593,12 +760,12 @@ st_adjustment_set_values (StAdjustment *adjustment,
/** /**
* st_adjustment_get_values: * st_adjustment_get_values:
* @adjustment: an #StAdjustment * @adjustment: an #StAdjustment
* @value: (out): the current value * @value: (out) (optional): the current value
* @lower: (out): the lower bound * @lower: (out) (optional): the lower bound
* @upper: (out): the upper bound * @upper: (out) (optional): the upper bound
* @step_increment: (out): the step increment * @step_increment: (out) (optional): the step increment
* @page_increment: (out): the page increment * @page_increment: (out) (optional): the page increment
* @page_size: (out): the page size * @page_size: (out) (optional): the page size
* *
* Gets all of @adjustment's values at once. * Gets all of @adjustment's values at once.
*/ */
@ -722,7 +889,13 @@ on_transition_stopped (ClutterTransition *transition,
/** /**
* st_adjustment_get_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 * ClutterTransition *
st_adjustment_get_transition (StAdjustment *adjustment, st_adjustment_get_transition (StAdjustment *adjustment,
@ -745,6 +918,15 @@ st_adjustment_get_transition (StAdjustment *adjustment,
return clos->transition; 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 void
st_adjustment_add_transition (StAdjustment *adjustment, st_adjustment_add_transition (StAdjustment *adjustment,
const char *name, const char *name,
@ -785,6 +967,14 @@ st_adjustment_add_transition (StAdjustment *adjustment,
clutter_timeline_start (CLUTTER_TIMELINE (transition)); 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 void
st_adjustment_remove_transition (StAdjustment *adjustment, st_adjustment_remove_transition (StAdjustment *adjustment,
const char *name) const char *name)

6
src/st/st-bin.c
View File

@ -327,7 +327,7 @@ st_bin_init (StBin *bin)
* *
* Creates a new #StBin, a simple container for one child. * Creates a new #StBin, a simple container for one child.
* *
* Return value: the newly created #StBin actor * Returns: the newly created #StBin actor
*/ */
StWidget * StWidget *
st_bin_new (void) st_bin_new (void)
@ -378,9 +378,9 @@ st_bin_set_child (StBin *bin,
* st_bin_get_child: * st_bin_get_child:
* @bin: a #StBin * @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 * ClutterActor *
st_bin_get_child (StBin *bin) st_bin_get_child (StBin *bin)

38
src/st/st-border-image.c
View File

@ -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 * StBorderImage *
st_border_image_new (GFile *file, st_border_image_new (GFile *file,
int border_top, int border_top,
@ -90,9 +103,11 @@ st_border_image_new (GFile *file,
/** /**
* st_border_image_get_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 * GFile *
st_border_image_get_file (StBorderImage *image) st_border_image_get_file (StBorderImage *image)
@ -102,6 +117,17 @@ st_border_image_get_file (StBorderImage *image)
return image->file; 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 void
st_border_image_get_borders (StBorderImage *image, st_border_image_get_borders (StBorderImage *image,
int *border_top, int *border_top,
@ -123,12 +149,12 @@ st_border_image_get_borders (StBorderImage *image,
/** /**
* st_border_image_equal: * st_border_image_equal:
* @image: a #StBorder_Image * @image: a #StBorderImage
* @other: a different #StBorder_Image * @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 gboolean
st_border_image_equal (StBorderImage *image, st_border_image_equal (StBorderImage *image,

8
src/st/st-box-layout.c
View File

@ -181,8 +181,8 @@ st_box_layout_class_init (StBoxLayoutClass *klass)
/** /**
* StBoxLayout:vertical: * StBoxLayout:vertical:
* *
* A convenience property for getting the #ClutterBoxLayout:vertical * A convenience property for the #ClutterBoxLayout:vertical property of the
* property of the layout for #StBoxLayout. * internal layout for #StBoxLayout.
*/ */
pspec = g_param_spec_boolean ("vertical", pspec = g_param_spec_boolean ("vertical",
"Vertical", "Vertical",
@ -195,8 +195,8 @@ st_box_layout_class_init (StBoxLayoutClass *klass)
/** /**
* StBoxLayout:pack-start: * StBoxLayout:pack-start:
* *
* A convenience property for getting the #ClutterBoxLayout:pack-start * A convenience property for the #ClutterBoxLayout:pack-start property of the
* property of the layout for #StBoxLayout. * internal layout for #StBoxLayout.
*/ */
pspec = g_param_spec_boolean ("pack-start", pspec = g_param_spec_boolean ("pack-start",
"Pack Start", "Pack Start",

49
src/st/st-button.c
View File

@ -484,6 +484,11 @@ st_button_class_init (StButtonClass *klass)
widget_class->style_changed = st_button_style_changed; widget_class->style_changed = st_button_style_changed;
widget_class->get_accessible_type = st_button_accessible_get_type; widget_class->get_accessible_type = st_button_accessible_get_type;
/**
* StButton:label:
*
* The label of the #StButton.
*/
props[PROP_LABEL] = props[PROP_LABEL] =
g_param_spec_string ("label", g_param_spec_string ("label",
"Label", "Label",
@ -491,6 +496,11 @@ st_button_class_init (StButtonClass *klass)
NULL, NULL,
ST_PARAM_READWRITE); ST_PARAM_READWRITE);
/**
* StButton:button-mask:
*
* Which buttons will trigger the #StButton::clicked signal.
*/
props[PROP_BUTTON_MASK] = props[PROP_BUTTON_MASK] =
g_param_spec_flags ("button-mask", g_param_spec_flags ("button-mask",
"Button mask", "Button mask",
@ -498,6 +508,11 @@ st_button_class_init (StButtonClass *klass)
ST_TYPE_BUTTON_MASK, ST_BUTTON_ONE, ST_TYPE_BUTTON_MASK, ST_BUTTON_ONE,
ST_PARAM_READWRITE); ST_PARAM_READWRITE);
/**
* StButton:toggle-mode:
*
* Whether the #StButton is operating in toggle mode (on/off).
*/
props[PROP_TOGGLE_MODE] = props[PROP_TOGGLE_MODE] =
g_param_spec_boolean ("toggle-mode", g_param_spec_boolean ("toggle-mode",
"Toggle Mode", "Toggle Mode",
@ -505,6 +520,15 @@ st_button_class_init (StButtonClass *klass)
FALSE, FALSE,
ST_PARAM_READWRITE); 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] = props[PROP_CHECKED] =
g_param_spec_boolean ("checked", g_param_spec_boolean ("checked",
"Checked", "Checked",
@ -512,6 +536,12 @@ st_button_class_init (StButtonClass *klass)
FALSE, FALSE,
ST_PARAM_READWRITE); 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] = props[PROP_PRESSED] =
g_param_spec_boolean ("pressed", g_param_spec_boolean ("pressed",
"Pressed", "Pressed",
@ -583,9 +613,10 @@ st_button_new_with_label (const gchar *text)
* st_button_get_label: * st_button_get_label:
* @button: a #StButton * @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 * const gchar *
st_button_get_label (StButton *button) st_button_get_label (StButton *button)
@ -598,9 +629,9 @@ st_button_get_label (StButton *button)
/** /**
* st_button_set_label: * st_button_set_label:
* @button: a #Stbutton * @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 void
st_button_set_label (StButton *button, st_button_set_label (StButton *button,
@ -726,7 +757,7 @@ st_button_set_toggle_mode (StButton *button,
* st_button_get_checked: * st_button_get_checked:
* @button: a #StButton * @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 * Returns: %TRUE if the button is checked, or %FALSE if not
*/ */
@ -743,8 +774,8 @@ st_button_get_checked (StButton *button)
* @button: a #Stbutton * @button: a #Stbutton
* @checked: %TRUE or %FALSE * @checked: %TRUE or %FALSE
* *
* Sets the pressed state of the button. This is only really useful if the * Set the #StButton:checked property of the button. This is only really useful
* button has #toggle-mode mode set to %TRUE. * if the button has #StButton:toggle-mode property set to %TRUE.
*/ */
void void
st_button_set_checked (StButton *button, st_button_set_checked (StButton *button,
@ -773,9 +804,9 @@ st_button_set_checked (StButton *button,
* @button: an #StButton * @button: an #StButton
* *
* If this widget is holding a pointer grab, this function will * 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 * 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 * 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 * after the user is holding the mouse button for a given period of

2
src/st/st-button.h
View File

@ -63,7 +63,7 @@ void st_button_fake_release (StButton *button);
* @ST_BUTTON_TWO: button 2 (middle) * @ST_BUTTON_TWO: button 2 (middle)
* @ST_BUTTON_THREE: button 3 (right) * @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 { typedef enum {
ST_BUTTON_ONE = (1 << 0), ST_BUTTON_ONE = (1 << 0),

13
src/st/st-clipboard.c
View File

@ -195,7 +195,6 @@ st_clipboard_get_mimetypes (StClipboard *clipboard,
* *
* Request the data from the clipboard in text form. @callback is executed * Request the data from the clipboard in text form. @callback is executed
* when the data is retreived. * when the data is retreived.
*
*/ */
void void
st_clipboard_get_text (StClipboard *clipboard, 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 * Request the data from the clipboard in #GBytes form. @callback is executed
* when the data is retrieved. * when the data is retrieved.
*
*/ */
void void
st_clipboard_get_content (StClipboard *clipboard, st_clipboard_get_content (StClipboard *clipboard,
@ -287,7 +285,9 @@ st_clipboard_get_content (StClipboard *clipboard,
* @mimetype: content mimetype * @mimetype: content mimetype
* @bytes: content data * @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 void
st_clipboard_set_content (StClipboard *clipboard, st_clipboard_set_content (StClipboard *clipboard,
@ -334,6 +334,13 @@ st_clipboard_set_text (StClipboard *clipboard,
g_bytes_unref (bytes); 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 void
st_clipboard_set_selection (MetaSelection *selection) st_clipboard_set_selection (MetaSelection *selection)
{ {

31
src/st/st-drawing-area.c
View File

@ -150,8 +150,8 @@ st_drawing_area_init (StDrawingArea *area)
* st_drawing_area_queue_repaint: * st_drawing_area_queue_repaint:
* @area: the #StDrawingArea * @area: the #StDrawingArea
* *
* Will cause the actor to emit a ::repaint signal before it is next * Will cause the actor to emit a #StDrawingArea::repaint signal before it is
* drawn to the scene. Useful if some parameters for the area being * next drawn to the scene. Useful if some parameters for the area being
* drawn other than the size or style have changed. Note that * drawn other than the size or style have changed. Note that
* clutter_actor_queue_redraw() will simply result in the same * clutter_actor_queue_redraw() will simply result in the same
* contents being drawn to the scene again. * contents being drawn to the scene again.
@ -169,9 +169,26 @@ st_drawing_area_queue_repaint (StDrawingArea *area)
* @area: the #StDrawingArea * @area: the #StDrawingArea
* *
* Gets the Cairo context to paint to. This function must only be called * Gets the Cairo context to paint to. This function must only be called
* from a signal hander for the ::repaint signal. * from a signal hander or virtual function for the #StDrawingArea::repaint
* signal.
* *
* Return Value: (transfer none): the Cairo context for the paint operation * JavaScript code must call the special dispose function before returning from
* the signal handler or virtual function to avoid leaking memory:
*
* |[<!-- language="JavaScript" -->
* function onRepaint(area) {
* let cr = area.get_context();
*
* // Draw to the context
*
* cr.$dispose();
* }
*
* let area = new St.DrawingArea();
* area.connect('repaint', onRepaint);
* ]|
*
* Returns: (transfer none): the Cairo context for the paint operation
*/ */
cairo_t * cairo_t *
st_drawing_area_get_context (StDrawingArea *area) st_drawing_area_get_context (StDrawingArea *area)
@ -189,12 +206,12 @@ st_drawing_area_get_context (StDrawingArea *area)
/** /**
* st_drawing_area_get_surface_size: * st_drawing_area_get_surface_size:
* @area: the #StDrawingArea * @area: the #StDrawingArea
* @width: (out): location to store the width of the painted area * @width: (out) (optional): location to store the width of the painted area
* @height: (out): location to store the height 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 * 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 * 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 void
st_drawing_area_get_surface_size (StDrawingArea *area, st_drawing_area_get_surface_size (StDrawingArea *area,

116
src/st/st-entry.c
View File

@ -29,14 +29,9 @@
* applications to set further properties. * applications to set further properties.
* *
* #StEntry supports the following pseudo style states: * #StEntry supports the following pseudo style states:
* <itemizedlist> *
* <listitem> * - `focus`: the widget has focus
* <para>focus: the widget has focus</para> * - `indeterminate`: the widget is showing the hint text or actor
* </listitem>
* <listitem>
* <para>indeterminate: the widget is showing the hint text or actor</para>
* </listitem>
* </itemizedlist>
*/ */
#ifdef HAVE_CONFIG_H #ifdef HAVE_CONFIG_H
@ -897,6 +892,11 @@ st_entry_class_init (StEntryClass *klass)
widget_class->navigate_focus = st_entry_navigate_focus; widget_class->navigate_focus = st_entry_navigate_focus;
widget_class->get_accessible_type = st_entry_accessible_get_type; widget_class->get_accessible_type = st_entry_accessible_get_type;
/**
* StEntry:clutter-text:
*
* The internal #ClutterText actor supporting the #StEntry.
*/
props[PROP_CLUTTER_TEXT] = props[PROP_CLUTTER_TEXT] =
g_param_spec_object ("clutter-text", g_param_spec_object ("clutter-text",
"Clutter Text", "Clutter Text",
@ -904,6 +904,11 @@ st_entry_class_init (StEntryClass *klass)
CLUTTER_TYPE_TEXT, CLUTTER_TYPE_TEXT,
ST_PARAM_READABLE); ST_PARAM_READABLE);
/**
* StEntry:primary-icon:
*
* The #ClutterActor acting as the primary icon at the start of the #StEntry.
*/
props[PROP_PRIMARY_ICON] = props[PROP_PRIMARY_ICON] =
g_param_spec_object ("primary-icon", g_param_spec_object ("primary-icon",
"Primary Icon", "Primary Icon",
@ -911,6 +916,11 @@ st_entry_class_init (StEntryClass *klass)
CLUTTER_TYPE_ACTOR, CLUTTER_TYPE_ACTOR,
ST_PARAM_READWRITE); ST_PARAM_READWRITE);
/**
* StEntry:secondary-icon:
*
* The #ClutterActor acting as the secondary icon at the end of the #StEntry.
*/
props[PROP_SECONDARY_ICON] = props[PROP_SECONDARY_ICON] =
g_param_spec_object ("secondary-icon", g_param_spec_object ("secondary-icon",
"Secondary Icon", "Secondary Icon",
@ -918,6 +928,12 @@ st_entry_class_init (StEntryClass *klass)
CLUTTER_TYPE_ACTOR, CLUTTER_TYPE_ACTOR,
ST_PARAM_READWRITE); 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] = props[PROP_HINT_TEXT] =
g_param_spec_string ("hint-text", g_param_spec_string ("hint-text",
"Hint Text", "Hint Text",
@ -926,6 +942,12 @@ st_entry_class_init (StEntryClass *klass)
NULL, NULL,
ST_PARAM_READWRITE); 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] = props[PROP_HINT_ACTOR] =
g_param_spec_object ("hint-actor", g_param_spec_object ("hint-actor",
"Hint Actor", "Hint Actor",
@ -934,6 +956,11 @@ st_entry_class_init (StEntryClass *klass)
CLUTTER_TYPE_ACTOR, CLUTTER_TYPE_ACTOR,
ST_PARAM_READWRITE); ST_PARAM_READWRITE);
/**
* StEntry:text:
*
* The current text value of the #StEntry.
*/
props[PROP_TEXT] = props[PROP_TEXT] =
g_param_spec_string ("text", g_param_spec_string ("text",
"Text", "Text",
@ -941,6 +968,12 @@ st_entry_class_init (StEntryClass *klass)
NULL, NULL,
ST_PARAM_READWRITE); 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] = props[PROP_INPUT_PURPOSE] =
g_param_spec_enum ("input-purpose", g_param_spec_enum ("input-purpose",
"Purpose", "Purpose",
@ -949,6 +982,13 @@ st_entry_class_init (StEntryClass *klass)
CLUTTER_INPUT_CONTENT_PURPOSE_NORMAL, CLUTTER_INPUT_CONTENT_PURPOSE_NORMAL,
ST_PARAM_READWRITE); 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] = props[PROP_INPUT_HINTS] =
g_param_spec_flags ("input-hints", g_param_spec_flags ("input-hints",
"hints", "hints",
@ -964,8 +1004,7 @@ st_entry_class_init (StEntryClass *klass)
* StEntry::primary-icon-clicked: * StEntry::primary-icon-clicked:
* @self: the #StEntry * @self: the #StEntry
* *
* * Emitted when the primary icon is clicked.
* Emitted when the primary icon is clicked
*/ */
entry_signals[PRIMARY_ICON_CLICKED] = entry_signals[PRIMARY_ICON_CLICKED] =
g_signal_new ("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), G_STRUCT_OFFSET (StEntryClass, primary_icon_clicked),
NULL, NULL, NULL, NULL, NULL, NULL,
G_TYPE_NONE, 0); G_TYPE_NONE, 0);
/** /**
* StEntry::secondary-icon-clicked: * StEntry::secondary-icon-clicked:
* @self: the #StEntry * @self: the #StEntry
* *
* Emitted when the secondary icon is clicked * Emitted when the secondary icon is clicked.
*/ */
entry_signals[SECONDARY_ICON_CLICKED] = entry_signals[SECONDARY_ICON_CLICKED] =
g_signal_new ("secondary-icon-clicked", g_signal_new ("secondary-icon-clicked",
@ -1040,9 +1080,9 @@ st_entry_init (StEntry *entry)
/** /**
* st_entry_new: * 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 * Returns: a new #StEntry
*/ */
@ -1063,9 +1103,10 @@ st_entry_new (const gchar *text)
* st_entry_get_text: * st_entry_get_text:
* @entry: a #StEntry * @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 * const gchar *
st_entry_get_text (StEntry *entry) st_entry_get_text (StEntry *entry)
@ -1084,7 +1125,8 @@ st_entry_get_text (StEntry *entry)
* @entry: a #StEntry * @entry: a #StEntry
* @text: (nullable): text to set the entry to * @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 void
st_entry_set_text (StEntry *entry, st_entry_set_text (StEntry *entry,
@ -1106,10 +1148,9 @@ st_entry_set_text (StEntry *entry,
* st_entry_get_clutter_text: * st_entry_get_clutter_text:
* @entry: a #StEntry * @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 * Returns: (transfer none): the #ClutterText used by @entry
* owned by the #StEntry and should not be unref'ed by the application.
*/ */
ClutterActor* ClutterActor*
st_entry_get_clutter_text (StEntry *entry) 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 * @text: (nullable): text to set as the entry hint
* *
* Sets the text to display when the entry is empty and unfocused. When the * 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". * entry is displaying the hint, it has a pseudo class of `indeterminate`.
* A value of NULL unsets the hint. * A value of %NULL unsets the hint.
*/ */
void void
st_entry_set_hint_text (StEntry *entry, st_entry_set_hint_text (StEntry *entry,
@ -1146,10 +1187,13 @@ st_entry_set_hint_text (StEntry *entry,
* st_entry_get_hint_text: * st_entry_get_hint_text:
* @entry: a #StEntry * @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 * Unlike st_entry_get_text() this function may return %NULL if
* #StEntry and should not be freed or modified. * #StEntry:hint-actor is not a #StLabel.
*
* Returns: (nullable) (transfer none): the current value of the hint property
*/ */
const gchar * const gchar *
st_entry_get_hint_text (StEntry *entry) st_entry_get_hint_text (StEntry *entry)
@ -1200,6 +1244,8 @@ st_entry_set_input_purpose (StEntry *entry,
* @entry: a #StEntry * @entry: a #StEntry
* *
* Gets the value of the #StEntry:input-purpose property. * Gets the value of the #StEntry:input-purpose property.
*
* Returns: the input purpose of the entry
*/ */
ClutterInputContentPurpose ClutterInputContentPurpose
st_entry_get_input_purpose (StEntry *entry) st_entry_get_input_purpose (StEntry *entry)
@ -1245,6 +1291,8 @@ st_entry_set_input_hints (StEntry *entry,
* @entry: a #StEntry * @entry: a #StEntry
* *
* Gets the value of the #StEntry:input-hints property. * Gets the value of the #StEntry:input-hints property.
*
* Returns: the input hints for the entry
*/ */
ClutterInputContentHintFlags ClutterInputContentHintFlags
st_entry_get_input_hints (StEntry *entry) st_entry_get_input_hints (StEntry *entry)
@ -1305,7 +1353,7 @@ _st_entry_set_icon (StEntry *entry,
* @entry: a #StEntry * @entry: a #StEntry
* @icon: (nullable): a #ClutterActor * @icon: (nullable): a #ClutterActor
* *
* Set the primary icon of the entry to @icon * Set the primary icon of the entry to @icon.
*/ */
void void
st_entry_set_primary_icon (StEntry *entry, st_entry_set_primary_icon (StEntry *entry,
@ -1324,7 +1372,9 @@ st_entry_set_primary_icon (StEntry *entry,
* st_entry_get_primary_icon: * st_entry_get_primary_icon:
* @entry: a #StEntry * @entry: a #StEntry
* *
* Returns: (transfer none): a #ClutterActor * Get the value of the #StEntry:primary-icon property.
*
* Returns: (nullable) (transfer none): a #ClutterActor
*/ */
ClutterActor * ClutterActor *
st_entry_get_primary_icon (StEntry *entry) st_entry_get_primary_icon (StEntry *entry)
@ -1342,7 +1392,7 @@ st_entry_get_primary_icon (StEntry *entry)
* @entry: a #StEntry * @entry: a #StEntry
* @icon: (nullable): an #ClutterActor * @icon: (nullable): an #ClutterActor
* *
* Set the secondary icon of the entry to @icon * Set the secondary icon of the entry to @icon.
*/ */
void void
st_entry_set_secondary_icon (StEntry *entry, st_entry_set_secondary_icon (StEntry *entry,
@ -1361,7 +1411,9 @@ st_entry_set_secondary_icon (StEntry *entry,
* st_entry_get_secondary_icon: * st_entry_get_secondary_icon:
* @entry: a #StEntry * @entry: a #StEntry
* *
* Returns: (transfer none): a #ClutterActor * Get the value of the #StEntry:secondary-icon property.
*
* Returns: (nullable) (transfer none): a #ClutterActor
*/ */
ClutterActor * ClutterActor *
st_entry_get_secondary_icon (StEntry *entry) st_entry_get_secondary_icon (StEntry *entry)
@ -1377,9 +1429,9 @@ st_entry_get_secondary_icon (StEntry *entry)
/** /**
* st_entry_set_hint_actor: * st_entry_set_hint_actor:
* @entry: a #StEntry * @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 void
st_entry_set_hint_actor (StEntry *entry, st_entry_set_hint_actor (StEntry *entry,
@ -1412,7 +1464,9 @@ st_entry_set_hint_actor (StEntry *entry,
* st_entry_get_hint_actor: * st_entry_get_hint_actor:
* @entry: a #StEntry * @entry: a #StEntry
* *
* Returns: (transfer none): a #ClutterActor * Get the value of the #StEntry:hint-actor property.
*
* Returns: (nullable) (transfer none): a #ClutterActor
*/ */
ClutterActor * ClutterActor *
st_entry_get_hint_actor (StEntry *entry) st_entry_get_hint_actor (StEntry *entry)

4
src/st/st-focus-manager.c
View File

@ -133,7 +133,7 @@ st_focus_manager_stage_event (ClutterActor *stage,
* *
* Gets the #StFocusManager for @stage, creating it if necessary. * 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 * StFocusManager *
st_focus_manager_get_for_stage (ClutterStage *stage) 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 * Checks if @widget is inside a focus group, and if so, returns
* the root of that group. * 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 * @widget is not in a focus group
*/ */
StWidget * StWidget *

18
src/st/st-generic-accessible.c
View File

@ -72,7 +72,7 @@ st_generic_accessible_class_init (StGenericAccessibleClass *klass)
* @self. Right now we only care about doubles, so the value is * @self. Right now we only care about doubles, so the value is
* directly returned by the signal. * 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] = st_generic_accessible_signals[GET_CURRENT_VALUE] =
g_signal_new ("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 * @self. Right now we only care about doubles, so the value is
* directly returned by the signal. * 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] = st_generic_accessible_signals[GET_MAXIMUM_VALUE] =
g_signal_new ("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 * @self. Right now we only care about doubles, so the value is
* directly returned by the signal. * 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] = st_generic_accessible_signals[GET_MINIMUM_VALUE] =
g_signal_new ("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 * @self. Right now we only care about doubles, so the value is
* directly returned by the signal. * 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] = st_generic_accessible_signals[GET_MINIMUM_INCREMENT] =
g_signal_new ("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; 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* AtkObject*
st_generic_accessible_new_for_actor (ClutterActor *actor) st_generic_accessible_new_for_actor (ClutterActor *actor)
{ {

4
src/st/st-icon-colors.c
View File

@ -26,7 +26,7 @@
* *
* Creates a new #StIconColors. All colors are initialized to transparent black. * 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 * StIconColors *
st_icon_colors_new (void) st_icon_colors_new (void)
@ -107,6 +107,8 @@ st_icon_colors_copy (StIconColors *colors)
* @colors: a #StIconColors * @colors: a #StIconColors
* @other: another #StIconColors * @other: another #StIconColors
* *
* Check if two #StIconColors objects are identical.
*
* Returns: %TRUE if the #StIconColors are equal * Returns: %TRUE if the #StIconColors are equal
*/ */
gboolean gboolean

37
src/st/st-icon.c
View File

@ -255,6 +255,11 @@ st_icon_class_init (StIconClass *klass)
widget_class->style_changed = st_icon_style_changed; widget_class->style_changed = st_icon_style_changed;
actor_class->resource_scale_changed = st_icon_resource_scale_changed; actor_class->resource_scale_changed = st_icon_resource_scale_changed;
/**
* StIcon:gicon:
*
* The #GIcon being displayed by this #StIcon.
*/
props[PROP_GICON] = props[PROP_GICON] =
g_param_spec_object ("gicon", g_param_spec_object ("gicon",
"GIcon", "GIcon",
@ -262,6 +267,11 @@ st_icon_class_init (StIconClass *klass)
G_TYPE_ICON, G_TYPE_ICON,
ST_PARAM_READWRITE); ST_PARAM_READWRITE);
/**
* StIcon:fallback-gicon:
*
* The fallback #GIcon to display if #StIcon:gicon fails to load.
*/
props[PROP_FALLBACK_GICON] = props[PROP_FALLBACK_GICON] =
g_param_spec_object ("fallback-gicon", g_param_spec_object ("fallback-gicon",
"Fallback GIcon", "Fallback GIcon",
@ -269,6 +279,11 @@ st_icon_class_init (StIconClass *klass)
G_TYPE_ICON, G_TYPE_ICON,
ST_PARAM_READWRITE); ST_PARAM_READWRITE);
/**
* StIcon:icon-name:
*
* The name of the icon if the icon being displayed is a #GThemedIcon.
*/
props[PROP_ICON_NAME] = props[PROP_ICON_NAME] =
g_param_spec_string ("icon-name", g_param_spec_string ("icon-name",
"Icon name", "Icon name",
@ -276,6 +291,12 @@ st_icon_class_init (StIconClass *klass)
NULL, NULL,
ST_PARAM_READWRITE); 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] = props[PROP_ICON_SIZE] =
g_param_spec_int ("icon-size", g_param_spec_int ("icon-size",
"Icon size", "Icon size",
@ -283,6 +304,12 @@ st_icon_class_init (StIconClass *klass)
-1, G_MAXINT, -1, -1, G_MAXINT, -1,
ST_PARAM_READWRITE); 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] = props[PROP_FALLBACK_ICON_NAME] =
g_param_spec_string ("fallback-icon-name", g_param_spec_string ("fallback-icon-name",
"Fallback icon name", "Fallback icon name",
@ -524,7 +551,7 @@ st_icon_update_icon_size (StIcon *icon)
/** /**
* st_icon_new: * st_icon_new:
* *
* Create a newly allocated #StIcon * Create a newly allocated #StIcon.
* *
* Returns: A newly allocated #StIcon * Returns: A newly allocated #StIcon
*/ */
@ -538,10 +565,10 @@ st_icon_new (void)
* st_icon_get_icon_name: * st_icon_get_icon_name:
* @icon: an #StIcon * @icon: an #StIcon
* *
* This is a convenience method to get the icon name of the #GThemedIcon that * This is a convenience method to get the icon name of the current icon, if it
* is currently set. * 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 * const gchar *
st_icon_get_icon_name (StIcon *icon) st_icon_get_icon_name (StIcon *icon)
@ -592,7 +619,7 @@ st_icon_set_icon_name (StIcon *icon,
* *
* Gets the current #GIcon in use. * 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 * GIcon *
st_icon_get_gicon (StIcon *icon) st_icon_get_gicon (StIcon *icon)

5
src/st/st-image-content.c
View File

@ -329,7 +329,10 @@ g_loadable_icon_interface_init (GLoadableIconIface *iface)
* *
* Creates a new #StImageContent, a simple content for sized images. * 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. * Use g_object_unref() when done.
*/ */
ClutterContent * ClutterContent *

30
src/st/st-label.c
View File

@ -274,6 +274,11 @@ st_label_class_init (StLabelClass *klass)
widget_class->style_changed = st_label_style_changed; widget_class->style_changed = st_label_style_changed;
widget_class->get_accessible_type = st_label_accessible_get_type; widget_class->get_accessible_type = st_label_accessible_get_type;
/**
* StLabel:clutter-text:
*
* The internal #ClutterText actor supporting the label
*/
props[PROP_CLUTTER_TEXT] = props[PROP_CLUTTER_TEXT] =
g_param_spec_object ("clutter-text", g_param_spec_object ("clutter-text",
"Clutter Text", "Clutter Text",
@ -281,6 +286,11 @@ st_label_class_init (StLabelClass *klass)
CLUTTER_TYPE_TEXT, CLUTTER_TYPE_TEXT,
ST_PARAM_READABLE); ST_PARAM_READABLE);
/**
* StLabel:text:
*
* The current text being display in the #StLabel.
*/
props[PROP_TEXT] = props[PROP_TEXT] =
g_param_spec_string ("text", g_param_spec_string ("text",
"Text", "Text",
@ -314,9 +324,9 @@ st_label_init (StLabel *label)
/** /**
* st_label_new: * 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 * Returns: a new #StLabel
*/ */
@ -335,9 +345,10 @@ st_label_new (const gchar *text)
* st_label_get_text: * st_label_get_text:
* @label: a #StLabel * @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 * const gchar *
st_label_get_text (StLabel *label) st_label_get_text (StLabel *label)
@ -350,9 +361,9 @@ st_label_get_text (StLabel *label)
/** /**
* st_label_set_text: * st_label_set_text:
* @label: a #StLabel * @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 void
st_label_set_text (StLabel *label, st_label_set_text (StLabel *label,
@ -382,10 +393,11 @@ st_label_set_text (StLabel *label,
* st_label_get_clutter_text: * st_label_get_clutter_text:
* @label: a #StLabel * @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 * Returns: (transfer none): the #ClutterText used by #StLabel. The actor
* is owned by the #StLabel and should not be unref'ed by the application. * is owned by the #StLabel and should not be destroyed by the application.
*/ */
ClutterActor* ClutterActor*
st_label_get_clutter_text (StLabel *label) st_label_get_clutter_text (StLabel *label)

31
src/st/st-password-entry.c
View File

@ -133,12 +133,23 @@ st_password_entry_class_init (StPasswordEntryClass *klass)
st_entry_class->secondary_icon_clicked = st_password_entry_secondary_icon_clicked; 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", props[PROP_PASSWORD_VISIBLE] = g_param_spec_boolean ("password-visible",
"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, FALSE,
ST_PARAM_READWRITE); 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", props[PROP_SHOW_PEEK_ICON] = g_param_spec_boolean ("show-peek-icon",
"Show peek icon", "Show peek icon",
"Whether to show the password 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: * st_password_entry_set_show_peek_icon:
* @entry: a #StPasswordEntry * @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 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; StPasswordEntryPrivate *priv;
@ -231,6 +245,8 @@ st_password_entry_set_show_peek_icon (StPasswordEntry *entry, gboolean value)
* @entry: a #StPasswordEntry * @entry: a #StPasswordEntry
* *
* Gets whether peek-icon is shown or hidden in the password entry. * Gets whether peek-icon is shown or hidden in the password entry.
*
* Returns: %TRUE if visible
*/ */
gboolean gboolean
st_password_entry_get_show_peek_icon (StPasswordEntry *entry) 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: * st_password_entry_set_password_visible:
* @entry: a #StPasswordEntry * @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. * Sets whether to show or hide text in the password entry.
*/ */
void void
st_password_entry_set_password_visible (StPasswordEntry *entry, gboolean value) st_password_entry_set_password_visible (StPasswordEntry *entry,
gboolean value)
{ {
StPasswordEntryPrivate *priv; StPasswordEntryPrivate *priv;
ClutterActor *clutter_text; ClutterActor *clutter_text;
@ -284,6 +301,8 @@ st_password_entry_set_password_visible (StPasswordEntry *entry, gboolean value)
* @entry: a #StPasswordEntry * @entry: a #StPasswordEntry
* *
* Gets whether the text is masked in the password entry. * Gets whether the text is masked in the password entry.
*
* Returns: %TRUE if visible
*/ */
gboolean gboolean
st_password_entry_get_password_visible (StPasswordEntry *entry) st_password_entry_get_password_visible (StPasswordEntry *entry)

28
src/st/st-scroll-bar.c
View File

@ -538,11 +538,21 @@ st_scroll_bar_class_init (StScrollBarClass *klass)
widget_class->style_changed = st_scroll_bar_style_changed; widget_class->style_changed = st_scroll_bar_style_changed;
/**
* StScrollBar:adjustment:
*
* The #StAdjustment controlling the #StScrollBar.
*/
props[PROP_ADJUSTMENT] = props[PROP_ADJUSTMENT] =
g_param_spec_object ("adjustment", "Adjustment", "The adjustment", g_param_spec_object ("adjustment", "Adjustment", "The adjustment",
ST_TYPE_ADJUSTMENT, ST_TYPE_ADJUSTMENT,
ST_PARAM_READWRITE); ST_PARAM_READWRITE);
/**
* StScrollBar:vertical:
*
* Whether the #StScrollBar is vertical. If %FALSE it is horizontal.
*/
props[PROP_VERTICAL] = props[PROP_VERTICAL] =
g_param_spec_boolean ("vertical", g_param_spec_boolean ("vertical",
"Vertical Orientation", "Vertical Orientation",
@ -552,6 +562,13 @@ st_scroll_bar_class_init (StScrollBarClass *klass)
g_object_class_install_properties (object_class, N_PROPS, props); 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] = signals[SCROLL_START] =
g_signal_new ("scroll-start", g_signal_new ("scroll-start",
G_TYPE_FROM_CLASS (klass), G_TYPE_FROM_CLASS (klass),
@ -560,6 +577,12 @@ st_scroll_bar_class_init (StScrollBarClass *klass)
NULL, NULL, NULL, NULL, NULL, NULL,
G_TYPE_NONE, 0); G_TYPE_NONE, 0);
/**
* StScrollBar::scroll-stop:
* @bar: a #StScrollBar
*
* Emitted when the #StScrollBar finishes scrolling.
*/
signals[SCROLL_STOP] = signals[SCROLL_STOP] =
g_signal_new ("scroll-stop", g_signal_new ("scroll-stop",
G_TYPE_FROM_CLASS (klass), G_TYPE_FROM_CLASS (klass),
@ -982,10 +1005,9 @@ st_scroll_bar_set_adjustment (StScrollBar *bar,
* st_scroll_bar_get_adjustment: * st_scroll_bar_get_adjustment:
* @bar: a #StScrollbar * @bar: a #StScrollbar
* *
* Gets the adjustment object that stores the current position * Gets the #StAdjustment that controls the current position of @bar.
* of the scrollbar.
* *
* Return value: (transfer none): the adjustment * Returns: (transfer none): an #StAdjustment
*/ */
StAdjustment * StAdjustment *
st_scroll_bar_get_adjustment (StScrollBar *bar) st_scroll_bar_get_adjustment (StScrollBar *bar)

24
src/st/st-scroll-view-fade.c
View File

@ -389,6 +389,12 @@ st_scroll_view_fade_class_init (StScrollViewFadeClass *klass)
offscreen_class->create_texture = st_scroll_view_fade_create_texture; offscreen_class->create_texture = st_scroll_view_fade_create_texture;
offscreen_class->paint_target = st_scroll_view_fade_paint_target; 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] = props[PROP_VFADE_OFFSET] =
g_param_spec_float ("vfade-offset", g_param_spec_float ("vfade-offset",
"Vertical Fade Offset", "Vertical Fade Offset",
@ -396,6 +402,12 @@ st_scroll_view_fade_class_init (StScrollViewFadeClass *klass)
0.f, G_MAXFLOAT, DEFAULT_FADE_OFFSET, 0.f, G_MAXFLOAT, DEFAULT_FADE_OFFSET,
ST_PARAM_READWRITE); 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] = props[PROP_HFADE_OFFSET] =
g_param_spec_float ("hfade-offset", g_param_spec_float ("hfade-offset",
"Horizontal Fade Offset", "Horizontal Fade Offset",
@ -403,6 +415,11 @@ st_scroll_view_fade_class_init (StScrollViewFadeClass *klass)
0.f, G_MAXFLOAT, DEFAULT_FADE_OFFSET, 0.f, G_MAXFLOAT, DEFAULT_FADE_OFFSET,
ST_PARAM_READWRITE); ST_PARAM_READWRITE);
/**
* StScrollViewFade:fade-edges:
*
* Whether the faded area should extend to the edges of the #StScrollViewFade.
*/
props[PROP_FADE_EDGES] = props[PROP_FADE_EDGES] =
g_param_spec_boolean ("fade-edges", g_param_spec_boolean ("fade-edges",
"Fade Edges", "Fade Edges",
@ -420,6 +437,13 @@ st_scroll_view_fade_init (StScrollViewFade *self)
self->hfade_offset = DEFAULT_FADE_OFFSET; self->hfade_offset = DEFAULT_FADE_OFFSET;
} }
/**
* st_scroll_view_fade_new:
*
* Create a new #StScrollViewFade.
*
* Returns: (transfer full): a new #StScrollViewFade
*/
ClutterEffect * ClutterEffect *
st_scroll_view_fade_new (void) st_scroll_view_fade_new (void)
{ {

104
src/st/st-scroll-view.c
View File

@ -830,6 +830,11 @@ st_scroll_view_class_init (StScrollViewClass *klass)
widget_class->style_changed = st_scroll_view_style_changed; widget_class->style_changed = st_scroll_view_style_changed;
/**
* StScrollView:hscroll:
*
* The horizontal #StScrollBar for the #StScrollView.
*/
props[PROP_HSCROLL] = props[PROP_HSCROLL] =
g_param_spec_object ("hscroll", g_param_spec_object ("hscroll",
"StScrollBar", "StScrollBar",
@ -837,6 +842,11 @@ st_scroll_view_class_init (StScrollViewClass *klass)
ST_TYPE_SCROLL_BAR, ST_TYPE_SCROLL_BAR,
ST_PARAM_READABLE); ST_PARAM_READABLE);
/**
* StScrollView:vscroll:
*
* The vertical #StScrollBar for the #StScrollView.
*/
props[PROP_VSCROLL] = props[PROP_VSCROLL] =
g_param_spec_object ("vscroll", g_param_spec_object ("vscroll",
"StScrollBar", "StScrollBar",
@ -844,6 +854,11 @@ st_scroll_view_class_init (StScrollViewClass *klass)
ST_TYPE_SCROLL_BAR, ST_TYPE_SCROLL_BAR,
ST_PARAM_READABLE); ST_PARAM_READABLE);
/**
* StScrollView:vscrollbar-policy:
*
* The #StPolicyType for when to show the vertical #StScrollBar.
*/
props[PROP_VSCROLLBAR_POLICY] = props[PROP_VSCROLLBAR_POLICY] =
g_param_spec_enum ("vscrollbar-policy", g_param_spec_enum ("vscrollbar-policy",
"Vertical Scrollbar Policy", "Vertical Scrollbar Policy",
@ -852,6 +867,11 @@ st_scroll_view_class_init (StScrollViewClass *klass)
ST_POLICY_AUTOMATIC, ST_POLICY_AUTOMATIC,
ST_PARAM_READWRITE); ST_PARAM_READWRITE);
/**
* StScrollView:hscrollbar-policy:
*
* The #StPolicyType for when to show the horizontal #StScrollBar.
*/
props[PROP_HSCROLLBAR_POLICY] = props[PROP_HSCROLLBAR_POLICY] =
g_param_spec_enum ("hscrollbar-policy", g_param_spec_enum ("hscrollbar-policy",
"Horizontal Scrollbar Policy", "Horizontal Scrollbar Policy",
@ -860,6 +880,11 @@ st_scroll_view_class_init (StScrollViewClass *klass)
ST_POLICY_AUTOMATIC, ST_POLICY_AUTOMATIC,
ST_PARAM_READWRITE); ST_PARAM_READWRITE);
/**
* StScrollView:hscrollbar-visible:
*
* Whether the horizontal #StScrollBar is visible.
*/
props[PROP_HSCROLLBAR_VISIBLE] = props[PROP_HSCROLLBAR_VISIBLE] =
g_param_spec_boolean ("hscrollbar-visible", g_param_spec_boolean ("hscrollbar-visible",
"Horizontal Scrollbar Visibility", "Horizontal Scrollbar Visibility",
@ -867,6 +892,11 @@ st_scroll_view_class_init (StScrollViewClass *klass)
TRUE, TRUE,
ST_PARAM_READABLE); ST_PARAM_READABLE);
/**
* StScrollView:vscrollbar-visible:
*
* Whether the vertical #StScrollBar is visible.
*/
props[PROP_VSCROLLBAR_VISIBLE] = props[PROP_VSCROLLBAR_VISIBLE] =
g_param_spec_boolean ("vscrollbar-visible", g_param_spec_boolean ("vscrollbar-visible",
"Vertical Scrollbar Visibility", "Vertical Scrollbar Visibility",
@ -874,6 +904,11 @@ st_scroll_view_class_init (StScrollViewClass *klass)
TRUE, TRUE,
ST_PARAM_READABLE); ST_PARAM_READABLE);
/**
* StScrollView:enable-mouse-scrolling:
*
* Whether to enable automatic mouse wheel scrolling.
*/
props[PROP_MOUSE_SCROLL] = props[PROP_MOUSE_SCROLL] =
g_param_spec_boolean ("enable-mouse-scrolling", g_param_spec_boolean ("enable-mouse-scrolling",
"Enable Mouse Scrolling", "Enable Mouse Scrolling",
@ -881,6 +916,11 @@ st_scroll_view_class_init (StScrollViewClass *klass)
TRUE, TRUE,
ST_PARAM_READWRITE); ST_PARAM_READWRITE);
/**
* StScrollView:overlay-scrollbars:
*
* Whether scrollbars are painted on top of the content.
*/
props[PROP_OVERLAY_SCROLLBARS] = props[PROP_OVERLAY_SCROLLBARS] =
g_param_spec_boolean ("overlay-scrollbars", g_param_spec_boolean ("overlay-scrollbars",
"Use Overlay Scrollbars", "Use Overlay Scrollbars",
@ -995,6 +1035,13 @@ clutter_container_iface_init (ClutterContainerIface *iface)
iface->remove = st_scroll_view_remove; iface->remove = st_scroll_view_remove;
} }
/**
* st_scroll_view_new:
*
* Create a new #StScrollView.
*
* Returns: (transfer full): a new #StScrollView
*/
StWidget * StWidget *
st_scroll_view_new (void) st_scroll_view_new (void)
{ {
@ -1005,9 +1052,9 @@ st_scroll_view_new (void)
* st_scroll_view_get_hscroll_bar: * st_scroll_view_get_hscroll_bar:
* @scroll: a #StScrollView * @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 * ClutterActor *
st_scroll_view_get_hscroll_bar (StScrollView *scroll) 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: * st_scroll_view_get_vscroll_bar:
* @scroll: a #StScrollView * @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 * ClutterActor *
st_scroll_view_get_vscroll_bar (StScrollView *scroll) st_scroll_view_get_vscroll_bar (StScrollView *scroll)
@ -1033,6 +1080,14 @@ st_scroll_view_get_vscroll_bar (StScrollView *scroll)
return scroll->priv->vscroll; 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 gfloat
st_scroll_view_get_column_size (StScrollView *scroll) st_scroll_view_get_column_size (StScrollView *scroll)
{ {
@ -1047,6 +1102,13 @@ st_scroll_view_get_column_size (StScrollView *scroll)
return column_size; 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 void
st_scroll_view_set_column_size (StScrollView *scroll, st_scroll_view_set_column_size (StScrollView *scroll,
gfloat column_size) 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 gfloat
st_scroll_view_get_row_size (StScrollView *scroll) st_scroll_view_get_row_size (StScrollView *scroll)
{ {
@ -1083,6 +1153,13 @@ st_scroll_view_get_row_size (StScrollView *scroll)
return row_size; 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 void
st_scroll_view_set_row_size (StScrollView *scroll, st_scroll_view_set_row_size (StScrollView *scroll,
gfloat row_size) 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 void
st_scroll_view_set_mouse_scrolling (StScrollView *scroll, st_scroll_view_set_mouse_scrolling (StScrollView *scroll,
gboolean enabled) 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 gboolean
st_scroll_view_get_mouse_scrolling (StScrollView *scroll) 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: * st_scroll_view_get_overlay_scrollbars:
* @scroll: A #StScrollView * @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 gboolean
st_scroll_view_get_overlay_scrollbars (StScrollView *scroll) st_scroll_view_get_overlay_scrollbars (StScrollView *scroll)

67
src/st/st-scrollable.c
View File

@ -86,6 +86,40 @@ st_scrollable_default_init (StScrollableInterface *g_iface)
if (!initialized) if (!initialized)
{ {
/**
* StScrollable:hadjustment:
*
* The horizontal #StAdjustment used by the #StScrollable.
*
* Implementations should override this property to provide read-write
* access to the #StAdjustment.
*
* JavaScript code may override this as demonstrated below:
*
* |[<!-- language="JavaScript" -->
* var MyScrollable = GObject.registerClass({
* Properties: {
* 'hadjustment': GObject.ParamSpec.override(
* 'hadjustment',
* St.Scrollable
* )
* }
* }, class MyScrollable extends St.Scrollable {
*
* get hadjustment() {
* return this._hadjustment || null;
* }
*
* set hadjustment(adjustment) {
* if (this.hadjustment === adjustment)
* return;
*
* this._hadjustment = adjustment;
* this.notify('hadjustment');
* }
* });
* ]|
*/
g_object_interface_install_property (g_iface, g_object_interface_install_property (g_iface,
g_param_spec_object ("hadjustment", g_param_spec_object ("hadjustment",
"StAdjustment", "StAdjustment",
@ -93,6 +127,17 @@ st_scrollable_default_init (StScrollableInterface *g_iface)
ST_TYPE_ADJUSTMENT, ST_TYPE_ADJUSTMENT,
ST_PARAM_READWRITE)); 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_object_interface_install_property (g_iface,
g_param_spec_object ("vadjustment", g_param_spec_object ("vadjustment",
"StAdjustment", "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 void
st_scrollable_set_adjustments (StScrollable *scrollable, st_scrollable_set_adjustments (StScrollable *scrollable,
StAdjustment *hadjustment, StAdjustment *hadjustment,
@ -116,11 +173,17 @@ st_scrollable_set_adjustments (StScrollable *scrollable,
/** /**
* st_scroll_bar_get_adjustments: * st_scroll_bar_get_adjustments:
* @hadjustment: (transfer none) (out) (optional) (nullable): location to store the horizontal adjustment, or %NULL * @hadjustment: (transfer none) (out) (optional): location to store the horizontal adjustment, or %NULL
* @vadjustment: (transfer none) (out) (optional) (nullable): location to store the vertical 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 * Gets the adjustment objects that store the offsets of the scrollable widget
* into its possible scrolling area. * 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 void
st_scrollable_get_adjustments (StScrollable *scrollable, st_scrollable_get_adjustments (StScrollable *scrollable,

62
src/st/st-settings.c
View File

@ -199,41 +199,89 @@ st_settings_class_init (StSettingsClass *klass)
object_class->set_property = st_settings_set_property; object_class->set_property = st_settings_set_property;
object_class->get_property = st_settings_get_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", props[PROP_ENABLE_ANIMATIONS] = g_param_spec_boolean ("enable-animations",
"Enable animations", "Enable animations",
"Enable animations", "Enable animations",
TRUE, TRUE,
ST_PARAM_READABLE); 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", props[PROP_PRIMARY_PASTE] = g_param_spec_boolean ("primary-paste",
"Primary paste", "Primary paste",
"Primary paste", "Primary paste",
TRUE, TRUE,
ST_PARAM_READABLE); ST_PARAM_READABLE);
/**
* StSettings:drag-threshold:
*
* The threshold before a drag operation begins.
*/
props[PROP_DRAG_THRESHOLD] = g_param_spec_int ("drag-threshold", props[PROP_DRAG_THRESHOLD] = g_param_spec_int ("drag-threshold",
"Drag threshold", "Drag threshold",
"Drag threshold", "Drag threshold",
0, G_MAXINT, 8, 0, G_MAXINT, 8,
ST_PARAM_READABLE); ST_PARAM_READABLE);
/**
* StSettings:font-name:
*
* The current font name.
*/
props[PROP_FONT_NAME] = g_param_spec_string ("font-name", props[PROP_FONT_NAME] = g_param_spec_string ("font-name",
"font name", "font name",
"font name", "font name",
"", "",
ST_PARAM_READABLE); ST_PARAM_READABLE);
/**
* StSettings:gtk-theme:
*
* The current GTK theme.
*/
props[PROP_GTK_THEME] = g_param_spec_string ("gtk-theme", props[PROP_GTK_THEME] = g_param_spec_string ("gtk-theme",
"GTK+ Theme", "GTK Theme",
"GTK+ Theme", "GTK Theme",
"", "",
ST_PARAM_READABLE); ST_PARAM_READABLE);
/**
* StSettings:gtk-icon-theme:
*
* The current GTK icon theme
*/
props[PROP_GTK_ICON_THEME] = g_param_spec_string ("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); ST_PARAM_READABLE);
/**
* StSettings:magnifier-active:
*
* Whether the accessibility magnifier is active.
*/
props[PROP_MAGNIFIER_ACTIVE] = g_param_spec_boolean("magnifier-active", props[PROP_MAGNIFIER_ACTIVE] = g_param_spec_boolean("magnifier-active",
"Magnifier is active", "Magnifier is active",
"Weather the a11y magnifier is active", "Whether the a11y magnifier is active",
FALSE, FALSE,
ST_PARAM_READABLE); 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", props[PROP_SLOW_DOWN_FACTOR] = g_param_spec_double("slow-down-factor",
"Slow down factor", "Slow down factor",
"Factor applied to all animation durations", "Factor applied to all animation durations",
@ -338,9 +386,9 @@ st_settings_init (StSettings *settings)
/** /**
* st_settings_get: * 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 * StSettings *
st_settings_get (void) st_settings_get (void)

9
src/st/st-shadow.c
View File

@ -117,7 +117,7 @@ st_shadow_unref (StShadow *shadow)
* compare non-identically if they differ only by floating point rounding * compare non-identically if they differ only by floating point rounding
* errors. * errors.
* *
* Return value: %TRUE if the two shadows are identical * Returns: %TRUE if the two shadows are identical
*/ */
gboolean gboolean
st_shadow_equal (StShadow *shadow, st_shadow_equal (StShadow *shadow,
@ -216,6 +216,13 @@ st_shadow_helper_new (StShadow *shadow)
return helper; return helper;
} }
/**
* st_shadow_helper_update:
* @helper: a #StShadowHelper
* @source: a #ClutterActor
*
* Update @helper from @source.
*/
void void
st_shadow_helper_update (StShadowHelper *helper, st_shadow_helper_update (StShadowHelper *helper,
ClutterActor *source) ClutterActor *source)

38
src/st/st-texture-cache.c
View File

@ -100,6 +100,12 @@ st_texture_cache_class_init (StTextureCacheClass *klass)
gobject_class->dispose = st_texture_cache_dispose; gobject_class->dispose = st_texture_cache_dispose;
gobject_class->finalize = st_texture_cache_finalize; 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] = signals[ICON_THEME_CHANGED] =
g_signal_new ("icon-theme-changed", g_signal_new ("icon-theme-changed",
G_TYPE_FROM_CLASS (klass), G_TYPE_FROM_CLASS (klass),
@ -108,6 +114,13 @@ st_texture_cache_class_init (StTextureCacheClass *klass)
NULL, NULL, NULL, NULL, NULL, NULL,
G_TYPE_NONE, 0); 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] = signals[TEXTURE_FILE_CHANGED] =
g_signal_new ("texture-file-changed", g_signal_new ("texture-file-changed",
G_TYPE_FROM_CLASS (klass), G_TYPE_FROM_CLASS (klass),
@ -799,7 +812,7 @@ st_texture_cache_free_bind (gpointer data)
/** /**
* st_texture_cache_bind_cairo_surface_property: * st_texture_cache_bind_cairo_surface_property:
* @cache: * @cache: A #StTextureCache
* @object: A #GObject with a property @property_name of type #cairo_surface_t * @object: A #GObject with a property @property_name of type #cairo_surface_t
* @property_name: Name of a property * @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 * If the source object is destroyed, the texture will continue to show the last
* value of the property. * value of the property.
* *
* Return value: (transfer none): A new #GIcon * Returns: (transfer none): A new #GIcon
*/ */
GIcon * GIcon *
st_texture_cache_bind_cairo_surface_property (StTextureCache *cache, st_texture_cache_bind_cairo_surface_property (StTextureCache *cache,
@ -879,7 +892,7 @@ st_texture_cache_load (StTextureCache *cache,
/** /**
* ensure_request: * ensure_request:
* @cache: * @cache: A #StTextureCache
* @key: A cache key * @key: A cache key
* @policy: Cache policy * @policy: Cache policy
* @request: (out): If no request is outstanding, one will be created and returned here * @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: * st_texture_cache_load_gicon:
* @cache: The texture cache instance * @cache: A #StTextureCache
* @theme_node: (nullable): The #StThemeNode to use for colors, or NULL * @theme_node: (nullable): The #StThemeNode to use for colors, or %NULL
* if the icon must not be recolored * if the icon must not be recolored
* @icon: the #GIcon to load * @icon: the #GIcon to load
* @size: Size of themed * @size: Size of themed
@ -944,7 +957,7 @@ ensure_request (StTextureCache *cache,
* icon isn't loaded already, the texture will be filled * icon isn't loaded already, the texture will be filled
* asynchronously. * 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 * ClutterActor *
st_texture_cache_load_gicon (StTextureCache *cache, 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: * 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 * @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_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 * @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 * 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. * 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 * ClutterActor *
st_texture_cache_load_file_async (StTextureCache *cache, st_texture_cache_load_file_async (StTextureCache *cache,
@ -1612,7 +1625,7 @@ static StTextureCache *instance = NULL;
/** /**
* st_texture_cache_get_default: * st_texture_cache_get_default:
* *
* Return value: (transfer none): The global texture cache * Returns: (transfer none): The global texture cache
*/ */
StTextureCache* StTextureCache*
st_texture_cache_get_default (void) st_texture_cache_get_default (void)
@ -1622,6 +1635,13 @@ st_texture_cache_get_default (void)
return instance; 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 gboolean
st_texture_cache_rescan_icon_theme (StTextureCache *cache) st_texture_cache_rescan_icon_theme (StTextureCache *cache)
{ {

28
src/st/st-theme-context.c
View File

@ -118,16 +118,23 @@ st_theme_context_class_init (StThemeContextClass *klass)
/** /**
* StThemeContext:scale-factor: * 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, g_object_class_install_property (object_class,
PROP_SCALE_FACTOR, PROP_SCALE_FACTOR,
g_param_spec_int ("scale-factor", g_param_spec_int ("scale-factor",
"Scale factor", "Scale factor",
"Integer scale factor used for high dpi scaling", "Integer scale factor used for HiDPI scaling",
0, G_MAXINT, 1, 0, G_MAXINT, 1,
ST_PARAM_READWRITE)); 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] = signals[CHANGED] =
g_signal_new ("changed", g_signal_new ("changed",
G_TYPE_FROM_CLASS (klass), 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 * This can be useful in testing scenarios, or if using StThemeContext
* with something other than #ClutterActor objects, but you generally * with something other than #ClutterActor objects, but you generally
* should use st_theme_context_get_for_stage() instead. * should use st_theme_context_get_for_stage() instead.
*
* Returns: (transfer full): a new #StThemeContext
*/ */
StThemeContext * StThemeContext *
st_theme_context_new (void) st_theme_context_new (void)
@ -296,7 +305,7 @@ on_icon_theme_changed (StTextureCache *cache,
* *
* Gets a singleton theme context associated with the stage. * 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 * StThemeContext *
st_theme_context_get_for_stage (ClutterStage *stage) 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: * st_theme_context_set_theme:
* @context: a #StThemeContext * @context: a #StThemeContext
* @theme: a #StTheme
* *
* Sets the default set of theme stylesheets for the context. This theme will * 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 * 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() * 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 * StTheme *
st_theme_context_get_theme (StThemeContext *context) 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 * 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 * 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 * 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. * modification is based on this font.
*/ */
void 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(). * 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 * const PangoFontDescription *
st_theme_context_get_font (StThemeContext *context) 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 * context. For the node tree associated with a stage, this node represents
* styles applied to the stage itself. * 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 * StThemeNode *
st_theme_context_get_root_node (StThemeContext *context) 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, * Return an existing node matching @node, or if that isn't possible,
* @node itself. * @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 * StThemeNode *
st_theme_context_intern_node (StThemeContext *context, 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 the current scale factor of @context.
* *
* Return value: a scale factor * Returns: an integer scale factor
*/ */
int int
st_theme_context_get_scale_factor (StThemeContext *context) st_theme_context_get_scale_factor (StThemeContext *context)

260
src/st/st-theme-node.c
View File

@ -180,11 +180,11 @@ split_on_whitespace (const gchar *s)
* @pseudo_class: (nullable): a whitespace-separated list of pseudo-classes * @pseudo_class: (nullable): a whitespace-separated list of pseudo-classes
* (like 'hover' or 'visited') to match CSS rules against * (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 * of the attributes of the node (like the @element_class) change the node
* and its child nodes must be destroyed and recreated. * and its child nodes must be destroyed and recreated.
* *
* Return value: (transfer full): the theme node * Returns: (transfer full): a new #StThemeNode
*/ */
StThemeNode * StThemeNode *
st_theme_node_new (StThemeContext *context, st_theme_node_new (StThemeContext *context,
@ -229,8 +229,8 @@ st_theme_node_new (StThemeContext *context,
* *
* Gets the parent themed element node. * Gets the parent themed element node.
* *
* Return value: (transfer none): the parent #StThemeNode, or %NULL if this * Returns: (nullable) (transfer none): the parent #StThemeNode, or %NULL if
* is the root node of the tree of theme elements. * this is the root node of the tree of theme elements.
*/ */
StThemeNode * StThemeNode *
st_theme_node_get_parent (StThemeNode *node) 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 * 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 * StTheme *
st_theme_node_get_theme (StThemeNode *node) st_theme_node_get_theme (StThemeNode *node)
@ -256,6 +256,14 @@ st_theme_node_get_theme (StThemeNode *node)
return node->theme; return node->theme;
} }
/**
* st_theme_node_get_element_type:
* @node: a #StThemeNode
*
* Get the element #GType for @node.
*
* Returns: the element type
*/
GType GType
st_theme_node_get_element_type (StThemeNode *node) st_theme_node_get_element_type (StThemeNode *node)
{ {
@ -264,6 +272,14 @@ st_theme_node_get_element_type (StThemeNode *node)
return node->element_type; 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 * const char *
st_theme_node_get_element_id (StThemeNode *node) 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: * st_theme_node_get_element_classes:
* @node: a #StThemeNode
*
* Get the list of element classes for @node.
* *
* Returns: (transfer none): the element's classes * 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: * 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 * 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 * the same CSS rules and have the same style properties. However, two
* nodes that have ended up with identical style properties do not * nodes that have ended up with identical style properties do not
* necessarily compare equal. * necessarily compare equal.
* In detail, @node_a and @node_b are considered equal iff *
* <itemizedlist> * In detail, @node_a and @node_b are considered equal if and only if:
* <listitem> *
* <para>they share the same #StTheme and #StThemeContext</para> * - they share the same #StTheme and #StThemeContext
* </listitem> * - they have the same parent
* <listitem> * - they have the same element type
* <para>they have the same parent</para> * - their id, class, pseudo-class and inline-style match
* </listitem>
* <listitem>
* <para>they have the same element type</para>
* </listitem>
* <listitem>
* <para>their id, class, pseudo-class and inline-style match</para>
* </listitem>
* </itemizedlist>
* *
* Returns: %TRUE if @node_a equals @node_b * Returns: %TRUE if @node_a equals @node_b
*/ */
@ -383,6 +397,14 @@ st_theme_node_equal (StThemeNode *node_a, StThemeNode *node_b)
return TRUE; return TRUE;
} }
/**
* st_theme_node_hash:
* @node: a #StThemeNode
*
* Converts @node to a hash value.
*
* Returns: a hash value corresponding to @node
*/
guint guint
st_theme_node_hash (StThemeNode *node) 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. * 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.) * theme node (or in the properties of parent nodes when inheriting.)
*/ */
gboolean gboolean
@ -727,7 +749,7 @@ st_theme_node_get_color (StThemeNode *node,
* *
* See also st_theme_node_get_double(), which provides a simpler API. * 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.) * theme node (or in the properties of parent nodes when inheriting.)
*/ */
gboolean gboolean
@ -780,7 +802,7 @@ st_theme_node_lookup_double (StThemeNode *node,
* Generically looks up a property containing a single time value, * Generically looks up a property containing a single time value,
* which is converted to milliseconds. * 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.) * theme node (or in the properties of parent nodes when inheriting.)
*/ */
gboolean 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 * and lets you handle the case where the theme does not specify the
* indicated value. * 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. * found, a warning will be logged and 0 will be returned.
*/ */
gdouble gdouble
@ -872,7 +894,7 @@ st_theme_node_get_double (StThemeNode *node,
* *
* See also st_theme_node_get_url(), which provides a simpler API. * 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.) * theme node (or in the properties of parent nodes when inheriting.)
*/ */
gboolean 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 * and lets you handle the case where the theme does not specify the
* indicated value. * 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 * If @property_name is not found, a warning will be logged and %NULL
* will be returned. * will be returned.
*/ */
@ -1169,7 +1191,7 @@ get_length_internal (StThemeNode *node,
* *
* See also st_theme_node_get_length(), which provides a simpler API. * 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.) * theme node (or in the properties of parent nodes when inheriting.)
*/ */
gboolean 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 * this does not print a warning if the property is not found; it just
* returns 0. * 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 gdouble
st_theme_node_get_length (StThemeNode *node, st_theme_node_get_length (StThemeNode *node,
@ -1807,6 +1830,15 @@ _st_theme_node_ensure_geometry (StThemeNode *node)
node->height = node->min_height; 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 int
st_theme_node_get_border_width (StThemeNode *node, st_theme_node_get_border_width (StThemeNode *node,
StSide side) StSide side)
@ -1819,6 +1851,15 @@ st_theme_node_get_border_width (StThemeNode *node,
return node->border_width[side]; 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 int
st_theme_node_get_border_radius (StThemeNode *node, st_theme_node_get_border_radius (StThemeNode *node,
StCorner corner) StCorner corner)
@ -1831,6 +1872,14 @@ st_theme_node_get_border_radius (StThemeNode *node,
return node->border_radius[corner]; 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 int
st_theme_node_get_outline_width (StThemeNode *node) st_theme_node_get_outline_width (StThemeNode *node)
{ {
@ -1859,6 +1908,14 @@ st_theme_node_get_outline_color (StThemeNode *node,
*color = node->outline_color; *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 int
st_theme_node_get_width (StThemeNode *node) st_theme_node_get_width (StThemeNode *node)
{ {
@ -1868,6 +1925,14 @@ st_theme_node_get_width (StThemeNode *node)
return node->width; 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 int
st_theme_node_get_height (StThemeNode *node) st_theme_node_get_height (StThemeNode *node)
{ {
@ -1877,6 +1942,14 @@ st_theme_node_get_height (StThemeNode *node)
return node->height; 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 int
st_theme_node_get_min_width (StThemeNode *node) st_theme_node_get_min_width (StThemeNode *node)
{ {
@ -1886,6 +1959,14 @@ st_theme_node_get_min_width (StThemeNode *node)
return node->min_width; 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 int
st_theme_node_get_min_height (StThemeNode *node) st_theme_node_get_min_height (StThemeNode *node)
{ {
@ -1895,6 +1976,14 @@ st_theme_node_get_min_height (StThemeNode *node)
return node->min_height; 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 int
st_theme_node_get_max_width (StThemeNode *node) st_theme_node_get_max_width (StThemeNode *node)
{ {
@ -1904,6 +1993,14 @@ st_theme_node_get_max_width (StThemeNode *node)
return node->max_width; 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 int
st_theme_node_get_max_height (StThemeNode *node) 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]; *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 double
st_theme_node_get_padding (StThemeNode *node, st_theme_node_get_padding (StThemeNode *node,
StSide side) StSide side)
@ -2282,6 +2389,16 @@ st_theme_node_get_padding (StThemeNode *node,
return node->padding[side]; 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 double
st_theme_node_get_margin (StThemeNode *node, st_theme_node_get_margin (StThemeNode *node,
StSide side) StSide side)
@ -2326,6 +2443,15 @@ st_theme_node_get_transition_duration (StThemeNode *node)
return factor * node->transition_duration; 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 StIconStyle
st_theme_node_get_icon_style (StThemeNode *node) 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; 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 StTextDecoration
st_theme_node_get_text_decoration (StThemeNode *node) st_theme_node_get_text_decoration (StThemeNode *node)
{ {
@ -2435,6 +2569,14 @@ st_theme_node_get_text_decoration (StThemeNode *node)
return 0; 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 StTextAlign
st_theme_node_get_text_align(StThemeNode *node) 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: * st_theme_node_get_letter_spacing:
* @node: a #StThemeNode * @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. * found, or zero if such property has not been found.
*/ */
gdouble gdouble
@ -2763,6 +2905,14 @@ font_variant_from_term (CRTerm *term,
return TRUE; 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 * const PangoFontDescription *
st_theme_node_get_font (StThemeNode *node) st_theme_node_get_font (StThemeNode *node)
{ {
@ -2956,6 +3106,14 @@ st_theme_node_get_font (StThemeNode *node)
return node->font_desc; 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 * gchar *
st_theme_node_get_font_features (StThemeNode *node) 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 * 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. * if there is no border image.
*/ */
StBorderImage * StBorderImage *
@ -3132,10 +3290,9 @@ st_theme_node_get_border_image (StThemeNode *node)
* st_theme_node_get_horizontal_padding: * st_theme_node_get_horizontal_padding:
* @node: a #StThemeNode * @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 * Returns: the total horizonal padding in physical pixels
* in pixels
*/ */
double double
st_theme_node_get_horizontal_padding (StThemeNode *node) 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: * st_theme_node_get_vertical_padding:
* @node: a #StThemeNode * @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 * Returns: the total vertical padding in physical pixels
* in pixels
*/ */
double double
st_theme_node_get_vertical_padding (StThemeNode *node) st_theme_node_get_vertical_padding (StThemeNode *node)
@ -3317,7 +3473,7 @@ parse_shadow_property (StThemeNode *node,
* *
* See also st_theme_node_get_shadow(), which provides a simpler API. * 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 * Returns: %TRUE if the property was found in the properties for this
* theme node (or in the properties of parent nodes when inheriting.), %FALSE * theme node (or in the properties of parent nodes when inheriting.), %FALSE
* if the property was not found, or was explicitly set to 'none'. * if the property was not found, or was explicitly set to 'none'.
*/ */
@ -3402,7 +3558,8 @@ st_theme_node_lookup_shadow (StThemeNode *node,
* *
* See also st_theme_node_lookup_shadow (), which provides more options. * 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 * StShadow *
st_theme_node_get_shadow (StThemeNode *node, 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 * 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 * if node has no shadow
*/ */
StShadow * StShadow *
@ -3455,8 +3612,8 @@ st_theme_node_get_box_shadow (StThemeNode *node)
* *
* Gets the value for the -st-background-image-shadow style property * Gets the value for the -st-background-image-shadow style property
* *
* Return value: (transfer none): the node's background image shadow, or %NULL * Returns: (nullable) (transfer none): the node's background image shadow, or
* if node has no such shadow * %NULL if node has no such shadow
*/ */
StShadow * StShadow *
st_theme_node_get_background_image_shadow (StThemeNode *node) 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 * 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 * if node has no text-shadow
*/ */
StShadow * 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 * Gets the colors that should be used for colorizing symbolic icons according
* the style of this node. * 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 * StIconColors *
st_theme_node_get_icon_colors (StThemeNode *node) 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 * 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 * used to optimize having to relayout when the style applied to a Clutter
* actor changes colors without changing the geometry. * actor changes colors without changing the geometry.
*
* Returns: %TRUE if equal, %FALSE otherwise
*/ */
gboolean gboolean
st_theme_node_geometry_equal (StThemeNode *node, 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 * for @other. Note that in some cases this function may return %TRUE even
* if there is no visible difference in the painting. * 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. * two nodes potentially paint differently.
*/ */
gboolean gboolean
@ -4077,6 +4236,15 @@ st_theme_node_paint_equal (StThemeNode *node,
return TRUE; 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 * gchar *
st_theme_node_to_string (StThemeNode *node) st_theme_node_to_string (StThemeNode *node)
{ {

63
src/st/st-theme-node.h
View File

@ -43,6 +43,11 @@ G_BEGIN_DECLS
* accessors for standard CSS properties that add caching and handling of various * accessors for standard CSS properties that add caching and handling of various
* details of the CSS specification. #StThemeNode also has convenience functions to help * details of the CSS specification. #StThemeNode also has convenience functions to help
* in implementing a #ClutterActor with borders and padding. * 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; typedef struct _StTheme StTheme;
@ -51,6 +56,15 @@ typedef struct _StThemeContext StThemeContext;
#define ST_TYPE_THEME_NODE (st_theme_node_get_type ()) #define ST_TYPE_THEME_NODE (st_theme_node_get_type ())
G_DECLARE_FINAL_TYPE (StThemeNode, st_theme_node, ST, THEME_NODE, GObject) 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 { typedef enum {
ST_SIDE_TOP, ST_SIDE_TOP,
ST_SIDE_RIGHT, ST_SIDE_RIGHT,
@ -58,6 +72,15 @@ typedef enum {
ST_SIDE_LEFT ST_SIDE_LEFT
} StSide; } 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 { typedef enum {
ST_CORNER_TOPLEFT, ST_CORNER_TOPLEFT,
ST_CORNER_TOPRIGHT, ST_CORNER_TOPRIGHT,
@ -66,6 +89,18 @@ typedef enum {
} StCorner; } StCorner;
/* These are the CSS values; that doesn't mean we have to implement blink... */ /* 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 { typedef enum {
ST_TEXT_DECORATION_UNDERLINE = 1 << 0, ST_TEXT_DECORATION_UNDERLINE = 1 << 0,
ST_TEXT_DECORATION_OVERLINE = 1 << 1, ST_TEXT_DECORATION_OVERLINE = 1 << 1,
@ -73,6 +108,15 @@ typedef enum {
ST_TEXT_DECORATION_BLINK = 1 << 3 ST_TEXT_DECORATION_BLINK = 1 << 3
} StTextDecoration; } 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 { typedef enum {
ST_TEXT_ALIGN_LEFT = PANGO_ALIGN_LEFT, ST_TEXT_ALIGN_LEFT = PANGO_ALIGN_LEFT,
ST_TEXT_ALIGN_CENTER = PANGO_ALIGN_CENTER, ST_TEXT_ALIGN_CENTER = PANGO_ALIGN_CENTER,
@ -80,6 +124,15 @@ typedef enum {
ST_TEXT_ALIGN_JUSTIFY ST_TEXT_ALIGN_JUSTIFY
} StTextAlign; } 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 { typedef enum {
ST_GRADIENT_NONE, ST_GRADIENT_NONE,
ST_GRADIENT_VERTICAL, ST_GRADIENT_VERTICAL,
@ -87,6 +140,16 @@ typedef enum {
ST_GRADIENT_RADIAL ST_GRADIENT_RADIAL
} StGradientType; } 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 { typedef enum {
ST_ICON_STYLE_REQUESTED, ST_ICON_STYLE_REQUESTED,
ST_ICON_STYLE_REGULAR, ST_ICON_STYLE_REGULAR,

22
src/st/st-theme.c
View File

@ -250,6 +250,16 @@ insert_stylesheet (StTheme *theme,
g_hash_table_insert (theme->files_by_stylesheet, stylesheet, file); 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 gboolean
st_theme_load_stylesheet (StTheme *theme, st_theme_load_stylesheet (StTheme *theme,
GFile *file, GFile *file,
@ -271,6 +281,14 @@ st_theme_load_stylesheet (StTheme *theme,
return TRUE; 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 void
st_theme_unload_stylesheet (StTheme *theme, st_theme_unload_stylesheet (StTheme *theme,
GFile *file) GFile *file)
@ -301,6 +319,8 @@ st_theme_unload_stylesheet (StTheme *theme,
* st_theme_get_custom_stylesheets: * st_theme_get_custom_stylesheets:
* @theme: an #StTheme * @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 * Returns: (transfer full) (element-type GFile): the list of stylesheet files
* that were loaded with st_theme_load_stylesheet() * 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; * @default_stylesheet: The lowest priority stylesheet, representing global default styling;
* this is associated with the CSS "user agent" stylesheet, may be %NULL * 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 * StTheme *
st_theme_new (GFile *application_stylesheet, st_theme_new (GFile *application_stylesheet,

31
src/st/st-widget.c
View File

@ -562,7 +562,7 @@ get_root_theme_node (ClutterStage *stage)
* Note: it is a fatal error to call this on a widget that is * Note: it is a fatal error to call this on a widget that is
* not been added to a stage. * 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 * This is owned by the widget. When attributes of the widget
* or the environment that affect the styling change (for example * or the environment that affect the styling change (for example
* the style_class property of the widget), it will be recreated, * 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 * node hasn't been computed. If %NULL is returned, then ::style-changed
* will be reliably emitted before the widget is allocated or painted. * 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 * This is owned by the widget. When attributes of the widget
* or the environment that affect the styling change (for example * or the environment that affect the styling change (for example
* the style_class property of the widget), it will be recreated, * the style_class property of the widget), it will be recreated,
@ -949,7 +949,7 @@ st_widget_class_init (StWidgetClass *klass)
ST_PARAM_READWRITE); ST_PARAM_READWRITE);
/** /**
* ClutterActor:label-actor: * StWidget:label-actor:
* *
* An actor that labels this widget. * An actor that labels this widget.
*/ */
@ -1006,8 +1006,7 @@ st_widget_class_init (StWidgetClass *klass)
* StWidget::popup-menu: * StWidget::popup-menu:
* @widget: the #StWidget * @widget: the #StWidget
* *
* Emitted when the user has requested a context menu (eg, via a * Emitted when the user has requested a context menu (eg, via a keybinding)
* keybinding)
*/ */
signals[POPUP_MENU] = signals[POPUP_MENU] =
g_signal_new ("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(). * Get the current inline style string. See st_widget_set_style().
* *
* Returns: The inline style string, or %NULL. The string is owned by the * Returns: (transfer none) (nullable): The inline style string, or %NULL. The
* #StWidget and should not be modified or freed. * string is owned by the #StWidget and should not be modified or freed.
*/ */
const gchar* const gchar*
st_widget_get_style (StWidget *actor) st_widget_get_style (StWidget *actor)
@ -1745,8 +1744,8 @@ st_widget_recompute_style (StWidget *widget,
* st_widget_ensure_style: * st_widget_ensure_style:
* @widget: A #StWidget * @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 void
st_widget_ensure_style (StWidget *widget) st_widget_ensure_style (StWidget *widget)
@ -1808,7 +1807,7 @@ st_widget_set_track_hover (StWidget *widget,
* st_widget_get_track_hover: * st_widget_get_track_hover:
* @widget: A #StWidget * @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. * st_widget_set_track_hover() for more information.
* *
* Returns: current value of track-hover on @widget * Returns: current value of track-hover on @widget
@ -1942,7 +1941,7 @@ st_widget_get_can_focus (StWidget *widget)
* st_widget_popup_menu: * st_widget_popup_menu:
* @self: A #StWidget * @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 void
st_widget_popup_menu (StWidget *self) 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 * time, using a %NULL @from, which should cause it to reset the focus
* to the first available widget in the given direction. * 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. * called on an actor. %FALSE if not.
*/ */
gboolean gboolean
@ -2275,7 +2274,7 @@ append_actor_text (GString *desc,
* includes the class name and actor name (if any), plus if @actor * includes the class name and actor name (if any), plus if @actor
* is an #StWidget, its style class and pseudo class names. * is an #StWidget, its style class and pseudo class names.
* *
* Return value: the debug name. * Returns: the debug name.
*/ */
char * char *
st_describe_actor (ClutterActor *actor) st_describe_actor (ClutterActor *actor)
@ -2350,7 +2349,7 @@ st_describe_actor (ClutterActor *actor)
* *
* Gets the label that identifies @widget if it is defined * 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 * ClutterActor *
st_widget_get_label_actor (StWidget *widget) 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 * Gets the accessible name for this widget. See
* st_widget_set_accessible_name() for more information. * 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. * of the widget.
*/ */
const gchar * const gchar *
@ -2488,7 +2487,7 @@ st_widget_set_accessible_role (StWidget *widget,
* Gets the #AtkRole for this widget. See * Gets the #AtkRole for this widget. See
* st_widget_set_accessible_role() for more information. * st_widget_set_accessible_role() for more information.
* *
* Return value: accessible #AtkRole for this widget * Returns: accessible #AtkRole for this widget
*/ */
AtkRole AtkRole
st_widget_get_accessible_role (StWidget *widget) st_widget_get_accessible_role (StWidget *widget)

11
src/st/st-widget.h
View File

@ -38,6 +38,17 @@ G_BEGIN_DECLS
#define ST_TYPE_WIDGET (st_widget_get_type ()) #define ST_TYPE_WIDGET (st_widget_get_type ())
G_DECLARE_DERIVABLE_TYPE (StWidget, st_widget, ST, WIDGET, ClutterActor) 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 typedef enum
{ {
ST_DIR_TAB_FORWARD, ST_DIR_TAB_FORWARD,