## StWidget

StWidget — Base class for stylable actors

## Synopsis

    enum                StTextDirection;
    struct              StWidget;
    struct              StWidgetClass;
    char *              st_describe_actor                   (ClutterActor *actor);
    gfloat              st_get_slow_down_factor             (void);
    ClutterContainer *  st_get_ui_root                      (ClutterStage *stage);
    void                st_set_slow_down_factor             (gfloat factor);
    void                st_set_ui_root                      (ClutterStage *stage,
                                                             ClutterContainer *container);
    void                st_widget_add_style_class_name      (StWidget *actor,
                                                             const gchar *style_class);
    void                st_widget_add_style_pseudo_class    (StWidget *actor,
                                                             const gchar *pseudo_class);
    void                st_widget_ensure_style              (StWidget *widget);
    gboolean            st_widget_get_can_focus             (StWidget *widget);
    StTextDirection     st_widget_get_default_direction     (void);
    StTextDirection     st_widget_get_direction             (StWidget *self);
    gboolean            st_widget_get_has_tooltip           (StWidget *widget);
    gboolean            st_widget_get_hover                 (StWidget *widget);
    ClutterActor *      st_widget_get_label_actor           (StWidget *widget);
    const gchar *       st_widget_get_style                 (StWidget *actor);
    const gchar *       st_widget_get_style_class_name      (StWidget *actor);
    const gchar *       st_widget_get_style_pseudo_class    (StWidget *actor);
    StTheme *           st_widget_get_theme                 (StWidget *actor);
    StThemeNode *       st_widget_get_theme_node            (StWidget *widget);
    const gchar *       st_widget_get_tooltip_text          (StWidget *widget);
    gboolean            st_widget_get_track_hover           (StWidget *widget);
    gboolean            st_widget_has_style_class_name      (StWidget *actor,
                                                             const gchar *style_class);
    gboolean            st_widget_has_style_pseudo_class    (StWidget *actor,
                                                             const gchar *pseudo_class);
    void                st_widget_hide_tooltip              (StWidget *widget);
    gboolean            st_widget_navigate_focus            (StWidget *widget,
                                                             ClutterActor *from,
                                                             GtkDirectionType direction,
                                                             gboolean wrap_around);
    StThemeNode *       st_widget_peek_theme_node           (StWidget *widget);
    void                st_widget_remove_style_class_name   (StWidget *actor,
                                                             const gchar *style_class);
    void                st_widget_remove_style_pseudo_class (StWidget *actor,
                                                             const gchar *pseudo_class);
    void                st_widget_set_can_focus             (StWidget *widget,
                                                             gboolean can_focus);
    void                st_widget_set_default_direction     (StTextDirection dir);
    void                st_widget_set_direction             (StWidget *self,
                                                             StTextDirection dir);
    void                st_widget_set_has_tooltip           (StWidget *widget,
                                                             gboolean has_tooltip);
    void                st_widget_set_hover                 (StWidget *widget,
                                                             gboolean hover);
    void                st_widget_set_label_actor           (StWidget *widget,
                                                             ClutterActor *label);
    void                st_widget_set_style                 (StWidget *actor,
                                                             const gchar *style);
    void                st_widget_set_style_class_name      (StWidget *actor,
                                                             const gchar *style_class_list);
    void                st_widget_set_style_pseudo_class    (StWidget *actor,
                                                             const gchar *pseudo_class_list);
    void                st_widget_set_theme                 (StWidget *actor,
                                                             StTheme *theme);
    void                st_widget_set_tooltip_text          (StWidget *widget,
                                                             const gchar *text);
    void                st_widget_set_track_hover           (StWidget *widget,
                                                             gboolean track_hover);
    void                st_widget_show_tooltip              (StWidget *widget);
    void                st_widget_style_changed             (StWidget *widget);
    void                st_widget_sync_hover                (StWidget *widget);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterActor
                   +----StWidget
                         +----StBin
                         +----StContainer
                         +----StDrawingArea
                         +----StEntry
                         +----StIcon
                         +----StLabel
                         +----StScrollBar
                         +----StTooltip

## Implemented Interfaces

