## gimpunit

gimpunit — Provides a collection of predefined units and functions for creating user-defined units.

## Synopsis

    enum                GimpUnit;
    gint                gimp_unit_get_number_of_units       (void);
    gint                gimp_unit_get_number_of_built_in_units
                                                            (void);
    GimpUnit            gimp_unit_new                       (gchar *identifier,
                                                             gdouble factor,
                                                             gint digits,
                                                             gchar *symbol,
                                                             gchar *abbreviation,
                                                             gchar *singular,
                                                             gchar *plural);
    gboolean            gimp_unit_get_deletion_flag         (GimpUnit unit);
    void                gimp_unit_set_deletion_flag         (GimpUnit unit,
                                                             gboolean deletion_flag);
    gdouble             gimp_unit_get_factor                (GimpUnit unit);
    gint                gimp_unit_get_digits                (GimpUnit unit);
    const gchar *       gimp_unit_get_identifier            (GimpUnit unit);
    const gchar *       gimp_unit_get_symbol                (GimpUnit unit);
    const gchar *       gimp_unit_get_abbreviation          (GimpUnit unit);
    const gchar *       gimp_unit_get_singular              (GimpUnit unit);
    const gchar *       gimp_unit_get_plural                (GimpUnit unit);
    gchar *             gimp_unit_format_string             (const gchar *format,
                                                             GimpUnit unit);
    gdouble             gimp_pixels_to_units                (gdouble pixels,
                                                             GimpUnit unit,
                                                             gdouble resolution);
    gdouble             gimp_units_to_pixels                (gdouble value,
                                                             GimpUnit unit,
                                                             gdouble resolution);
    gdouble             gimp_units_to_points                (gdouble value,
                                                             GimpUnit unit,
                                                             gdouble resolution);
    #define             GIMP_TYPE_UNIT
    #define             GIMP_TYPE_PARAM_UNIT
    #define             GIMP_IS_PARAM_SPEC_UNIT             (pspec)
    GParamSpec *        gimp_param_spec_unit                (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             gboolean allow_pixels,
                                                             gboolean allow_percent,
                                                             GimpUnit default_value,
                                                             GParamFlags flags);
    #define             GIMP_VALUE_HOLDS_UNIT               (value)

## Description

Provides a collection of predefined units and functions for creating user-defined units.

## Details

### enum GimpUnit

    typedef enum {
      GIMP_UNIT_PIXEL   = 0,

      GIMP_UNIT_INCH    = 1,
      GIMP_UNIT_MM      = 2,
      GIMP_UNIT_POINT   = 3,
      GIMP_UNIT_PICA    = 4,

      GIMP_UNIT_END     = 5,

      GIMP_UNIT_PERCENT = 65536 /*< pdb-skip >*/
    } GimpUnit;

`GIMP_UNIT_PIXEL` |
`GIMP_UNIT_INCH` |
`GIMP_UNIT_MM` |
`GIMP_UNIT_POINT` |
`GIMP_UNIT_PICA` |
`GIMP_UNIT_END` |
`GIMP_UNIT_PERCENT` |

### gimp_unit_get_number_of_units ()

    gint                gimp_unit_get_number_of_units       (void);

Returns the number of units which are known to the GimpUnit system.

Returns : | The number of defined units.

### gimp_unit_get_number_of_built_in_units ()

    gint                gimp_unit_get_number_of_built_in_units
                                                            (void);

Returns the number of GimpUnit's which are hardcoded in the unit system (UNIT_INCH, UNIT_MM, UNIT_POINT, UNIT_PICA and the two "pseudo unit" UNIT_PIXEL).

Returns : | The number of built-in units.

### gimp_unit_new ()

    GimpUnit            gimp_unit_new                       (gchar *identifier,
                                                             gdouble factor,
                                                             gint digits,
                                                             gchar *symbol,
                                                             gchar *abbreviation,
                                                             gchar *singular,
                                                             gchar *plural);

Returns the integer ID of the new GimpUnit.

Note that a new unit is always created with it's deletion flag set to `TRUE`. You will have to set it to `FALSE` with `gimp_unit_set_deletion_flag()` to make the unit definition persistent.

`identifier` : | The unit's identifier string.
`factor` : | The unit's factor (how many units are in one inch).
`digits` : | The unit's suggested number of digits (see `gimp_unit_get_digits()`).
`symbol` : | The symbol of the unit (e.g. "''" for inch).
`abbreviation` : | The abbreviation of the unit.
`singular` : | The singular form of the unit.
`plural` : | The plural form of the unit.
Returns : | The ID of the new unit.

### gimp_unit_get_deletion_flag ()

    gboolean            gimp_unit_get_deletion_flag         (GimpUnit unit);

`unit` : | The unit you want to know the `deletion_flag` of.
Returns : | The unit's `deletion_flag`.

### gimp_unit_set_deletion_flag ()

    void                gimp_unit_set_deletion_flag         (GimpUnit unit,
                                                             gboolean deletion_flag);

Sets a GimpUnit's `deletion_flag`. If the `deletion_flag` of a unit is `TRUE` when GIMP exits, this unit will not be saved in the users's "unitrc" file.

Trying to change the `deletion_flag` of a built-in unit will be silently ignored.

`unit` : | The unit you want to set the `deletion_flag` for.
`deletion_flag` : | The new deletion_flag.

### gimp_unit_get_factor ()

    gdouble             gimp_unit_get_factor                (GimpUnit unit);

