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

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.
Generated by GTK-Doc V1.18