Next: , Previous: ClutterTransition, Up: Top

71 Unit conversion

A logical distance unit

71.1 Overview

<clutter-units> is a structure holding a logical distance value along with its type, expressed as a value of the <clutter-unit-type> enumeration. It is possible to use <clutter-units> to store a position or a size in units different than pixels, and convert them whenever needed (for instance inside the <clutter-actor>::allocate virtual function, or inside the <clutter-actor>::get-preferred-width and <clutter-actor>::get-preferred-height virtual functions.

In order to register a <clutter-units> property, the <clutter-param-spec-units><gparam> 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. <gvalue>s containing a <clutter-units> 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.

<clutter-units> is available since Clutter 1.0

71.2 Usage

— Function: clutter-units-from-cm (self <clutter-units>) (cm float)

Stores a value in centimeters inside units

units
a <clutter-units>.
cm
centimeters

Since 1.2

— Function: clutter-units-from-em (em float) ⇒  (ret <clutter-units>)

Stores a value in em inside units, using the default font name as returned by clutter-backend-get-font-name

units
a <clutter-units>.
em
em

Since 1.0

— Function: clutter-units-from-em-for-font (font_name mchars) (em float) ⇒  (ret <clutter-units>)

Stores a value in em inside units using font-name

units
a <clutter-units>.
font-name
the font name and size.
em
em

Since 1.0

— Function: clutter-units-from-mm (mm float) ⇒  (ret <clutter-units>)

Stores a value in millimiters inside units

units
a <clutter-units>.
mm
millimeters

Since 1.0

— Function: clutter-units-from-pixels (px int) ⇒  (ret <clutter-units>)

Stores a value in pixels inside units

units
a <clutter-units>.
px
pixels

Since 1.0

— Function: clutter-units-from-pt (pt float) ⇒  (ret <clutter-units>)

Stores a value in typographic points inside units

units
a <clutter-units>.
pt
typographic points

Since 1.0

— Function: clutter-units-to-pixels (self <clutter-units>) ⇒  (ret float)

Converts a value in <clutter-units> to pixels

units
units to convert
ret
the value in pixels

Since 1.0

— Function: clutter-units-get-unit-type (self <clutter-units>) ⇒  (ret <clutter-unit-type>)

Retrieves the unit type of the value stored inside units

units
a <clutter-units>
ret
a unit type

Since 1.0

— Function: clutter-units-get-unit-value (self <clutter-units>) ⇒  (ret float)

Retrieves the value stored inside units

units
a <clutter-units>
ret
the value stored inside a <clutter-units>

Since 1.0

— Function: clutter-units-from-string (str mchars) ⇒  (ret <clutter-units>)

Parses a value and updates units with it

A <clutter-units> expressed in string should match: 

          
            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: 

          
            10 px
            5.1 em
            24 pt
            12.6 mm
            .3 cm

While these are not: 

          
            42 cats
            omg!1!ponies

If no unit is specified, pixels are assumed.

units
a <clutter-units>.
str
the string to convert
ret
‘#t’ if the string was successfully parsed, and ‘#f’ otherwise

Since 1.0

— Function: clutter-units-to-string (self <clutter-units>) ⇒  (ret mchars)

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.

units
a <clutter-units>
ret
a newly allocated string containing the encoded <clutter-units> value. Use g-free to free the string

Since 1.0