GNOME.org

Unit conversion

Unit conversion — A logical distance unit

Synopsis

enum                ClutterUnitType;
struct              ClutterUnits;
void                clutter_units_from_cm               (ClutterUnits *units,
                                                         gfloat cm);
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_mm               (ClutterUnits *units,
                                                         gfloat mm);
void                clutter_units_from_pixels           (ClutterUnits *units,
                                                         gint px);
void                clutter_units_from_pt               (ClutterUnits *units,
                                                         gfloat pt);
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);

struct              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 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(). 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 {
 /*< prefix=CLUTTER_UNIT >*/
  CLUTTER_UNIT_PIXEL,
  CLUTTER_UNIT_EM,
  CLUTTER_UNIT_MM,
  CLUTTER_UNIT_POINT,
  CLUTTER_UNIT_CM
} 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

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

clutter_units_from_cm ()

void                clutter_units_from_cm               (ClutterUnits *units,
                                                         gfloat cm);

Stores a value in centimeters inside units

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

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

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

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

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

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

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. [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()

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: 

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: (<GTKDOCLINK HREF="0x20">0x20</GTKDOCLINK> | <GTKDOCLINK HREF="0x9">0x9</GTKDOCLINK> | <GTKDOCLINK HREF="0xA">0xA</GTKDOCLINK> | <GTKDOCLINK HREF="0xB">0xB</GTKDOCLINK> | <GTKDOCLINK HREF="0xC">0xC</GTKDOCLINK> | <GTKDOCLINK HREF="0xD">0xD</GTKDOCLINK>)+

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

Note

If no unit is specified, pixels are assumed.

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

Note

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 ClutterUnits

Returns :

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

Since 1.0

struct ClutterParamSpecUnits

struct ClutterParamSpecUnits {
  ClutterUnitType default_type;

  gfloat default_value;
  gfloat minimum;
  gfloat maximum;
};

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

value :

 a GValue initialized to CLUTTER_TYPE_UNITS

Returns :

 the units inside the passed GValue

Since 0.8

Generated by GTK-Doc V1.18.1