# gnome-print-unit

## Name

gnome-print-unit --

## Synopsis

    struct      GnomePrintUnit;
    enum        GnomePrintUnitBase;
    #define     GNOME_PRINT_PS_UNIT
    #define     GNOME_PRINT_UNITS_ALL
    const GnomePrintUnit* gnome_print_unit_get_identity
                                                (guint base);
    const GnomePrintUnit* gnome_print_unit_get_default
                                                (void);
    const GnomePrintUnit* gnome_print_unit_get_by_name
                                                (const guchar *name);
    const GnomePrintUnit* gnome_print_unit_get_by_abbreviation
                                                (const guchar *abbreviation);
    GList*      gnome_print_unit_get_list       (guint bases);
    void        gnome_print_unit_free_list      (GList *units);
    gboolean    gnome_print_convert_distance    (gdouble *distance,
                                                 const GnomePrintUnit *from,
                                                 const GnomePrintUnit *to);
    gboolean    gnome_print_convert_distance_full
                                                (gdouble *distance,
                                                 const GnomePrintUnit *from,
                                                 const GnomePrintUnit *to,
                                                 gdouble ctmscale,
                                                 gdouble devicescale);

## Description

## Details

### >struct GnomePrintUnit

    struct GnomePrintUnit {

    	guint version : 8; /* Has to be 0 at moment */
    	guint base : 8; /* Base */
    	gdouble unittobase;
    	/* I am not absolutely sure, but seems that gettext can do the magic */
    	guchar *name;
    	guchar *abbr;
    	guchar *plural;
    	guchar *abbr_plural;
    };

### >enum GnomePrintUnitBase

    typedef enum {
    	GNOME_PRINT_UNIT_DIMENSIONLESS = (1 << 0), /* For percentages and like */
    	GNOME_PRINT_UNIT_ABSOLUTE = (1 << 1),      /* Real world distances - i.e. mm, cm... */
    	GNOME_PRINT_UNIT_DEVICE = (1 << 2),        /* Semi-real device-dependent distances i.e. pixels */
    	GNOME_PRINT_UNIT_USERSPACE = (1 << 3)      /* Mathematical coordinates */
    } GnomePrintUnitBase;

### >GNOME_PRINT_PS_UNIT

    #define GNOME_PRINT_PS_UNIT   (gnome_print_unit_get_identity (GNOME_PRINT_UNIT_ABSOLUTE))

The GnomePrintUnit structure that represents the absolute units.

### >GNOME_PRINT_UNITS_ALL

    #define GNOME_PRINT_UNITS_ALL (GNOME_PRINT_UNIT_DIMENSIONLESS | GNOME_PRINT_UNIT_ABSOLUTE | GNOME_PRINT_UNIT_DEVICE | GNOME_PRINT_UNIT_USERSPACE)

Convenience macro for all of the different GNOME_PRINT_UNIT_* macros.

### >gnome_print_unit_get_identity ()

    const GnomePrintUnit* gnome_print_unit_get_identity
                                                (guint base);

Retrieves the GnomePrintUnit structure referenced by base base.

base : | The base of the GnomePrintUnit to retrieve
Returns : | The GnomePrintUnit structure representing base. NULL on error

### >gnome_print_unit_get_default ()

    const GnomePrintUnit* gnome_print_unit_get_default
                                                (void);

Used to get the default GnomePrintUnit structure.

Returns : | A pointer to the default GnomePrintUnit structure

### >gnome_print_unit_get_by_name ()

    const GnomePrintUnit* gnome_print_unit_get_by_name
                                                (const guchar *name);

Get a unit based on its name, for example "Millimeter" or "Inches".

name : | Name of the unit, as a string pointer
Returns : | A constant pointer to a GnomePrintUnit, NULL on error

### >gnome_print_unit_get_by_abbreviation ()

    const GnomePrintUnit* gnome_print_unit_get_by_abbreviation
                                                (const guchar *abbreviation);

Get a unit based on its abbreviation, for example "cm" "pts" or "in".

abbreviation : | Abbreviation of the unit, as a string pointer
Returns : | A constant pointer to a GnomePrintUnit, NULL on error

### >gnome_print_unit_get_list ()

    GList*      gnome_print_unit_get_list       (guint bases);

Gets a list of the units represented by the bases bases. To get a list of all units then use GNOME_PRINT_UNITS_ALL. The list that is returned should be freed using gnome_print_unit_free_list.

bases : | The bases to include in the list
Returns : | A pointer to a GList, NULL on error

### >gnome_print_unit_free_list ()

    void        gnome_print_unit_free_list      (GList *units);

Used to free the list of units created by gnome_print_unit_get_list.

units : | A pointer to a GList to be freed

### >gnome_print_convert_distance ()

    gboolean    gnome_print_convert_distance    (gdouble *distance,
                                                 const GnomePrintUnit *from,
                                                 const GnomePrintUnit *to);

Check whether a conversion between from and to can be made

distance : | The distance to convert, and the converted value on success
from : | Units to convert from
to : | Units to convert to
Returns : | TRUE if the conversion is possible, FALSE if it is not or on error

### >gnome_print_convert_distance_full ()

    gboolean    gnome_print_convert_distance_full
                                                (gdouble *distance,
                                                 const GnomePrintUnit *from,
                                                 const GnomePrintUnit *to,
                                                 gdouble ctmscale,
                                                 gdouble devicescale);

Convert a distance from one unit to another. You should supply a scale as necessary.

ctmscale is userspace->absolute, devicescale is device->absolute

distance : | The distance to convert, and the result on success
from : | Units to convert from
to : | Units to convert to
ctmscale : | The userspace scale to use
devicescale : | The device scale to use
Returns : | TRUE if the conversion is possible, FALSE if it is not or on error