gimpunit

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

Functions

Types and Values

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.