StWidget: St Reference Manual

## StWidget StWidget — Base class for stylable actors |

## Functions

void | st_widget_set_style_pseudo_class ()
void | st_widget_add_style_pseudo_class ()
void | st_widget_remove_style_pseudo_class ()
const gchar * | st_widget_get_style_pseudo_class ()
gboolean | st_widget_has_style_pseudo_class ()
void | st_widget_set_style_class_name ()
void | st_widget_add_style_class_name ()
void | st_widget_remove_style_class_name ()
const gchar * | st_widget_get_style_class_name ()
gboolean | st_widget_has_style_class_name ()
void | st_widget_set_style ()
const gchar * | st_widget_get_style ()
void | st_widget_set_theme ()
StTheme * | st_widget_get_theme ()
void | st_widget_set_track_hover ()
gboolean | st_widget_get_track_hover ()
void | st_widget_set_hover ()
void | st_widget_sync_hover ()
gboolean | st_widget_get_hover ()
void | st_widget_popup_menu ()
void | st_widget_ensure_style ()
void | st_widget_set_can_focus ()
gboolean | st_widget_get_can_focus ()
gboolean | st_widget_navigate_focus ()
ClutterActor * | st_widget_get_label_actor ()
void | st_widget_set_label_actor ()
void | st_widget_style_changed ()
StThemeNode * | st_widget_get_theme_node ()
StThemeNode * | st_widget_peek_theme_node ()
GList * | st_widget_get_focus_chain ()
void | st_widget_paint_background ()
char * | st_describe_actor ()
void | st_set_slow_down_factor ()
gfloat | st_get_slow_down_factor ()
void | st_widget_set_accessible_role ()
AtkRole | st_widget_get_accessible_role ()
void | st_widget_add_accessible_state ()
void | st_widget_remove_accessible_state ()
void | st_widget_set_accessible_name ()
const gchar * | st_widget_get_accessible_name ()
void | st_widget_set_accessible ()
void | st_get_align_factors ()

## Properties

gchar * | accessible-name | Read / Write
AtkRole | accessible-role | Read / Write
gboolean | can-focus | Read / Write
gboolean | hover | Read / Write
ClutterActor * | label-actor | Read / Write
gchar * | pseudo-class | Read / Write
gchar * | style | Read / Write
gchar * | style-class | Read / Write
StTheme * | theme | Read / Write
gboolean | track-hover | Read / Write

## Signals

void | popup-menu | Run Last
void | style-changed | Run Last

## Types and Values

struct | StWidget
struct | StWidgetClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── ClutterActor
                ╰── StWidget
                    ├── StBin
                    ├── StBoxLayout
                    ├── StDrawingArea
                    ├── StEntry
                    ├── StIcon
                    ├── StLabel
                    ├── StScrollBar
                    ╰── StTable

## Implemented Interfaces

StWidget implements ClutterContainer, ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

## Description

StWidget is a simple abstract class on top of ClutterActor. It provides basic themeing properties.

Actors in the St library should subclass StWidget if they plan to obey to a certain StStyle.

## Functions

### st_widget_set_style_pseudo_class ()

    void
    st_widget_set_style_pseudo_class (StWidget *actor,
                                      const gchar *pseudo_class_list);

Set the style pseudo class list. `pseudo_class_list` can either be `NULL`, for no classes, or a space-separated list of pseudo class names. See also `st_widget_add_style_pseudo_class()` and `st_widget_remove_style_pseudo_class()`.

#### Parameters

actor | a StWidget |
pseudo_class_list | a new pseudo class list string. | [nullable]

### st_widget_add_style_pseudo_class ()

    void
    st_widget_add_style_pseudo_class (StWidget *actor,
                                      const gchar *pseudo_class);

Adds `pseudo_class` to `actor` 's pseudo class list, if it is not already present.

#### Parameters

actor | a StWidget |
pseudo_class | a pseudo class string |

### st_widget_remove_style_pseudo_class ()

    void
    st_widget_remove_style_pseudo_class (StWidget *actor,
                                         const gchar *pseudo_class);

Removes `pseudo_class` from `actor` 's pseudo class, if it is present.

#### Parameters

actor | a StWidget |
pseudo_class | a pseudo class string |

### st_widget_get_style_pseudo_class ()

    const gchar *
    st_widget_get_style_pseudo_class (StWidget *actor);

Get the current style pseudo class list.

