MxStylable

## MxStylable MxStylable — Interface for stylable objects |

## Synopsis

    enum                MxStyleChangedFlags;
                        MxStylable;
                        MxStylableIface;
    void                mx_stylable_iface_install_property  (MxStylableIface *iface,
                                                             GType owner_type,
                                                             GParamSpec *pspec);
    void                mx_stylable_freeze_notify           (MxStylable *stylable);
    void                mx_stylable_notify                  (MxStylable *stylable,
                                                             const gchar *property_name);
    void                mx_stylable_thaw_notify             (MxStylable *stylable);
    GParamSpec **       mx_stylable_list_properties         (MxStylable *stylable,
                                                             guint *n_props);
    GParamSpec *        mx_stylable_find_property           (MxStylable *stylable,
                                                             const gchar *property_name);
    void                mx_stylable_set_style               (MxStylable *stylable,
                                                             MxStyle *style);
    MxStyle *           mx_stylable_get_style               (MxStylable *stylable);
    void                mx_stylable_get                     (MxStylable *stylable,
                                                             const gchar *first_property_name,
                                                             ...);
    void                mx_stylable_get_property            (MxStylable *stylable,
                                                             const gchar *property_name,
                                                             GValue *value);
    gboolean            mx_stylable_get_default_value       (MxStylable *stylable,
                                                             const gchar *property_name,
                                                             GValue *value_out);
    const gchar *       mx_stylable_get_style_class         (MxStylable *stylable);
    void                mx_stylable_set_style_class         (MxStylable *stylable,
                                                             const gchar *style_class);
    const gchar *       mx_stylable_get_style_pseudo_class  (MxStylable *stylable);
    void                mx_stylable_set_style_pseudo_class  (MxStylable *stylable,
                                                             const gchar *pseudo_class);
    void                mx_stylable_style_changed           (MxStylable *stylable,
                                                             MxStyleChangedFlags flags);
    void                mx_stylable_connect_change_notifiers
                                                            (MxStylable *stylable);
    void                mx_stylable_apply_clutter_text_attributes
                                                            (MxStylable *stylable,
                                                             ClutterText *text);
    void                mx_stylable_style_pseudo_class_add  (MxStylable *stylable,
                                                             const gchar *new_class);
    void                mx_stylable_style_pseudo_class_remove
                                                            (MxStylable *stylable,
                                                             const gchar *remove_class);
    gboolean            mx_stylable_style_pseudo_class_contains
                                                            (MxStylable *stylable,
                                                             const gchar *pseudo_class);

## Object Hierarchy

      GInterface
       +----MxStylable

## Known Implementations

MxStylable is implemented by MxBin, MxBoxLayout, MxButton, MxComboBox, MxDeformBowTie, MxDeformPageTurn, MxDeformTexture, MxDeformWaves, MxDialog, MxEntry, MxExpander, MxFloatingWidget, MxFrame, MxIcon, MxImage, MxItemView, MxKineticScrollView, MxLabel, MxListView, MxMenu, MxNotebook, MxPathBar, MxProgressBar, MxScrollBar, MxScrollView, MxSlider, MxSpinner, MxStack, MxTable, MxToggle, MxToolbar, MxTooltip, MxViewport and MxWidget.

## Properties

      "style"                    MxStyle*              : Read / Write
      "style-class"              gchar*                : Read / Write
      "style-pseudo-class"       gchar*                : Read / Write

## Signals

      "style-changed"                                  : Run First

## Description

Stylable objects are classes that can have "style properties", that is properties that can be changed by attaching a MxStyle to them.

## Details

### enum MxStyleChangedFlags

    typedef enum {
      MX_STYLE_CHANGED_NONE  = 0,
      MX_STYLE_CHANGED_FORCE = 1 << 0,
      MX_STYLE_CHANGED_INVALIDATE_CACHE = 1 << 1
    } MxStyleChangedFlags;

`MX_STYLE_CHANGED_NONE` | No flag set
`MX_STYLE_CHANGED_FORCE` | Whether to force propogation of the style-changed signal, regardless of the state of the stylable object.
`MX_STYLE_CHANGED_INVALIDATE_CACHE` | Internal flag used to track style caching state.

### MxStylable

    typedef struct _MxStylable MxStylable;

This is an opaque structure whose members cannot be directly accessed.

