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 ()
gint | gimp_unit_get_scaled_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 ()
gboolean | gimp_unit_is_metric ()
#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 its 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 set for `unit` . Built-in units' accuracy is approximately the same as an inch with two digits. User-defined units can suggest a different accuracy.

Note: the value is as-set by defaults or by the user and does not necessary provide enough precision on high-resolution images. When the information is needed for a specific image, the use of `gimp_unit_get_scaled_digits()` may be more appropriate.

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

    gint
    gimp_unit_get_scaled_digits (GimpUnit unit,
                                 gdouble resolution);

Returns the number of digits a `unit` field should provide to get enough accuracy so that every pixel position shows a different value from neighboring pixels.

Note: when needing digit accuracy to display a diagonal distance, the `resolution` may not correspond to the image's horizontal or vertical resolution, but instead to the result of: `distance_in_pixel / distance_in_inch`.

#### Parameters

unit | The unit you want to know the digits. |
resolution | the resolution in PPI. |

#### Returns

The suggested number of digits.

### gimp_unit_get_identifier ()

    const gchar *
    gimp_unit_get_identifier (GimpUnit unit);

This is an untranslated 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: 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 | resolution in DPI |

#### Returns

`pixels` converted to units.

Since: 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: 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: 2.8

### gimp_unit_is_metric ()

    gboolean
    gimp_unit_is_metric (GimpUnit unit);

Checks if the given `unit` is metric. A simplistic test is used that looks at the unit's factor and checks if it is 2.54 multiplied by some common powers of 10. Currently it checks for mm, cm, dm, m.

See also: `gimp_unit_get_factor()`

#### Parameters

unit | The unit |

#### Returns

`TRUE` if the `unit` is metric.

Since: 2.10

### 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 description of param. |
allow_pixels | Whether "pixels" is an allowed unit. |
allow_percent | Whether "percent" 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: 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

Units used for dimensions in images.

#### Members

GIMP_UNIT_PIXEL | Pixels |
GIMP_UNIT_INCH | Inches |
GIMP_UNIT_MM | Millimeters |
GIMP_UNIT_POINT | Points |
GIMP_UNIT_PICA | Picas |
GIMP_UNIT_END | Marker for end-of-builtin-units |
GIMP_UNIT_PERCENT | Pseudo-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.