Note that an actor can have multiple pseudo classes; if you just want to test for the presence of a specific pseudo class, use `st_widget_has_style_pseudo_class()`.

#### Parameters

actor | a StWidget |

#### Returns

the pseudo class list string. The string is owned by the StWidget and should not be modified or freed.

### st_widget_has_style_pseudo_class ()

    gboolean
    st_widget_has_style_pseudo_class (StWidget *actor,
                                      const gchar *pseudo_class);

Tests if `actor` 's pseudo class list includes `pseudo_class` .

#### Parameters

actor | a StWidget |
pseudo_class | a pseudo class string |

#### Returns

whether or not `actor` 's pseudo class list includes `pseudo_class` .

### st_widget_set_style_class_name ()

    void
    st_widget_set_style_class_name (StWidget *actor,
                                    const gchar *style_class_list);

Set the style class name list. `style_class_list` can either be `NULL`, for no classes, or a space-separated list of style class names. See also `st_widget_add_style_class_name()` and `st_widget_remove_style_class_name()`.

#### Parameters

actor | a StWidget |
style_class_list | a new style class list string. | [nullable]

### st_widget_add_style_class_name ()

    void
    st_widget_add_style_class_name (StWidget *actor,
                                    const gchar *style_class);

Adds `style_class` to `actor` 's style class name list, if it is not already present.

#### Parameters

actor | a StWidget |
style_class | a style class name string |

### st_widget_remove_style_class_name ()

    void
    st_widget_remove_style_class_name (StWidget *actor,
                                       const gchar *style_class);

Removes `style_class` from `actor` 's style class name, if it is present.

#### Parameters

actor | a StWidget |
style_class | a style class name string |

### st_widget_get_style_class_name ()

    const gchar *
    st_widget_get_style_class_name (StWidget *actor);

Get the current style class name

#### Parameters

actor | a StWidget |

#### Returns

the class name string. The string is owned by the StWidget and should not be modified or freed.

### st_widget_has_style_class_name ()

    gboolean
    st_widget_has_style_class_name (StWidget *actor,
                                    const gchar *style_class);

Tests if `actor` 's style class list includes `style_class` .

#### Parameters

actor | a StWidget |
style_class | a style class string |

#### Returns

whether or not `actor` 's style class list includes `style_class` .

### st_widget_set_style ()

    void
    st_widget_set_style (StWidget *actor,
                         const gchar *style);

Set the inline style string for this widget. The inline style string is an optional ';'-separated list of CSS properties that override the style as determined from the stylesheets of the current theme.

#### Parameters

actor | a StWidget |
style | a inline style string, or `NULL`. | [nullable]

### st_widget_get_style ()

    const gchar *
    st_widget_get_style (StWidget *actor);

Get the current inline style string. See `st_widget_set_style()`.

#### Parameters

actor | a StWidget |

#### Returns

The inline style string, or `NULL`. The string is owned by the StWidget and should not be modified or freed.

### st_widget_set_theme ()

    void
    st_widget_set_theme (StWidget *actor,
                         StTheme *theme);

Overrides the theme that would be inherited from the actor's parent or the stage with an entirely new theme (set of stylesheets).

#### Parameters

actor | a StWidget |
theme | a new style class string |

### st_widget_get_theme ()

    StTheme *
    st_widget_get_theme (StWidget *actor);

Gets the overriding theme set on the actor. See `st_widget_set_theme()`

#### Parameters

actor | a StWidget |

#### Returns

the overriding theme, or `NULL`.

[transfer none]

### st_widget_set_track_hover ()

    void
    st_widget_set_track_hover (StWidget *widget,
                               gboolean track_hover);

Enables hover tracking on the StWidget.

If hover tracking is enabled, and the widget is visible and reactive, then `widget` 's “hover” property will be updated automatically to reflect whether the pointer is in `widget` (or one of its children), and `widget` 's “pseudo-class” will have the "hover" class added and removed from it accordingly.

Note that currently it is not possible to correctly track the hover state when another actor has a pointer grab. You can use `st_widget_sync_hover()` to update the property manually in this case.

#### Parameters

widget | A StWidget |
track_hover | `TRUE` if the widget should track the pointer hover state |

### st_widget_get_track_hover ()

    gboolean
    st_widget_get_track_hover (StWidget *widget);

Returns the current value of the track-hover property. See `st_widget_set_track_hover()` for more information.

#### Parameters

widget | A StWidget |