### MxStylableIface

    typedef struct {
      /* virtual functions */
      MxStyle *  (* get_style) (MxStylable *stylable);
      void       (* set_style) (MxStylable *stylable,
                                MxStyle    *style);

      const gchar* (* get_style_class) (MxStylable  *stylable);
      void         (* set_style_class) (MxStylable  *stylable,
                                        const gchar *style_class);

      const gchar* (* get_style_pseudo_class) (MxStylable  *stylable);
      void         (* set_style_pseudo_class) (MxStylable  *stylable,
                                               const gchar *pseudo_class);

      /* context virtual functions */

      /* signals, not vfuncs */
    #if 0
      void (* style_notify)     (MxStylable *stylable,
                                 GParamSpec *pspec);
    #endif
      void (* style_changed)    (MxStylable *stylable, MxStyleChangedFlags flags);
    } MxStylableIface;

### mx_stylable_iface_install_property ()

    void                mx_stylable_iface_install_property  (MxStylableIface *iface,
                                                             GType owner_type,
                                                             GParamSpec *pspec);

Installs a property for `owner_type` using `pspec` as the property description.

This function should be used inside the MxStylableIface initialization function of a class, for instance:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    G_DEFINE_TYPE_WITH_CODE (FooActor, foo_actor, CLUTTER_TYPE_ACTOR,
                             G_IMPLEMENT_INTERFACE (MX_TYPE_STYLABLE,
                                                    mx_stylable_init));
    ...
    static void
    mx_stylable_init (MxStylableIface *iface)
    {
      static gboolean is_initialized = FALSE;

      if (!is_initialized)
        {
          ...
          mx_stylable_iface_install_property (stylable,
                                                FOO_TYPE_ACTOR,
                                                g_param_spec_int ("x-spacing",
                                                                  "X Spacing",
                                                                  "Horizontal spacing",
                                                                  -1, G_MAXINT,
                                                                  2,
                                                                  G_PARAM_READWRITE));
          ...
        }
    }

`iface` : | a MxStylableIface
`owner_type` : | GType of the style property owner
`pspec` : | a GParamSpec

### mx_stylable_freeze_notify ()

    void                mx_stylable_freeze_notify           (MxStylable *stylable);

### mx_stylable_notify ()

    void                mx_stylable_notify                  (MxStylable *stylable,
                                                             const gchar *property_name);

### mx_stylable_thaw_notify ()

    void                mx_stylable_thaw_notify             (MxStylable *stylable);

### mx_stylable_list_properties ()

    GParamSpec **       mx_stylable_list_properties         (MxStylable *stylable,
                                                             guint *n_props);

Retrieves all the GParamSpecs installed by `stylable`.

`stylable` : | a MxStylable
`n_props` : | return location for the number of properties, or `NULL`. [out]
Returns : | an array of GParamSpecs. Free it with `g_free()` when done. [transfer container][array length=n_props]

### mx_stylable_find_property ()

    GParamSpec *        mx_stylable_find_property           (MxStylable *stylable,
                                                             const gchar *property_name);

Finds the GParamSpec installed by `stylable` for the property with `property_name`.

`stylable` : | a MxStylable
`property_name` : | the name of the property to find
Returns : | a GParamSpec for the given property, or `NULL` if no property with that name was found. [transfer none]

### mx_stylable_set_style ()

    void                mx_stylable_set_style               (MxStylable *stylable,
                                                             MxStyle *style);

Sets `style` as the new MxStyle to be used by `stylable`.

The MxStylable will take ownership of the passed MxStyle.

After the MxStyle has been set, the MxStylable::style-set signal will be emitted.

`stylable` : | a MxStylable
`style` : | a MxStyle

### mx_stylable_get_style ()

    MxStyle *           mx_stylable_get_style               (MxStylable *stylable);

Retrieves the MxStyle used by `stylable`. This function does not alter the reference count of the returned object.

`stylable` : | a MxStylable
Returns : | a MxStyle. [transfer none]

### mx_stylable_get ()

    void                mx_stylable_get                     (MxStylable *stylable,
                                                             const gchar *first_property_name,
                                                             ...);

Gets the style properties for `stylable`.

In general, a copy is made of the property contents and the called is responsible for freeing the memory in the appropriate manner for the property type.

Example 1. Using mx_stylable_get()

An example of using `mx_stylable_get()` to get the contents of two style properties - one of type G_TYPE_INT and one of type CLUTTER_TYPE_COLOR:

      gint x_spacing;
      ClutterColor *bg_color;

      mx_stylable_get (stylable,
                         "x-spacing", &x_spacing,
                         "bg-color", &bg_color,
                         NULL);

      /* do something with x_spacing and bg_color */

      clutter_color_free (bg_color);

`stylable` : | a MxStylable
`first_property_name` : | name of the first property to get
`Varargs` : | return location for the first property, followed optionally by more name/return location pairs, followed by `NULL`

