Clutter Reference Manual: Unit conversion

## Unit conversion Unit conversion — A logical distance unit |

## Functions

void | clutter_units_from_cm ()
void | clutter_units_from_em ()
void | clutter_units_from_em_for_font ()
void | clutter_units_from_mm ()
void | clutter_units_from_pixels ()
void | clutter_units_from_pt ()
gfloat | clutter_units_to_pixels ()
ClutterUnits * | clutter_units_copy ()
void | clutter_units_free ()
ClutterUnitType | clutter_units_get_unit_type ()
gfloat | clutter_units_get_unit_value ()
gboolean | clutter_units_from_string ()
gchar * | clutter_units_to_string ()
GParamSpec * | clutter_param_spec_units ()
#define | CLUTTER_VALUE_HOLDS_UNITS()
void | clutter_value_set_units ()
const ClutterUnits * | clutter_value_get_units ()

## Types and Values

enum | ClutterUnitType
struct | ClutterUnits
struct | ClutterParamSpecUnits

## 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 `ClutterActorClass.allocate()` virtual function, or inside the `ClutterActorClass.get_preferred_width()` and `ClutterActorClass.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()`. GValue<!-- -->s containing a ClutterUnits value can also be transformed to GValue<!-- -->s 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

## Functions

### clutter_units_from_cm ()

    void
    clutter_units_from_cm (ClutterUnits *units,
                           gfloat cm);

Stores a value in centimeters inside `units`

#### Parameters

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

#### Parameters

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`

#### Parameters

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`

#### Parameters

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`

#### Parameters

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`

#### Parameters

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

#### Parameters

units | units to convert |

#### Returns

the value in pixels

Since 1.0

### clutter_units_copy ()

    ClutterUnits *
    clutter_units_copy (const ClutterUnits *units);

Copies `units`

#### Parameters

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

#### Parameters

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`

#### Parameters

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`

#### Parameters

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: (#0x20 | #0x9 | #0xA | #0xB | #0xC | #0xD)+

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.

#### Parameters

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

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.

#### Parameters

units | a ClutterUnits |

#### Returns

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

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.

#### Parameters

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

#### Parameters

x | a GValue |

Since 0.8

### clutter_value_set_units ()

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

Sets `value` to `units`

#### Parameters

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

#### Parameters

value | a GValue initialized to `CLUTTER_TYPE_UNITS` |

#### Returns

the units inside the passed GValue

Since 0.8

## Types and Values

### enum ClutterUnitType

The type of unit in which a value is expressed

This enumeration might be expanded at later date

#### Members

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

### struct ClutterParamSpecUnits

    struct ClutterParamSpecUnits {
      ClutterUnitType default_type;

      gfloat default_value;
      gfloat minimum;
      gfloat maximum;
    };

GParamSpec subclass for unit based properties.

#### Members

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

Since 1.0