StWidget implements ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

## Properties

      "can-focus"                gboolean              : Read / Write
      "has-tooltip"              gboolean              : Read / Write
      "hover"                    gboolean              : Read / Write
      "label-actor"              ClutterActor*         : Read / Write
      "pseudo-class"             gchar*                : Read / Write
      "stylable"                 gboolean              : Read / Write
      "style"                    gchar*                : Read / Write
      "style-class"              gchar*                : Read / Write
      "theme"                    StTheme*              : Read / Write
      "tooltip-text"             gchar*                : Read / Write
      "track-hover"              gboolean              : Read / Write

## Signals

      "popup-menu"                                     : Run Last
      "style-changed"                                  : Run Last

## 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.

## Details

### enum StTextDirection

    typedef enum {
      ST_TEXT_DIRECTION_NONE,
      ST_TEXT_DIRECTION_LTR,
      ST_TEXT_DIRECTION_RTL
    } StTextDirection;

### 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.

### 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.

`actor` : | a ClutterActor
Returns : | the debug name.

### st_get_slow_down_factor ()

    gfloat              st_get_slow_down_factor             (void);

Returns : | the global factor applied to all animation durations

### st_get_ui_root ()

    ClutterContainer *  st_get_ui_root                      (ClutterStage *stage);

`stage` : | a ClutterStage
Returns : | the container which should be the parent of all user interface, which can be set with `st_set_ui_root()`. If not set, returns `stage`. [transfer none]

### st_set_slow_down_factor ()

    void                st_set_slow_down_factor             (gfloat factor);

`factor`: new slow-down factor

Set a global factor applied to all animation durations

### st_set_ui_root ()

    void                st_set_ui_root                      (ClutterStage *stage,
                                                             ClutterContainer *container);

### 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.

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

### 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.

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

### st_widget_ensure_style ()

    void                st_widget_ensure_style              (StWidget *widget);

Ensures that `widget` has read its style information.

`widget` : | A StWidget

### 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.

`widget` : | A StWidget
Returns : | current value of can-focus on `widget`

### st_widget_get_default_direction ()

    StTextDirection     st_widget_get_default_direction     (void);

### st_widget_get_direction ()

    StTextDirection     st_widget_get_direction             (StWidget *self);

### st_widget_get_has_tooltip ()

    gboolean            st_widget_get_has_tooltip           (StWidget *widget);

Returns the current value of the has-tooltip property. See `st_tooltip_set_has_tooltip()` for more information.

`widget` : | A StWidget
Returns : | current value of has-tooltip on `widget`

### 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.

`widget` : | A StWidget
Returns : | current value of hover on `widget`

### st_widget_get_label_actor ()

    ClutterActor *      st_widget_get_label_actor           (StWidget *widget);

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

`widget` : | a StWidget
Returns : | the label that identifies the widget. [transfer none]

### st_widget_get_style ()

    const gchar *       st_widget_get_style                 (StWidget *actor);

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

`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_get_style_class_name ()

    const gchar *       st_widget_get_style_class_name      (StWidget *actor);

Get the current style class name

`actor` : | a StWidget
Returns : | the class name string. The string is owned by the StWidget and should not be modified or freed.

### 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()`.

`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_get_theme ()

    StTheme *           st_widget_get_theme                 (StWidget *actor);

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

`actor` : | a StWidget
Returns : | the overriding theme, or `NULL`. [transfer none]

### 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.

`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_tooltip_text ()

    const gchar *       st_widget_get_tooltip_text          (StWidget *widget);

Get the current tooltip string

`widget` : | A StWidget
Returns : | The current tooltip string, owned by the StWidget

### st_widget_get_track_hover ()

    gboolean            st_widget_get_track_hover           (StWidget *widget);

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

`widget` : | A StWidget
Returns : | current value of track-hover on `widget`

### 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`.

`actor` : | a StWidget
`style_class` : | a style class string
Returns : | whether or not `actor`'s style class list includes `style_class`.

### 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`.

`actor` : | a StWidget
`pseudo_class` : | a pseudo class string
Returns : | whether or not `actor`'s pseudo class list includes `pseudo_class`.