#### Returns

current value of track-hover on `widget`

### st_widget_set_hover ()

    void
    st_widget_set_hover (StWidget *widget,
                         gboolean hover);

Sets `widget` 's hover property and adds or removes "hover" from its pseudo class accordingly.

If you have set “track-hover”, you should not need to call this directly. You can call `st_widget_sync_hover()` if the hover state might be out of sync due to another actor's pointer grab.

#### Parameters

widget | A StWidget |
hover | whether the pointer is hovering over the widget |

### st_widget_sync_hover ()

    void
    st_widget_sync_hover (StWidget *widget);

Sets `widget` 's hover state according to the current pointer position. This can be used to ensure that it is correct after (or during) a pointer grab.

#### Parameters

widget | A StWidget |

### st_widget_get_hover ()

    gboolean
    st_widget_get_hover (StWidget *widget);

If “track-hover” is set, this returns whether the pointer is currently over the widget.

#### Parameters

widget | A StWidget |

#### Returns

current value of hover on `widget`

### st_widget_popup_menu ()

    void
    st_widget_popup_menu (StWidget *self);

Asks the widget to pop-up a context menu.

#### Parameters

self | A StWidget |

### st_widget_ensure_style ()

    void
    st_widget_ensure_style (StWidget *widget);

Ensures that `widget` has read its style information.

#### Parameters

widget | A StWidget |

### st_widget_set_can_focus ()

    void
    st_widget_set_can_focus (StWidget *widget,
                             gboolean can_focus);

Marks `widget` as being able to receive keyboard focus via keyboard navigation.

#### Parameters

widget | A StWidget |
can_focus | `TRUE` if the widget can receive keyboard focus via keyboard navigation |

### st_widget_get_can_focus ()

    gboolean
    st_widget_get_can_focus (StWidget *widget);

Returns the current value of the can-focus property. See `st_widget_set_can_focus()` for more information.

#### Parameters

widget | A StWidget |

#### Returns

current value of can-focus on `widget`

### st_widget_navigate_focus ()

    gboolean
    st_widget_navigate_focus (StWidget *widget,
                              ClutterActor *from,
                              GtkDirectionType direction,
                              gboolean wrap_around);

Tries to update the keyboard focus within `widget` in response to a keyboard event.

If `from` is a descendant of `widget` , this attempts to move the keyboard focus to the next descendant of `widget` (in the order implied by `direction` ) that has the “can-focus” property set. If `from` is `NULL`, this attempts to focus either `widget` itself, or its first descendant in the order implied by `direction` . If `from` is outside of `widget` , it behaves as if it was a descendant if `direction` is one of the directional arrows and as if it was `NULL` otherwise.

If a container type is marked “can-focus”, the expected behavior is that it will only take up a single slot on the focus chain as a whole, rather than allowing navigation between its child actors (or having a distinction between itself being focused and one of its children being focused).

Some widget classes might have slightly different behavior from the above, where that would make more sense.

If `wrap_around` is `TRUE` and `from` is a child of `widget` , but the widget has no further children that can accept the focus in the given direction, then `st_widget_navigate_focus()` will try a second time, using a `NULL` `from` , which should cause it to reset the focus to the first available widget in the given direction.

#### Parameters

widget | the "top level" container |
from | the actor that the focus is coming from. | [nullable]
direction | the direction focus is moving in |
wrap_around | whether focus should wrap around |

#### Returns

`TRUE` if `clutter_actor_grab_key_focus()` has been called on an actor. `FALSE` if not.

### st_widget_get_label_actor ()

    ClutterActor *
    st_widget_get_label_actor (StWidget *widget);

Gets the label that identifies `widget` if it is defined

#### Parameters

widget | a StWidget |

#### Returns

the label that identifies the widget.

[transfer none]

### st_widget_set_label_actor ()

    void
    st_widget_set_label_actor (StWidget *widget,
                               ClutterActor *label);

Sets `label` as the ClutterActor that identifies (labels) `widget` . `label` can be `NULL` to indicate that `widget` is not labelled any more

#### Parameters

widget | a StWidget |
label | a ClutterActor |

### st_widget_style_changed ()

    void
    st_widget_style_changed (StWidget *widget);

### st_widget_get_theme_node ()

    StThemeNode *
    st_widget_get_theme_node (StWidget *widget);

Gets the theme node holding style information for the widget. The theme node is used to access standard and custom CSS properties of the widget.

