## Unit conversion

Unit conversion — A logical distance unit

## Synopsis

    enum                ClutterUnitType;
    struct              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);

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

## Description

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

## Details

### enum ClutterUnitType

    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

`CLUTTER_UNIT_PIXEL` | Unit expressed in pixels (with subpixel precision)
`CLUTTER_UNIT_EM` | Unit expressed in em
`CLUTTER_UNIT_MM` | Unit expressed in millimeters
`CLUTTER_UNIT_POINT` | Unit expressed in points
`CLUTTER_UNIT_CM` | Unit expressed in centimeters

Since 1.0

### struct ClutterUnits

    struct ClutterUnits {
    };

An opaque structure, to be used to store sizing and positioning values along with their unit.

Since 1.0

### clutter_units_from_cm ()

    void                clutter_units_from_cm               (ClutterUnits *units,
                                                             gfloat cm);

Stores a value in centimeters inside `units`

`units` : | a ClutterUnits. [out caller-allocates]
`cm` : | centimeters

Since 1.2

### clutter_units_from_em ()

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

`units` : | a ClutterUnits. [out caller-allocates]
`em` : | em

Since 1.0

### clutter_units_from_em_for_font ()

    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`

`units` : | a ClutterUnits. [out caller-allocates]
`font_name` : | the font name and size. [allow-none]
`em` : | em

Since 1.0

### clutter_units_from_mm ()

    void                clutter_units_from_mm               (ClutterUnits *units,
                                                             gfloat mm);

Stores a value in millimiters inside `units`

`units` : | a ClutterUnits. [out caller-allocates]
`mm` : | millimeters

Since 1.0

### clutter_units_from_pixels ()

    void                clutter_units_from_pixels           (ClutterUnits *units,
                                                             gint px);

Stores a value in pixels inside `units`

`units` : | a ClutterUnits. [out caller-allocates]
`px` : | pixels

Since 1.0

### clutter_units_from_pt ()

    void                clutter_units_from_pt               (ClutterUnits *units,
                                                             gfloat pt);

Stores a value in typographic points inside `units`

`units` : | a ClutterUnits. [out caller-allocates]
`pt` : | typographic points

Since 1.0

### clutter_units_to_pixels ()

    gfloat              clutter_units_to_pixels             (ClutterUnits *units);

Converts a value in ClutterUnits to pixels

`units` : | units to convert
Returns : | the value in pixels

Since 1.0

### clutter_units_copy ()

    ClutterUnits *      clutter_units_copy                  (const ClutterUnits *units);

Copies `units`

`units` : | the ClutterUnits to copy
Returns : | the newly created copy of a ClutterUnits structure. Use `clutter_units_free()` to free the allocated resources. [transfer full]

Since 1.0

### clutter_units_free ()

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

`units` : | the ClutterUnits to free

Since 1.0

### clutter_units_get_unit_type ()

    ClutterUnitType     clutter_units_get_unit_type         (const ClutterUnits *units);

Retrieves the unit type of the value stored inside `units`

`units` : | a ClutterUnits
Returns : | a unit type

Since 1.0

### clutter_units_get_unit_value ()

    gfloat              clutter_units_get_unit_value        (const ClutterUnits *units);

Retrieves the value stored inside `units`

`units` : | a ClutterUnits
Returns : | the value stored inside a ClutterUnits

Since 1.0

### clutter_units_from_string ()

    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

### Note

If no unit is specified, pixels are assumed.

`units` : | a ClutterUnits. [out caller-allocates]
`str` : | the string to convert
Returns : | `TRUE` if the string was successfully parsed, and `FALSE` otherwise

Since 1.0

### clutter_units_to_string ()

    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

### Note

Fractional values are truncated to the second decimal position for em, mm and cm, and to the first decimal position for typographic points. Pixels are integers.

`units` : | a ClutterUnits
Returns : | a newly allocated string containing the encoded ClutterUnits value. Use `g_free()` to free the string

Since 1.0

### struct ClutterParamSpecUnits

    struct ClutterParamSpecUnits {
      ClutterUnitType default_type;

      gfloat default_value;
      gfloat minimum;
      gfloat maximum;
    };

GParamSpec subclass for unit based properties.

ClutterUnitType `default_type`; | default type
gfloat `default_value`; | default value
gfloat `minimum`; | lower boundary
gfloat `maximum`; | higher boundary

Since 1.0

### clutter_param_spec_units ()

    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` : | name of the property
`nick` : | short name
`blurb` : | description (can be translatable)
`default_type` : | the default type for the ClutterUnits
`minimum` : | lower boundary
`maximum` : | higher boundary
`default_value` : | default value
`flags` : | flags for the param spec
Returns : | the newly created GParamSpec

Since 1.0

### CLUTTER_VALUE_HOLDS_UNITS()

    #define CLUTTER_VALUE_HOLDS_UNITS(x)    (G_VALUE_HOLDS ((x), CLUTTER_TYPE_UNITS))

Evaluates to `TRUE` if `x` holds a ClutterUnits value

`x` : | a GValue

Since 0.8

### clutter_value_set_units ()

    void                clutter_value_set_units             (GValue *value,
                                                             const ClutterUnits *units);

Sets `value` to `units`

`value` : | a GValue initialized to `CLUTTER_TYPE_UNITS`
`units` : | the units to set

Since 0.8

### clutter_value_get_units ()

    const ClutterUnits * clutter_value_get_units            (const GValue *value);

Gets the ClutterUnits contained in `value`.

`value` : | a GValue initialized to `CLUTTER_TYPE_UNITS`
Returns : | the units inside the passed GValue

Since 0.8