Unit conversion

Unit conversion — A logical distance unit

Synopsis

enum                ClutterUnitType;
                    ClutterUnits;
void                clutter_units_mm                    (ClutterUnits *units,
                                                         gfloat mm);
void                clutter_units_pt                    (ClutterUnits *units,
                                                         gfloat pt);
void                clutter_units_em                    (ClutterUnits *units,
                                                         gfloat em);
void                clutter_units_em_for_font           (ClutterUnits *units,
                                                         const gchar *font_name,
                                                         gfloat em);
void                clutter_units_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_mm ()

void                clutter_units_mm                    (ClutterUnits *units,
                                                         gfloat mm);

Stores a value in millimiters inside units

units :

a ClutterUnits

mm :

millimeters

Since 1.0


clutter_units_pt ()

void                clutter_units_pt                    (ClutterUnits *units,
                                                         gfloat pt);

Stores a value in typographic points inside units

units :

a ClutterUnits

pt :

typographic points

Since 1.0


clutter_units_em ()

void                clutter_units_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_em_for_font ()

void                clutter_units_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_pixels ()

void                clutter_units_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: <numbers>+
  unit_name: px|pt|mm|em
  units: <unit_value> <unit_name>

For instance, these are valid strings:

  10 px
  5 em
  24 pt
  12.6 mm

units :

a ClutterUnits

str :

the string to convert

Returns :

TRUE if the string was successfully parsed

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 outputs

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