Note: it is a fatal error to call this on a widget that is not been added to a stage.

#### Parameters

widget | a StWidget |

#### Returns

the theme node for the widget. This is owned by the widget. When attributes of the widget or the environment that affect the styling change (for example the style_class property of the widget), it will be recreated, and the ::style-changed signal will be emitted on the widget.

[transfer none]

### st_widget_peek_theme_node ()

    StThemeNode *
    st_widget_peek_theme_node (StWidget *widget);

Returns the theme node for the widget if it has already been computed, `NULL` if the widget hasn't been added to a stage or the theme node hasn't been computed. If `NULL` is returned, then ::style-changed will be reliably emitted before the widget is allocated or painted.

#### Parameters

widget | a StWidget |

#### Returns

the theme node for the widget. This is owned by the widget. When attributes of the widget or the environment that affect the styling change (for example the style_class property of the widget), it will be recreated, and the ::style-changed signal will be emitted on the widget.

[transfer none]

### st_widget_get_focus_chain ()

    GList *
    st_widget_get_focus_chain (StWidget *widget);

Gets a list of the focusable children of `widget` , in "Tab" order. By default, this returns all visible (as in `CLUTTER_ACTOR_IS_VISIBLE()`) children of `widget` .

#### Parameters

widget | An StWidget |

#### Returns

`widget` 's focusable children.

[element-type Clutter.Actor][transfer container]

### st_widget_paint_background ()

    void
    st_widget_paint_background (StWidget *widget);

Paint the background of the widget. This is meant to be called by subclasses of StWidget that need to paint the background without painting children.

#### Parameters

widget | The StWidget |

### st_describe_actor ()

    char *
    st_describe_actor (ClutterActor *actor);

Creates a string describing `actor` , for use in debugging. This includes the class name and actor name (if any), plus if `actor` is an StWidget, its style class and pseudo class names.

#### Parameters

actor | a ClutterActor |

#### Returns

the debug name.

### st_set_slow_down_factor ()

    void
    st_set_slow_down_factor (gfloat factor);

Set a global factor applied to all animation durations

#### Parameters

factor | new slow-down factor |

### st_get_slow_down_factor ()

    gfloat
    st_get_slow_down_factor (void);

#### Returns

the global factor applied to all animation durations

### st_widget_set_accessible_role ()

    void
    st_widget_set_accessible_role (StWidget *widget,
                                   AtkRole role);

This method sets `role` as the accessible role for `widget` . This role describes what kind of user interface element `widget` is and is provided so that assistive technologies know how to present `widget` to the user.

Usually you will have no need to set the accessible role for an object, as this information is extracted from the context of the object (ie: a StButton has by default a push button role). This method is only required when you need to redefine the role currently associated with the widget, for instance if it is being used in an unusual way (ie: a StButton used as a togglebutton), or if a generic object is used directly (ie: a container as a menu item).

If `role` is ATK_ROLE_INVALID, the role will not be changed and the accessible's default role will be used instead.

#### Parameters

widget | widget to set the accessible role for |
role | The role to use |

### st_widget_get_accessible_role ()

    AtkRole
    st_widget_get_accessible_role (StWidget *widget);

Gets the AtkRole for this widget. See `st_widget_set_accessible_role()` for more information.

#### Parameters

widget | widget to get the accessible role for |

#### Returns

accessible AtkRole for this widget

### st_widget_add_accessible_state ()

    void
    st_widget_add_accessible_state (StWidget *widget,
                                    AtkStateType state);

This method adds `state` as one of the accessible states for `widget` . The list of states of a widget describes the current state of user interface element `widget` and is provided so that assistive technologies know how to present `widget` to the user.

Usually you will have no need to add accessible states for an object, as the accessible object can extract most of the states from the object itself (ie: a StButton knows when it is pressed). This method is only required when one cannot extract the information automatically from the object itself (i.e.: a generic container used as a toggle menu item will not automatically include the toggled state).

#### Parameters

widget | A StWidget |
state | AtkStateType state to add |

### st_widget_remove_accessible_state ()

    void
    st_widget_remove_accessible_state (StWidget *widget,
                                       AtkStateType state);

This method removes `state` as on of the accessible states for `widget` . See `st_widget_add_accessible_state()` for more information.

#### Parameters

widget | A StWidget |
state | AtkState state to remove |

