mx-stylable

## mx-stylable mx-stylable — Interface for stylable objects |

## Synopsis

    enum                MxStyleChangedFlags;
                        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);

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

### MxStylableIface

    typedef struct {
      GTypeInterface g_iface;

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

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

      G_CONST_RETURN gchar* (* get_style_pseudo_class) (MxStylable  *stylable);
      void                  (* set_style_pseudo_class) (MxStylable  *stylable,
                                                        const gchar *style_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);

`stylable` : |

### mx_stylable_notify ()

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

`stylable` : |
`property_name` : |

### mx_stylable_thaw_notify ()

    void                mx_stylable_thaw_notify             (MxStylable *stylable);

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

`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

`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);

`stylable` : |

### mx_stylable_apply_clutter_text_attributes ()

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

`stylable` : |
`text` : |