### st_widget_hide_tooltip ()

    void                st_widget_hide_tooltip              (StWidget *widget);

Hide the tooltip for `widget`

`widget` : | A StWidget

### 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`, or outside of `widget`, this attempts to focus either `widget` itself, or its first descendant in the order implied by `direction`.

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.

`widget` : | the "top level" container
`from` : | the actor that the focus is coming from. [allow-none]
`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_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.

`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_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.

`actor` : | a StWidget
`style_class` : | a style class name 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.

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

### 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.

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

### st_widget_set_default_direction ()

    void                st_widget_set_default_direction     (StTextDirection dir);

### st_widget_set_direction ()

    void                st_widget_set_direction             (StWidget *self,
                                                             StTextDirection dir);

### st_widget_set_has_tooltip ()

    void                st_widget_set_has_tooltip           (StWidget *widget,
                                                             gboolean has_tooltip);

Enables tooltip support on the StWidget.

Note that setting has-tooltip to `TRUE` will cause "reactive" and "track-hover" to be set `TRUE` as well, but you must clear these flags yourself (if appropriate) when setting it `FALSE`.

`widget` : | A StWidget
`has_tooltip` : | `TRUE` if the widget should display a tooltip

### 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 "has-tooltip" is `TRUE`, this will also show or hide the tooltip, as appropriate.

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.

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

### 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

`widget` : | a StWidget
`label` : | a ClutterActor

### 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.

`actor` : | a StWidget
`style` : | a inline style string, or `NULL`. [allow-none]

### 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()`.

`actor` : | a StWidget
`style_class_list` : | a new style class list string. [allow-none]

### 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()`.

`actor` : | a StWidget
`pseudo_class_list` : | a new pseudo class list string. [allow-none]

### 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).

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

### st_widget_set_tooltip_text ()

    void                st_widget_set_tooltip_text          (StWidget *widget,
                                                             const gchar *text);

Set the tooltip text of the widget. This will set StWidget::has-tooltip to `TRUE`. A value of `NULL` will unset the tooltip and set has-tooltip to `FALSE`.

`widget` : | A StWidget
`text` : | text to set as the tooltip

### 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.

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

### st_widget_show_tooltip ()

    void                st_widget_show_tooltip              (StWidget *widget);

Force the tooltip for `widget` to be shown

`widget` : | A StWidget

### st_widget_style_changed ()

    void                st_widget_style_changed             (StWidget *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.

`widget` : | A StWidget

## Property Details

### The `"can-focus"` property

      "can-focus"                gboolean              : Read / Write

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

Default value: FALSE

### The `"has-tooltip"` property

      "has-tooltip"              gboolean              : Read / Write

Determines whether the widget has a tooltip. If set to `TRUE`, causes the widget to monitor hover state (i.e. sets "reactive" and "track-hover").

Default value: FALSE

### The `"hover"` property

      "hover"                    gboolean              : Read / Write

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.

Default value: FALSE

### The `"label-actor"` property

      "label-actor"              ClutterActor*         : Read / Write

Label that identifies this widget.

### The `"pseudo-class"` property

      "pseudo-class"             gchar*                : Read / Write

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

Default value: ""

### The `"stylable"` property

      "stylable"                 gboolean              : Read / Write

Enable or disable styling of the widget

Default value: TRUE

### The `"style"` property

      "style"                    gchar*                : Read / Write

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

Default value: ""

### The `"style-class"` property

      "style-class"              gchar*                : Read / Write

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

Default value: ""

### The `"theme"` property

      "theme"                    StTheme*              : Read / Write

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

### The `"tooltip-text"` property

      "tooltip-text"             gchar*                : Read / Write

text displayed on the tooltip

Default value: ""

### The `"track-hover"` property

      "track-hover"              gboolean              : Read / Write

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.

Default value: FALSE

## Signal Details

### The `"popup-menu"` signal

    void                user_function                      (StWidget *widget,
                                                            gpointer  user_data)      : Run Last

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

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

### The `"style-changed"` signal

    void                user_function                      (StWidget *widget,
                                                            gpointer  user_data)      : Run Last

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

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