### mx_stylable_get_property ()

    void                mx_stylable_get_property            (MxStylable *stylable,
                                                             const gchar *property_name,
                                                             GValue *value);

Retrieves the value of `property_name` for `stylable`, and puts it into `value`.

`stylable` : | a MxStylable
`property_name` : | the name of the property
`value` : | return location for an empty GValue. [out]

### mx_stylable_get_default_value ()

    gboolean            mx_stylable_get_default_value       (MxStylable *stylable,
                                                             const gchar *property_name,
                                                             GValue *value_out);

Query `stylable` for the default value of property `property_name` and fill `value_out` with the result.

`stylable` : | a MxStylable
`property_name` : | name of the property to query
`value_out` : | return location for the default value. [out]
Returns : | `TRUE` if property `property_name` exists and the default value has been returned.

### mx_stylable_get_style_class ()

    const gchar *       mx_stylable_get_style_class         (MxStylable *stylable);

Get the current style class name

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

### mx_stylable_set_style_class ()

    void                mx_stylable_set_style_class         (MxStylable *stylable,
                                                             const gchar *style_class);

Set the style class name

`stylable` : | a MxStylable
`style_class` : | a new style class string

### mx_stylable_get_style_pseudo_class ()

    const gchar *       mx_stylable_get_style_pseudo_class  (MxStylable *stylable);

Get the current style pseudo class. This can contain multiple pseudo class names, separated by ':'.

`stylable` : | a MxStylable
Returns : | the pseudo class string. The string is owned by the MxWidget and should not be modified or freed.

### mx_stylable_set_style_pseudo_class ()

    void                mx_stylable_set_style_pseudo_class  (MxStylable *stylable,
                                                             const gchar *pseudo_class);

Set the style pseudo class. The string can contain multiple pseudo class names, separated by ':'.

`stylable` : | a MxStylable
`pseudo_class` : | a new pseudo class string

### mx_stylable_style_changed ()

    void                mx_stylable_style_changed           (MxStylable *stylable,
                                                             MxStyleChangedFlags flags);

Emit the "style-changed" signal on `stylable` to notify it that one or more of the style properties has changed.

If `stylable` is a ClutterContainer then the "style-changed" notification is propagated to it's children, since their style may depend on one or more properties of the parent.

`stylable` : | an MxStylable
`flags` : | flags that control the style changing

### mx_stylable_connect_change_notifiers ()

    void                mx_stylable_connect_change_notifiers
                                                            (MxStylable *stylable);

### mx_stylable_apply_clutter_text_attributes ()

    void                mx_stylable_apply_clutter_text_attributes
                                                            (MxStylable *stylable,
                                                             ClutterText *text);

### mx_stylable_style_pseudo_class_add ()

    void                mx_stylable_style_pseudo_class_add  (MxStylable *stylable,
                                                             const gchar *new_class);

Add a pseudo-class name to the list of pseudo classes, contained in the "style-pseudo-class" property.

`stylable` : | A MxStylable
`new_class` : | A pseudo-class name to add

Since 1.2

### mx_stylable_style_pseudo_class_remove ()

    void                mx_stylable_style_pseudo_class_remove
                                                            (MxStylable *stylable,
                                                             const gchar *remove_class);

Remove the specified pseudo class name from the list of pseudo classes contained in the "style-pseudo-class" property.

`stylable` : | An MxStylable
`remove_class` : | A pseudo class name to remove

Since 1.2

### mx_stylable_style_pseudo_class_contains ()

    gboolean            mx_stylable_style_pseudo_class_contains
                                                            (MxStylable *stylable,
                                                             const gchar *pseudo_class);

Check if the given pseudo-class name is contained in the list of set pseudo classes on this MxStylable object.

`stylable` : | A MxStylable
`pseudo_class` : | A pseudo-class name
Returns : | `TRUE` if the given pseudo-class is set, `FALSE` otherwise

Since 1.2

## Property Details

### The `"style"` property

      "style"                    MxStyle*              : Read / Write

A style object.

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

      "style-class"              gchar*                : Read / Write

String representation of the item's class.

Default value: ""

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

      "style-pseudo-class"       gchar*                : Read / Write

List of pseudo class, such as current state,separated by ':'.

Default value: ""

## Signal Details

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

    void                user_function                      (MxStylable         *stylable,
                                                            MxStyleChangedFlags flags,
                                                            gpointer            user_data)      : Run First

The ::style-changed signal is emitted each time one of the style properties have changed.

`stylable` : | the MxStylable that received the signal
`flags` : | the MxStyleChangedFlags associated with the signal
`user_data` : | user data set when the signal handler was connected.