
@c %start of fragment

@node Unit conversion
@chapter Unit conversion
A logical distance unit

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

In order to register a @code{<clutter-units>} property, the
@code{<clutter-param-spec-units>}@code{<gparam>} sub-class should be
used:

@example 

  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);
@end example

A @code{<gvalue>} holding units can be manipulated using
@code{clutter-value-set-units} and @code{clutter-value-get-units}.
@code{<gvalue>}s containing a @code{<clutter-units>} value can also be
transformed to @code{<gvalue>}s initialized with @samp{G_TYPE_INT},
@samp{G_TYPE_FLOAT} and @samp{G_TYPE_STRING} through implicit conversion
and using @code{g-value-transform}.

@code{<clutter-units>} is available since Clutter 1.0

@section Usage
@include defuns-clutter-units.xml.texi

@c %end of fragment
