Unit conversion
3
CLUTTER Library

# Unit conversion

A logical distance unit

## Synopsis

    enum                ClutterUnitType;
                        ClutterUnits;
    void                clutter_units_from_mm               (ClutterUnits *units,
                                                             gfloat mm);
    void                clutter_units_from_pt               (ClutterUnits *units,
                                                             gfloat pt);
    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_pixels           (ClutterUnits *units,
                                                             gint px);
    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);

## 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 ""`allocate()` virtual function, or inside the ""`get_preferred_width()` and ""`get_preferred_height()` virtual functions.

In order to register a ClutterUnits property, the ClutterParamSpecUnits GParamSpec sub-class should be used:

      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
    } 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

Since 1.0

### ClutterUnits

    typedef struct {
    } ClutterUnits;

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

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

`mm` :

  millimeters

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

`pt` :

  typographic points

Since 1.0

### 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

`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

`font_name` :

  the font name and size

`em` :

  em

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

`px` :

  pixels

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

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:

      number: [0-9]
      unit_value: <number>+
      unit_name: px|pt|mm|em
      units: <unit_value> <unit_name>

For instance, these are valid strings:

      10 px
      5.1 em
      24 pt
      12.6 mm

While these are not:

      42 cats
      omg!1!ponies

If no unit is specified, pixels are assumed.

`units` :

  a ClutterUnits

`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

Fractional values are truncated to the second decimal position for em and mm, 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

### ClutterParamSpecUnits

    typedef struct {
      ClutterUnitType default_type;

      gfloat default_value;
      gfloat minimum;
      gfloat maximum;
    } ClutterParamSpecUnits;

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_UNIT

`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_UNIT

Returns :

  the units inside the passed GValue

Since 0.8