NbtkStylable

NbtkStylable — Interface for stylable objects

Synopsis

                    NbtkStylableIface;
void                nbtk_stylable_iface_install_property
                                                        (NbtkStylableIface *iface,
                                                         GType owner_type,
                                                         GParamSpec *pspec);
void                nbtk_stylable_freeze_notify         (NbtkStylable *stylable);
void                nbtk_stylable_notify                (NbtkStylable *stylable,
                                                         const gchar *property_name);
void                nbtk_stylable_thaw_notify           (NbtkStylable *stylable);
GParamSpec **       nbtk_stylable_list_properties       (NbtkStylable *stylable,
                                                         guint *n_props);
GParamSpec *        nbtk_stylable_find_property         (NbtkStylable *stylable,
                                                         const gchar *property_name);
void                nbtk_stylable_set_style             (NbtkStylable *stylable,
                                                         NbtkStyle *style);
NbtkStyle *         nbtk_stylable_get_style             (NbtkStylable *stylable);
void                nbtk_stylable_get                   (NbtkStylable *stylable,
                                                         const gchar *first_property_name,
                                                         ...);
void                nbtk_stylable_get_property          (NbtkStylable *stylable,
                                                         const gchar *property_name,
                                                         GValue *value);
gboolean            nbtk_stylable_get_default_value     (NbtkStylable *stylable,
                                                         const gchar *property_name,
                                                         GValue *value_out);
NbtkStylable*       nbtk_stylable_get_container         (NbtkStylable *stylable);
NbtkStylable*       nbtk_stylable_get_base_style        (NbtkStylable *stylable);
const gchar*        nbtk_stylable_get_style_id          (NbtkStylable *stylable);
const gchar*        nbtk_stylable_get_style_type        (NbtkStylable *stylable);
const gchar*        nbtk_stylable_get_style_class       (NbtkStylable *stylable);
const gchar*        nbtk_stylable_get_pseudo_class      (NbtkStylable *stylable);
gchar*              nbtk_stylable_get_attribute         (NbtkStylable *stylable,
                                                         const gchar *name);
gboolean            nbtk_stylable_get_viewport          (NbtkStylable *stylable,
                                                         gint *x,
                                                         gint *y,
                                                         gint *width,
                                                         gint *height);
void                nbtk_stylable_changed               (NbtkStylable *stylable);

Description

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

Objects can choose to subclass NbtkWidget, and thus inherit all the NbtkWidget style properties; or they can subclass NbtkWidget and reimplement the NbtkStylable interface to add new style properties specific for them (and their subclasses); or, finally, they can simply subclass GObject and implement NbtkStylable to install new properties.

Details

NbtkStylableIface

typedef struct {
  GTypeInterface g_iface;

  /* virtual functions */
  NbtkStyle *(* get_style) (NbtkStylable *stylable);
  void       (* set_style) (NbtkStylable *stylable,
                            NbtkStyle    *style);

  /* context virtual functions */
  NbtkStylable *(*get_container)    (NbtkStylable *stylable);
  NbtkStylable *(*get_base_style)   (NbtkStylable *stylable);
  const gchar  *(*get_style_id)     (NbtkStylable *stylable);
  const gchar  *(*get_style_type)   (NbtkStylable *stylable);
  const gchar  *(*get_style_class)  (NbtkStylable *stylable);
  const gchar  *(*get_pseudo_class) (NbtkStylable *stylable);
  gchar        *(*get_attribute)    (NbtkStylable *stylable,
                                     const gchar  *name);
  gboolean      (*get_viewport)     (NbtkStylable *stylable,
                                     gint         *x,
                                     gint         *y,
                                     gint         *width,
                                     gint         *height);

  /* signals, not vfuncs */
  void (* style_notify)     (NbtkStylable *stylable,
                             GParamSpec   *pspec);
  void (* style_changed)    (NbtkStylable *stylable);

  void (* stylable_changed) (NbtkStylable *stylable);
} NbtkStylableIface;


nbtk_stylable_iface_install_property ()

void                nbtk_stylable_iface_install_property
                                                        (NbtkStylableIface *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 NbtkStylableIface initialization function of a class, for instance:

G_DEFINE_TYPE_WITH_CODE (FooActor, foo_actor, CLUTTER_TYPE_ACTOR,
                         G_IMPLEMENT_INTERFACE (NBTK_TYPE_STYLABLE,
                                                nbtk_stylable_init));
...
static void
nbtk_stylable_init (NbtkStylableIface *iface)
{
  static gboolean is_initialized = FALSE;

  if (!is_initialized)
    {
      ...
      nbtk_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 NbtkStylableIface

owner_type :

GType of the style property owner

pspec :

a GParamSpec

nbtk_stylable_freeze_notify ()

void                nbtk_stylable_freeze_notify         (NbtkStylable *stylable);

stylable :


nbtk_stylable_notify ()

void                nbtk_stylable_notify                (NbtkStylable *stylable,
                                                         const gchar *property_name);

stylable :

property_name :


nbtk_stylable_thaw_notify ()

void                nbtk_stylable_thaw_notify           (NbtkStylable *stylable);

stylable :


nbtk_stylable_list_properties ()

GParamSpec **       nbtk_stylable_list_properties       (NbtkStylable *stylable,
                                                         guint *n_props);

Retrieves all the GParamSpecs installed by stylable.

stylable :

a NbtkStylable

n_props :

return location for the number of properties, or NULL

Returns :

an array of GParamSpecs. Free it with g_free() when done.

nbtk_stylable_find_property ()

GParamSpec *        nbtk_stylable_find_property         (NbtkStylable *stylable,
                                                         const gchar *property_name);

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

stylable :

a NbtkStylable

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

nbtk_stylable_set_style ()

void                nbtk_stylable_set_style             (NbtkStylable *stylable,
                                                         NbtkStyle *style);

Sets style as the new NbtkStyle to be used by stylable.

The NbtkStylable will take ownership of the passed NbtkStyle.

After the NbtkStle has been set, the NbtkStylable::style-set signal will be emitted.

stylable :

a NbtkStylable

style :

a NbtkStyle

nbtk_stylable_get_style ()

NbtkStyle *         nbtk_stylable_get_style             (NbtkStylable *stylable);

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

stylable :

a NbtkStylable

Returns :

a NbtkStyle

nbtk_stylable_get ()

void                nbtk_stylable_get                   (NbtkStylable *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 nbtk_stylable_get()

An example of using nbtk_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;

  nbtk_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 NbtkStylable

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

nbtk_stylable_get_property ()

void                nbtk_stylable_get_property          (NbtkStylable *stylable,
                                                         const gchar *property_name,
                                                         GValue *value);

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

stylable :

a NbtkStylable

property_name :

the name of the property

value :

return location for an empty GValue

nbtk_stylable_get_default_value ()

gboolean            nbtk_stylable_get_default_value     (NbtkStylable *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 NbtkStylable

property_name :

name of the property to query

value_out :

return location for the default value

Returns :

TRUE if property property_name exists and the default value has been returned.

nbtk_stylable_get_container ()

NbtkStylable*       nbtk_stylable_get_container         (NbtkStylable *stylable);

Obtain the parent NbtkStylable that contains stylable.

stylable :

a NbtkStylable

Returns :

The parent NbtkStylable

nbtk_stylable_get_base_style ()

NbtkStylable*       nbtk_stylable_get_base_style        (NbtkStylable *stylable);

Get the parent ancestor NbtkStylable of stylable.

stylable :

a NbtkStylable

Returns :

the parent NbtkStylable

nbtk_stylable_get_style_id ()

const gchar*        nbtk_stylable_get_style_id          (NbtkStylable *stylable);

Get the ID value of stylable

stylable :

a NbtkStylable

Returns :

the id of stylable

nbtk_stylable_get_style_type ()

const gchar*        nbtk_stylable_get_style_type        (NbtkStylable *stylable);

Get the type name of stylable

stylable :

a NbtkStylable

Returns :

the type name of stylable

nbtk_stylable_get_style_class ()

const gchar*        nbtk_stylable_get_style_class       (NbtkStylable *stylable);

Get the style class name of stylable

stylable :

a NbtkStylable

Returns :

the type name of stylable

nbtk_stylable_get_pseudo_class ()

const gchar*        nbtk_stylable_get_pseudo_class      (NbtkStylable *stylable);

Get the pseudo class name of stylable

stylable :

a NbtkStylable

Returns :

the pseudo class name of stylable

nbtk_stylable_get_attribute ()

gchar*              nbtk_stylable_get_attribute         (NbtkStylable *stylable,
                                                         const gchar *name);

Get the named attribute from stylable

stylable :

a NbtkStylable

name :

attribute name

Returns :

the value of the attribute

nbtk_stylable_get_viewport ()

gboolean            nbtk_stylable_get_viewport          (NbtkStylable *stylable,
                                                         gint *x,
                                                         gint *y,
                                                         gint *width,
                                                         gint *height);

Obtain the position and dimensions of stylable.

stylable :

a NbtkStylable

x :

location to store X coordinate

y :

location to store Y coordinate

width :

location to store width

height :

location to store height

Returns :

true if the function succeeded

nbtk_stylable_changed ()

void                nbtk_stylable_changed               (NbtkStylable *stylable);

Emit the "stylable-changed" signal on stylable

stylable :

A NbtkStylable