A GimpUnit's `factor` is defined to be:

distance_in_units == (`factor` * distance_in_inches)

Returns 0 for `unit` == GIMP_UNIT_PIXEL.

`unit` : | The unit you want to know the factor of.
Returns : | The unit's factor.

### gimp_unit_get_digits ()

    gint                gimp_unit_get_digits                (GimpUnit unit);

Returns 0 for `unit` == GIMP_UNIT_PIXEL.

`unit` : | The unit you want to know the digits.
Returns : | The suggested number of digits.

### gimp_unit_get_identifier ()

    const gchar *       gimp_unit_get_identifier            (GimpUnit unit);

This is an unstranslated string and must not be changed or freed.

`unit` : | The unit you want to know the identifier of.
Returns : | The unit's identifier.

### gimp_unit_get_symbol ()

    const gchar *       gimp_unit_get_symbol                (GimpUnit unit);

This is e.g. "''" for UNIT_INCH.

NOTE: This string must not be changed or freed.

`unit` : | The unit you want to know the symbol of.
Returns : | The unit's symbol.

### gimp_unit_get_abbreviation ()

    const gchar *       gimp_unit_get_abbreviation          (GimpUnit unit);

For built-in units, this function returns the translated abbreviation of the unit.

NOTE: This string must not be changed or freed.

`unit` : | The unit you want to know the abbreviation of.
Returns : | The unit's abbreviation.

### gimp_unit_get_singular ()

    const gchar *       gimp_unit_get_singular              (GimpUnit unit);

For built-in units, this function returns the translated singular form of the unit's name.

NOTE: This string must not be changed or freed.

`unit` : | The unit you want to know the singular form of.
Returns : | The unit's singular form.

### gimp_unit_get_plural ()

    const gchar *       gimp_unit_get_plural                (GimpUnit unit);

For built-in units, this function returns the translated plural form of the unit's name.

NOTE: This string must not be changed or freed.

`unit` : | The unit you want to know the plural form of.
Returns : | The unit's plural form.

### gimp_unit_format_string ()

    gchar *             gimp_unit_format_string             (const gchar *format,
                                                             GimpUnit unit);

The `format` string supports the following percent expansions:

% f | Factor (how many units make up an inch)
% y | Symbol (e.g. "''" for GIMP_UNIT_INCH)
% a | Abbreviation
% s | Singular
% p | Plural
%% | Literal percent

`format` : | A printf-like format string which is used to create the unit string.
`unit` : | A unit.
Returns : | A newly allocated string with above percent expressions replaced with the resp. strings for `unit`.

Since GIMP 2.8

### gimp_pixels_to_units ()

    gdouble             gimp_pixels_to_units                (gdouble pixels,
                                                             GimpUnit unit,
                                                             gdouble resolution);

Converts a `value` specified in pixels to `unit`.

`pixels` : | value in pixels
`unit` : | unit to convert to
`resolution` : | resloution in DPI
Returns : | `pixels` converted to units.

Since GIMP 2.8

### gimp_units_to_pixels ()

    gdouble             gimp_units_to_pixels                (gdouble value,
                                                             GimpUnit unit,
                                                             gdouble resolution);

Converts a `value` specified in `unit` to pixels.

`value` : | value in units
`unit` : | unit of `value`
`resolution` : | resloution in DPI
Returns : | `value` converted to pixels.

Since GIMP 2.8

### gimp_units_to_points ()

    gdouble             gimp_units_to_points                (gdouble value,
                                                             GimpUnit unit,
                                                             gdouble resolution);

Converts a `value` specified in `unit` to points.

`value` : | value in units
`unit` : | unit of `value`
`resolution` : | resloution in DPI
Returns : | `value` converted to points.

Since GIMP 2.8

### GIMP_TYPE_UNIT

    #define GIMP_TYPE_UNIT               (gimp_unit_get_type ())

GIMP_TYPE_UNIT is a GType derived from G_TYPE_INT.

### GIMP_TYPE_PARAM_UNIT

    #define GIMP_TYPE_PARAM_UNIT              (gimp_param_unit_get_type ())

### GIMP_IS_PARAM_SPEC_UNIT()

    #define GIMP_IS_PARAM_SPEC_UNIT(pspec)    (G_TYPE_CHECK_INSTANCE_TYPE ((pspec), GIMP_TYPE_PARAM_UNIT))

### gimp_param_spec_unit ()

    GParamSpec *        gimp_param_spec_unit                (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             gboolean allow_pixels,
                                                             gboolean allow_percent,
                                                             GimpUnit default_value,
                                                             GParamFlags flags);

Creates a param spec to hold a units param. See `g_param_spec_internal()` for more information.

`name` : | Canonical name of the param
`nick` : | Nickname of the param
`blurb` : | Brief desciption of param.
`allow_pixels` : | Whether "pixels" is an allowed unit.
`allow_percent` : | Whether "perecent" is an allowed unit.
`default_value` : | Unit to use if none is assigned.
`flags` : | a combination of GParamFlags
Returns : | a newly allocated GParamSpec instance

Since GIMP 2.4

### GIMP_VALUE_HOLDS_UNIT()

    #define GIMP_VALUE_HOLDS_UNIT(value) (G_TYPE_CHECK_VALUE_TYPE ((value), GIMP_TYPE_UNIT))

## See Also

GimpUnitMenu, GimpSizeEntry.