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

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:

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

... :

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


mx_stylable_apply_clutter_text_attributes ()

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