GIMP Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# gimpunit

## Name

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);
    gchar*      gimp_unit_get_identifier        (GimpUnit unit);
    gchar*      gimp_unit_get_symbol            (GimpUnit unit);
    gchar*      gimp_unit_get_abbreviation      (GimpUnit unit);
    gchar*      gimp_unit_get_singular          (GimpUnit unit);
    gchar*      gimp_unit_get_plural            (GimpUnit unit);

## 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
    } GimpUnit;

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

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

### gimp_unit_get_identifier ()

    gchar*      gimp_unit_get_identifier        (GimpUnit unit);

This is an unstranslated string.

NOTE: This string has to be g_free()'d by plugins but is a pointer to a constant string when this function is used from inside the GIMP.

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

### gimp_unit_get_symbol ()

    gchar*      gimp_unit_get_symbol            (GimpUnit unit);

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

NOTE: This string has to be g_free()'d by plugins but is a pointer to a constant string when this function is used from inside the GIMP.

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

### gimp_unit_get_abbreviation ()

    gchar*      gimp_unit_get_abbreviation      (GimpUnit unit);

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

NOTE: This string has to be g_free()'d by plugins but is a pointer to a constant string when this function is used from inside the GIMP.

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

### gimp_unit_get_singular ()

    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 has to be g_free()'d by plugins but is a pointer to a constant string when this function is used from inside the GIMP.

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

### gimp_unit_get_plural ()

    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 has to be g_free()'d by plugins but is a pointer to a constant string when this function is used from inside the GIMP.

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

## See Also

GimpUnitMenu

GimpSizeEntry

<<< Previous Page | Home | Up | Next Page >>>
gimpundo | gimputils