gimpunit: GIMP Base Library Reference Manual

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

## Functions

gint | gimp_unit_get_number_of_units ()
gint | gimp_unit_get_number_of_built_in_units ()
GimpUnit | gimp_unit_new ()
gboolean | gimp_unit_get_deletion_flag ()
void | gimp_unit_set_deletion_flag ()
gdouble | gimp_unit_get_factor ()
gint | gimp_unit_get_digits ()
const gchar * | gimp_unit_get_identifier ()
const gchar * | gimp_unit_get_symbol ()
const gchar * | gimp_unit_get_abbreviation ()
const gchar * | gimp_unit_get_singular ()
const gchar * | gimp_unit_get_plural ()
gchar * | gimp_unit_format_string ()
gdouble | gimp_pixels_to_units ()
gdouble | gimp_units_to_pixels ()
gdouble | gimp_units_to_points ()
#define | GIMP_IS_PARAM_SPEC_UNIT()
GParamSpec * | gimp_param_spec_unit ()
#define | GIMP_VALUE_HOLDS_UNIT()

## Types and Values

enum | GimpUnit
#define | GIMP_TYPE_UNIT
#define | GIMP_TYPE_PARAM_UNIT

## Description

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

## Functions

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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 the number of digits an entry field should provide to get approximately the same accuracy as an inch input field with two digits.

Returns 0 for `unit` == GIMP_UNIT_PIXEL.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

value | value in units |
unit | unit of `value` |
resolution | resloution in DPI |

#### Returns

`value` converted to points.

Since: GIMP 2.8

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

#### Parameters

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

## Types and Values

### enum GimpUnit

#### Members

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

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

## See Also

GimpUnitMenu, GimpSizeEntry.