### st_widget_set_accessible_name ()

    void
    st_widget_set_accessible_name (StWidget *widget,
                                   const gchar *name);

This method sets `name` as the accessible name for `widget` .

Usually you will have no need to set the accessible name for an object, as usually there is a label for most of the interface elements. So in general it is better to just use `st_widget_set_label_actor` . This method is only required when you need to set an accessible name and there is no available label object.

#### Parameters

widget | widget to set the accessible name for |
name | a character string to be set as the accessible name. | [nullable]

### st_widget_get_accessible_name ()

    const gchar *
    st_widget_get_accessible_name (StWidget *widget);

Gets the accessible name for this widget. See `st_widget_set_accessible_name()` for more information.

#### Parameters

widget | widget to get the accessible name for |

#### Returns

a character string representing the accessible name of the widget.

### st_widget_set_accessible ()

    void
    st_widget_set_accessible (StWidget *widget,
                              AtkObject *accessible);

This method allows to set a customly created accessible object to this widget. For example if you define a new subclass of StWidgetAccessible at the javascript code.

NULL is a valid value for `accessible` . That contemplates the hypothetical case of not needing anymore a custom accessible object for the widget. Next call of `st_widget_get_accessible()` would create and return a default accessible.

It assumes that the call to atk_object_initialize that bound the gobject with the custom accessible object was already called, so not a responsibility of this method.

#### Parameters

widget | A StWidget |
accessible | an accessible (AtkObject) |

### st_get_align_factors ()

    void
    st_get_align_factors (StAlign x_align,
                          StAlign y_align,
                          gdouble *x_align_out,
                          gdouble *y_align_out);

Converts `x_align` and `y_align` to gdouble values.

#### Parameters

x_align | an StAlign |
y_align | an StAlign |
x_align_out | `x_align` as a gdouble. | [out][optional]
y_align_out | `y_align` as a gdouble. | [out][optional]

## Types and Values

### struct StWidget

    struct StWidget;

Base class for stylable actors. The contents of the StWidget structure are private and should only be accessed through the public API.

### struct StWidgetClass

    struct StWidgetClass {
    };

Base class for stylable actors.

## Property Details

### The `“accessible-name”` property

      “accessible-name”          gchar *

Object instance's name for assistive technology access.

Flags: Read / Write

Default value: NULL

### The `“accessible-role”` property

      “accessible-role”          AtkRole

The accessible role of this object

Flags: Read / Write

Default value: ATK_ROLE_INVALID

### The `“can-focus”` property

      “can-focus”                gboolean

Whether or not the widget can be focused via keyboard navigation.

Flags: Read / Write

Default value: FALSE

### The `“hover”` property

      “hover”                    gboolean

Whether or not the pointer is currently hovering over the widget. This is only tracked automatically if “track-hover” is `TRUE`, but you can adjust it manually in any case.

Flags: Read / Write

Default value: FALSE

### The `“label-actor”` property

      “label-actor”              ClutterActor *

Label that identifies this widget.

Flags: Read / Write

### The `“pseudo-class”` property

      “pseudo-class”             gchar *

The pseudo-class of the actor. Typical values include "hover", "active", "focus".

Flags: Read / Write

Default value: ""

### The `“style”` property

      “style”                    gchar *

Inline style information for the actor as a ';'-separated list of CSS properties.

Flags: Read / Write

Default value: ""

### The `“style-class”` property

      “style-class”              gchar *

The style-class of the actor for use in styling.

Flags: Read / Write

Default value: ""

### The `“theme”` property

      “theme”                    StTheme *

A theme set on this actor overriding the global theming for this actor and its descendants

Flags: Read / Write

### The `“track-hover”` property

      “track-hover”              gboolean

Determines whether the widget tracks pointer hover state. If `TRUE` (and the widget is visible and reactive), the “hover” property and "hover" style pseudo class will be adjusted automatically as the pointer moves in and out of the widget.

Flags: Read / Write

Default value: FALSE

## Signal Details

### The `“popup-menu”` signal

    void
    user_function (StWidget *widget,
                   gpointer  user_data)

Emitted when the user has requested a context menu (eg, via a keybinding)

#### Parameters

widget | the StWidget |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“style-changed”` signal

    void
    user_function (StWidget *widget,
                   gpointer  user_data)

Emitted when the style information that the widget derives from the theme changes

#### Parameters

widget | the StWidget |
user_data | user data set when the signal handler was connected. |

Flags: Run Last