Gimp.Unit¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`format_string` (format, unit)
class	`get_by_id` (unit_id)
class	`inch` ()
class	`mm` ()
class	`new` (name, factor, digits, symbol, abbreviation)
class	`percent` ()
class	`pica` ()
class	`pixel` ()
class	`point` ()
	`get_abbreviation` ()
	`get_deletion_flag` ()
	`get_digits` ()
	`get_factor` ()
	`get_id` ()
	`get_name` ()
	`get_scaled_digits` (resolution)
	`get_symbol` ()
	`is_built_in` ()
	`is_metric` ()
	`set_deletion_flag` (deletion_flag)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags
`abbreviation`	`str`	r/w/co
`digits`	`int`	r/w/co
`factor`	`float`	r/w/co
`id`	`int`	r/w/co
`name`	`str`	r/w/co
`symbol`	`str`	r/w/co

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class Gimp.Unit(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Gimp.UnitClass

Provides operations on units, a collection of predefined units and functions to create new units.

classmethod format_string(format, unit)¶

Parameters:

format (str) – A printf-like format string which is used to create the unit string.
unit (Gimp.Unit) – A unit.

Returns:

A newly allocated string with above percent expressions replaced with the resp. strings for unit.

Return type:

str

The format string supports the following percent expansions:

%n: Name (long label)
%a: Abbreviation (short label)
%%: Literal percent
%f: Factor (how many units make up an inch)
%y: Symbol (e.g. '' for GIMP_UNIT_INCH)

New in version 2.8.

classmethod get_by_id(unit_id)¶

Parameters:: unit_id (int) – The unit id.
Returns:: the Gimp.Unit object with ID unit_id.
Return type:: Gimp.Unit

Returns the unique [class`Unit`] object corresponding to unit_id, which is the integer identifier as returned by [method`Unit`.get_id].

New in version 3.0.

classmethod inch()¶

Returns:: The unique inch unit.
Return type:: Gimp.Unit

Returns the unique object representing inch unit.

This procedure returns the unit representing inch. The returned object is unique across the whole run.

New in version 3.0.

classmethod mm()¶

Returns:: The unique millimeter unit.
Return type:: Gimp.Unit

Returns the unique object representing millimeter unit.

This procedure returns the unit representing millimeter. The returned object is unique across the whole run.

New in version 3.0.

classmethod new(name, factor, digits, symbol, abbreviation)¶

Parameters:

name (str) – The new unit’s name.
factor (float) – The new unit’s factor.
digits (int) – The new unit’s digits.
symbol (str) – The new unit’s symbol.
abbreviation (str) – The new unit’s abbreviation.

Returns:

The new unit.

Return type:

Gimp.Unit

Creates a new unit.

This procedure creates a new unit and returns it. Note that the new unit will have it’s deletion flag set to True, so you will have to set it to False with Gimp.Unit.set_deletion_flag() to make it persistent.

classmethod percent()¶

Returns:: The unique percent unit.
Return type:: Gimp.Unit

Returns the unique object representing percent dimensions relatively to an image.

This procedure returns the unit representing typographical points. The returned object is unique across the whole run.

New in version 3.0.

classmethod pica()¶

Returns:: The unique pica unit.
Return type:: Gimp.Unit

Returns the unique object representing Pica unit.

This procedure returns the unit representing Picas. The returned object is unique across the whole run.

New in version 3.0.

classmethod pixel()¶

Returns:: The unique pixel unit.
Return type:: Gimp.Unit

Returns the unique object representing pixel unit.

This procedure returns the unit representing pixel. The returned object is unique across the whole run.

New in version 3.0.

classmethod point()¶

Returns:: The unique point unit.
Return type:: Gimp.Unit

Returns the unique object representing typographical point unit.

This procedure returns the unit representing typographical points. The returned object is unique across the whole run.

New in version 3.0.

get_abbreviation()¶

Returns:: The unit’s abbreviation.
Return type:: str

This function returns the abbreviation of the unit (e.g. “in” for inches). It can be used as a short label for the unit in the interface. For long labels, use [method`Unit`.get_name].

NOTE: This string must not be changed or freed.

get_deletion_flag()¶

Returns:: The unit’s deletion_flag.
Return type:: bool

get_digits()¶

Returns:: The suggested number of digits.
Return type:: int

Returns the number of digits set for self. 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 units. When the information is needed for a specific unit, the use of Gimp.Unit.get_scaled_digits() may be more appropriate.

Returns 0 for self == Gimp.UnitID.PIXEL.

get_factor()¶

Returns:: The unit’s factor.
Return type:: float

A Gimp.Unit's factor is defined to be:

distance_in_units == (factor * distance_in_inches)

Returns 0 for self == Gimp.UnitID.PIXEL.

get_id()¶

Returns:: The unit’s ID.
Return type:: int

The ID can be used to retrieve the unit with [func`Unit`.get_by_id].

Note that this ID will be stable within a single session of GIMP, but you should not expect this ID to stay the same across multiple runs.

get_name()¶

Returns:: The unit’s name.
Return type:: str

This function returns the usual name of the unit (e.g. “inches”). It can be used as the long label for the unit in the interface. For short labels, use [method`Unit`.get_abbreviation].

NOTE: This string must not be changed or freed.

get_scaled_digits(resolution)¶

Parameters:: resolution (float) – the resolution in PPI.
Returns:: The suggested number of digits.
Return type:: int

Returns the number of digits a self 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 unit’s horizontal or vertical resolution, but instead to the result of: distance_in_pixel / distance_in_inch.

get_symbol()¶

Returns:: The unit’s symbol.
Return type:: str

This is e.g. “’’” for UNIT_INCH.

NOTE: This string must not be changed or freed.

is_built_in()¶

Returns:: Whether self is built-in.
Return type:: bool

Returns whether the unit is built-in.

This procedure returns self is a built-in unit. In particular the deletion flag cannot be set on built-in units.

New in version 3.0.

is_metric()¶

Returns:: True if the self is metric.
Return type:: bool

Checks if the given self 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.

Property Details¶

Gimp.Unit.props.abbreviation¶

Name:: abbreviation
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

Gimp.Unit.props.digits¶

Name:: digits
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

Gimp.Unit.props.factor¶

Name:: factor
Type:: float
Default Value:: 1.0
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

Gimp.Unit.props.id¶

Name:: id
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

Gimp.Unit.props.name¶

Name:: name
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

Gimp.Unit.props.symbol¶

Name:: symbol
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY