StWidget

StWidget — Base class for stylable actors

Synopsis

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

Object Hierarchy

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

Implemented Interfaces

StWidget implements ClutterContainer, ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

Properties

  "accessible-name"          gchar*                : Read / Write
  "accessible-role"          AtkRole               : Read / Write
  "can-focus"                gboolean              : Read / Write
  "has-tooltip"              gboolean              : Read / Write
  "hover"                    gboolean              : Read / Write
  "important"                gboolean              : Read / Write / Construct Only
  "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;

ST_TEXT_DIRECTION_NONE

ST_TEXT_DIRECTION_LTR

ST_TEXT_DIRECTION_RTL


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_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_change_style_pseudo_class ()

void                st_widget_change_style_pseudo_class (StWidget *actor,
                                                         const gchar *pseudo_class,
                                                         gboolean add);

Adds pseudo_class to actor's pseudo class list if add is true, removes if add is false.

actor :

a StWidget

pseudo_class :

a pseudo class string

add :

whether to add or remove pseudo class

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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_show_tooltip ()

void                st_widget_show_tooltip              (StWidget *widget);

Force the tooltip for widget to be shown

widget :

A StWidget

st_widget_hide_tooltip ()

void                st_widget_hide_tooltip              (StWidget *widget);

Hide the tooltip for widget

widget :

A StWidget

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

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_ensure_style ()

void                st_widget_ensure_style              (StWidget *widget);

Ensures that widget has read its style information.

widget :

A StWidget

st_widget_get_default_direction ()

StTextDirection     st_widget_get_default_direction     (void);

st_widget_set_default_direction ()

void                st_widget_set_default_direction     (StTextDirection dir);

st_widget_get_direction ()

StTextDirection     st_widget_get_direction             (StWidget *self);

st_widget_set_direction ()

void                st_widget_set_direction             (StWidget *self,
                                                         StTextDirection dir);

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_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_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_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_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_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: this should only be called on a widget that has been added to the 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_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_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_set_slow_down_factor ()

void                st_set_slow_down_factor             (gfloat factor);

Set a global factor applied to all animation durations

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_set_ui_root ()

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

Sets a ClutterContainer to be the parent of all UI in the program. This container is used when St needs to add new content outside the widget hierarchy, for example, when it shows a tooltip over a widget.

stage :

a ClutterStage

container :

the new UI root. [allow-none]

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

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.

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

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.

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.

widget :

widget to set the accessible name for

name :

a character string to be set as the accessible name. [allow-none]

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.

widget :

widget to get the accessible name for

Returns :

a character string representing the accessible name of the widget.

Property Details

The "accessible-name" property

  "accessible-name"          gchar*                : Read / Write

Object instance's name for assistive technology access.

Default value: NULL


The "accessible-role" property

  "accessible-role"          AtkRole               : Read / Write

The accessible role of this object

Default value: ATK_ROLE_INVALID


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 "important" property

  "important"                gboolean              : Read / Write / Construct Only

Whether or not the fallback theme should be used for lookups in case the user theme fails.

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.