| Clutter Reference Manual | ||||
|---|---|---|---|---|
| Top | Description | ||||
enum ClutterUnitType; ClutterUnits; void clutter_units_from_cm (ClutterUnits *units,gfloat cm); void clutter_units_from_em (ClutterUnits *units,gfloat em); void clutter_units_from_em_for_font (ClutterUnits *units,const gchar *font_name,gfloat em); void clutter_units_from_mm (ClutterUnits *units,gfloat mm); void clutter_units_from_pixels (ClutterUnits *units,gint px); void clutter_units_from_pt (ClutterUnits *units,gfloat pt); gfloat clutter_units_to_pixels (ClutterUnits *units); ClutterUnits * clutter_units_copy (const ClutterUnits *units); void clutter_units_free (ClutterUnits *units); ClutterUnitType clutter_units_get_unit_type (const ClutterUnits *units); gfloat clutter_units_get_unit_value (const ClutterUnits *units); gboolean clutter_units_from_string (ClutterUnits *units,const gchar *str); gchar * clutter_units_to_string (const ClutterUnits *units); ClutterParamSpecUnits; GParamSpec * clutter_param_spec_units (const gchar *name,const gchar *nick,const gchar *blurb,ClutterUnitType default_type,gfloat minimum,gfloat maximum,gfloat default_value,GParamFlags flags); #define CLUTTER_VALUE_HOLDS_UNITS (x) void clutter_value_set_units (GValue *value,const ClutterUnits *units); const ClutterUnits * clutter_value_get_units (const GValue *value);
ClutterUnits is a structure holding a logical distance value along with
its type, expressed as a value of the ClutterUnitType enumeration. It is
possible to use ClutterUnits to store a position or a size in units
different than pixels, and convert them whenever needed (for instance
inside the ClutterActor::allocate() virtual function, or inside the
ClutterActor::get_preferred_width() and ClutterActor::get_preferred_height()
virtual functions.
In order to register a ClutterUnits property, the ClutterParamSpecUnits GParamSpec sub-class should be used:
1 2 3 4 5 6 7 8 9 10 |
GParamSpec *pspec; pspec = clutter_param_spec_units ("active-width", "Width", "Width of the active area, in millimeters", CLUTTER_UNIT_MM, 0.0, 12.0, 12.0, G_PARAM_READWRITE); g_object_class_install_property (gobject_class, PROP_WIDTH, pspec); |
A GValue holding units can be manipulated using clutter_value_set_units()
and clutter_value_get_units(). GValues containing a ClutterUnits
value can also be transformed to GValues initialized with
G_TYPE_INT, G_TYPE_FLOAT and G_TYPE_STRING through implicit conversion
and using g_value_transform().
ClutterUnits is available since Clutter 1.0
typedef enum {
CLUTTER_UNIT_PIXEL,
CLUTTER_UNIT_EM,
CLUTTER_UNIT_MM,
CLUTTER_UNIT_POINT,
CLUTTER_UNIT_CM
} ClutterUnitType;
The type of unit in which a value is expressed
This enumeration might be expanded at later date
| Unit expressed in pixels (with subpixel precision) | |
| Unit expressed in em | |
| Unit expressed in millimeters | |
| Unit expressed in points | |
| Unit expressed in centimeters |
Since 1.0
typedef struct {
} ClutterUnits;
An opaque structure, to be used to store sizing and positioning values along with their unit.
Since 1.0
void clutter_units_from_cm (ClutterUnits *units,gfloat cm);
Stores a value in centimeters inside units
|
a ClutterUnits |
|
centimeters |
Since 1.2
void clutter_units_from_em (ClutterUnits *units,gfloat em);
Stores a value in em inside units, using the default font
name as returned by clutter_backend_get_font_name()
|
a ClutterUnits |
|
em |
Since 1.0
void clutter_units_from_em_for_font (ClutterUnits *units,const gchar *font_name,gfloat em);
Stores a value in em inside units using font_name
|
a ClutterUnits |
|
the font name and size |
|
em |
Since 1.0
void clutter_units_from_mm (ClutterUnits *units,gfloat mm);
Stores a value in millimiters inside units
|
a ClutterUnits |
|
millimeters |
Since 1.0
void clutter_units_from_pixels (ClutterUnits *units,gint px);
Stores a value in pixels inside units
|
a ClutterUnits |
|
pixels |
Since 1.0
void clutter_units_from_pt (ClutterUnits *units,gfloat pt);
Stores a value in typographic points inside units
|
a ClutterUnits |
|
typographic points |
Since 1.0
gfloat clutter_units_to_pixels (ClutterUnits *units);
Converts a value in ClutterUnits to pixels
|
units to convert |
Returns : |
the value in pixels |
Since 1.0
ClutterUnits * clutter_units_copy (const ClutterUnits *units);
Copies units
|
the ClutterUnits to copy |
Returns : |
the newly created copy of a ClutterUnits structure.
Use clutter_units_free() to free the allocated resources
|
Since 1.0
void clutter_units_free (ClutterUnits *units);
Frees the resources allocated by units
You should only call this function on a ClutterUnits
created using clutter_units_copy()
|
the ClutterUnits to free |
Since 1.0
ClutterUnitType clutter_units_get_unit_type (const ClutterUnits *units);
Retrieves the unit type of the value stored inside units
|
a ClutterUnits |
Returns : |
a unit type |
Since 1.0
gfloat clutter_units_get_unit_value (const ClutterUnits *units);
Retrieves the value stored inside units
|
a ClutterUnits |
Returns : |
the value stored inside a ClutterUnits |
Since 1.0
gboolean clutter_units_from_string (ClutterUnits *units,const gchar *str);
Parses a value and updates units with it
A ClutterUnits expressed in string should match:
1 2 3 4 5 6 7 8 |
units: wsp* unit-value wsp* unit-name? wsp* unit-value: number unit-name: 'px' | 'pt' | 'mm' | 'em' | 'cm' number: digit+ | digit* sep digit+ sep: '.' | ',' digit: '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' wsp: (<GTKDOCLINK HREF="0x20">0x20</GTKDOCLINK> | <GTKDOCLINK HREF="0x9">0x9</GTKDOCLINK> | <GTKDOCLINK HREF="0xA">0xA</GTKDOCLINK> | <GTKDOCLINK HREF="0xB">0xB</GTKDOCLINK> | <GTKDOCLINK HREF="0xC">0xC</GTKDOCLINK> | <GTKDOCLINK HREF="0xD">0xD</GTKDOCLINK>)+ |
For instance, these are valid strings:
1 2 3 4 5 |
10 px 5.1 em 24 pt 12.6 mm .3 cm |
While these are not:
1 2 |
42 cats omg!1!ponies |
If no unit is specified, pixels are assumed.
|
a ClutterUnits |
|
the string to convert |
Returns : |
TRUE if the string was successfully parsed,
and FALSE otherwise
|
Since 1.0
gchar * clutter_units_to_string (const ClutterUnits *units);
Converts units into a string
See clutter_units_from_string() for the units syntax and for
examples of output
|
a ClutterUnits |
Returns : |
a newly allocated string containing the encoded
ClutterUnits value. Use g_free() to free the string
|
Since 1.0
typedef struct {
ClutterUnitType default_type;
gfloat default_value;
gfloat minimum;
gfloat maximum;
} ClutterParamSpecUnits;
GParamSpec subclass for unit based properties.
ClutterUnitType |
default type |
gfloat |
default value |
gfloat |
lower boundary |
gfloat |
higher boundary |
Since 1.0
GParamSpec * clutter_param_spec_units (const gchar *name,const gchar *nick,const gchar *blurb,ClutterUnitType default_type,gfloat minimum,gfloat maximum,gfloat default_value,GParamFlags flags);
Creates a GParamSpec for properties using ClutterUnits.
|
name of the property |
|
short name |
|
description (can be translatable) |
|
the default type for the ClutterUnits |
|
lower boundary |
|
higher boundary |
|
default value |
|
flags for the param spec |
Returns : |
the newly created GParamSpec |
Since 1.0
#define CLUTTER_VALUE_HOLDS_UNITS(x) (G_VALUE_HOLDS ((x), CLUTTER_TYPE_UNITS))
Evaluates to TRUE if x holds a ClutterUnits value
|
a GValue |
Since 0.8
void clutter_value_set_units (GValue *value,const ClutterUnits *units);
Sets value to units
|
a GValue initialized to CLUTTER_TYPE_UNIT |
|
the units to set |
Since 0.8
const ClutterUnits * clutter_value_get_units (const GValue *value);
Gets the ClutterUnits contained in value.
Since 0.8