37 Unit conversion

A logical distance unit.

37.1 Overview

Clutter units are logical units with granularity greater than that of the device units; they are used by <clutter-actor-box> and the units-based family of <clutter-actor> functions. To convert between Clutter units and device units, use ‘CLUTTER_UNITS_FROM_DEVICE’ and ‘CLUTTER_UNITS_TO_DEVICE’ macros.

<clutter-unit>s can be converted from other units like millimeters, typographic points (at the current resolution) and percentages. It is also possible to convert fixed point values to and from <clutter-unit> values.

In order to register a <clutter-unit> property, the <clutter-param-spec-unit><gparam> sub-class should be used:

     
       GParamSpec *pspec;
     
       pspec = clutter_param_spec_unit ("width",
                                        "Width",
                                        "Width of the actor, in units",
                                        0, CLUTTER_MAXUNIT,
                                        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-unit and clutter-value-get-unit. <gvalue>s containing a <clutter-unit> value can also be transformed to <gvalue>s containing integer values - with a loss of precision:

     
       static gboolean
       units_to_int (const GValue *src,
                     GValue       *dest)
       {
         g_return_val_if_fail (CLUTTER_VALUE_HOLDS_UNIT (src), FALSE);
     
         g_value_init (dest, G_TYPE_INT);
         return g_value_transform (src, &dest);
       }

The code above is equivalent to:

     
       static gboolean
       units_to_int (const GValue *src,
                     GValue       *dest)
       {
         g_return_val_if_fail (CLUTTER_VALUE_HOLDS_UNIT (src), FALSE);
     
         g_value_init (dest, G_TYPE_INT);
         g_value_set_int (dest,
                          CLUTTER_UNITS_TO_INT (clutter_value_get_unit (src)));
     
         return TRUE;
       }

<clutter-unit> is available since Clutter 0.4

37.2 Usage