GimpSizeEntry: GIMP Widgets Library Reference Manual

GimpSizeEntry

GimpSizeEntry — Widget for entering pixel values and resolutions.

Functions

GtkWidget *	gimp_size_entry_new ()
void	gimp_size_entry_add_field ()
GtkWidget *	gimp_size_entry_attach_label ()
void	gimp_size_entry_set_resolution ()
void	gimp_size_entry_set_size ()
void	gimp_size_entry_set_value_boundaries ()
gdouble	gimp_size_entry_get_value ()
void	gimp_size_entry_set_value ()
void	gimp_size_entry_set_refval_boundaries ()
void	gimp_size_entry_set_refval_digits ()
gdouble	gimp_size_entry_get_refval ()
void	gimp_size_entry_set_refval ()
GimpUnit	gimp_size_entry_get_unit ()
void	gimp_size_entry_set_unit ()
void	gimp_size_entry_set_pixel_digits ()
void	gimp_size_entry_show_unit_menu ()
void	gimp_size_entry_grab_focus ()
void	gimp_size_entry_set_activates_default ()
GtkWidget *	gimp_size_entry_get_help_widget ()

Signals

void	refval-changed	Run First
void	unit-changed	Run First
void	value-changed	Run First

Types and Values

	GimpSizeEntry
	GimpSizeEntryField
enum	GimpSizeEntryUpdatePolicy

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkObject
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkTable
                        ╰── GimpSizeEntry

Implemented Interfaces

GimpSizeEntry implements AtkImplementorIface and GtkBuildable.

Description

This widget is used to enter pixel distances/sizes and resolutions.

You can specify the number of fields the widget should provide. For each field automatic mappings are performed between the field's "reference value" and its "value".

There is a GimpUnitComboBox right of the entry fields which lets you specify the GimpUnit of the displayed values.

For each field, there can be one or two GtkSpinButton's to enter "value" and "reference value". If you specify show_refval as FALSE in gimp_size_entry_new() there will be only one GtkSpinButton and the GimpUnitComboBox will contain an item for selecting GIMP_UNIT_PIXEL.

The "reference value" is either of GIMP_UNIT_PIXEL or dpi, depending on which GimpSizeEntryUpdatePolicy you specify in gimp_size_entry_new(). The "value" is either the size in pixels mapped to the size in a real-world-unit (see GimpUnit) or the dpi value mapped to pixels per real-world-unit.

Functions

gimp_size_entry_new ()

GtkWidget *
gimp_size_entry_new (gint number_of_fields,
                     GimpUnit unit,
                     const gchar *unit_format,
                     gboolean menu_show_pixels,
                     gboolean menu_show_percent,
                     gboolean show_refval,
                     gint spinbutton_width,
                     GimpSizeEntryUpdatePolicy update_policy);

Creates a new GimpSizeEntry widget.

To have all automatic calculations performed correctly, set up the widget in the following order:

gimp_size_entry_new()
(for each additional input field) gimp_size_entry_add_field()
gimp_size_entry_set_unit()

For each input field:

gimp_size_entry_set_resolution()
gimp_size_entry_set_refval_boundaries() (or gimp_size_entry_set_value_boundaries())
gimp_size_entry_set_size()
gimp_size_entry_set_refval() (or gimp_size_entry_set_value())

The GimpSizeEntry is derived from GtkTable and will have an empty border of one cell width on each side plus an empty column left of the GimpUnitComboBox to allow the caller to add labels or a GimpChainButton.

Parameters

number_of_fields	The number of input fields.
unit	The initial unit.
unit_format	A printf-like unit-format string as is used with `gimp_unit_menu_new()`.
menu_show_pixels	`TRUE` if the unit menu should contain an item for GIMP_UNIT_PIXEL (ignored if the `update_policy` is not GIMP_SIZE_ENTRY_UPDATE_NONE).
menu_show_percent	`TRUE` if the unit menu should contain an item for GIMP_UNIT_PERCENT.
show_refval	`TRUE` if you want an extra "reference value" spinbutton per input field.
spinbutton_width	The minimal horizontal size of the GtkSpinButton's.
update_policy	How the automatic pixel <-> real-world-unit calculations should be done.

Returns

A Pointer to the new GimpSizeEntry widget.

gimp_size_entry_add_field ()

void
gimp_size_entry_add_field (GimpSizeEntry *gse,
                           GtkSpinButton *value_spinbutton,
                           GtkSpinButton *refval_spinbutton);

Adds an input field to the GimpSizeEntry.

The new input field will have the index 0. If you specified show_refval as TRUE in gimp_size_entry_new() you have to pass an additional GtkSpinButton to hold the reference value. If show_refval was FALSE, refval_spinbutton will be ignored.

Parameters

gse	The sizeentry you want to add a field to.
value_spinbutton	The spinbutton to display the field's value.
refval_spinbutton	The spinbutton to display the field's reference value.

gimp_size_entry_attach_label ()

GtkWidget *
gimp_size_entry_attach_label (GimpSizeEntry *gse,
                              const gchar *text,
                              gint row,
                              gint column,
                              gfloat alignment);

Attaches a GtkLabel to the GimpSizeEntry (which is a GtkTable).

Parameters

gse	The sizeentry you want to add a label to.
text	The text of the label.
row	The row where the label will be attached.
column	The column where the label will be attached.
alignment	The horizontal alignment of the label.

Returns

A pointer to the new GtkLabel widget.

gimp_size_entry_set_resolution ()

void
gimp_size_entry_set_resolution (GimpSizeEntry *gse,
                                gint field,
                                gdouble resolution,
                                gboolean keep_size);

Sets the resolution (in dpi) for field # field of the GimpSizeEntry.

The resolution passed will be clamped to fit in [GIMP_MIN_RESOLUTION..GIMP_MAX_RESOLUTION].

This function does nothing if the GimpSizeEntryUpdatePolicy specified in gimp_size_entry_new() doesn't equal to GIMP_SIZE_ENTRY_UPDATE_SIZE.

Parameters

gse	The sizeentry you want to set a resolution for.
field	The index of the field you want to set the resolution for.
resolution	The new resolution (in dpi) for the chosen `field` .
keep_size	`TRUE` if the `field` 's size in pixels should stay the same. `FALSE` if the `field` 's size in units should stay the same.

gimp_size_entry_set_size ()

void
gimp_size_entry_set_size (GimpSizeEntry *gse,
                          gint field,
                          gdouble lower,
                          gdouble upper);

Sets the pixel values for field # field of the GimpSizeEntry which will be treated as 0% and 100%.

These values will be used if you specified menu_show_percent as TRUE in gimp_size_entry_new() and the user has selected GIMP_UNIT_PERCENT in the GimpSizeEntry's GimpUnitComboBox.

This function does nothing if the GimpSizeEntryUpdatePolicy specified in gimp_size_entry_new() doesn't equal to GIMP_SIZE_ENTRY_UPDATE_SIZE.

Parameters

gse	The sizeentry you want to set a size for.
field	The index of the field you want to set the size for.
lower	The reference value which will be treated as 0%.
upper	The reference value which will be treated as 100%.

gimp_size_entry_set_value_boundaries ()

void
gimp_size_entry_set_value_boundaries (GimpSizeEntry *gse,
                                      gint field,
                                      gdouble lower,
                                      gdouble upper);

Limits the range of possible values which can be entered in field # field of the GimpSizeEntry.

The current value of the field will be clamped to fit in the field 's new boundaries.

NOTE: In most cases you won't be interested in this function because the GimpSizeEntry's purpose is to shield the programmer from unit calculations. Use gimp_size_entry_set_refval_boundaries() instead. Whatever you do, don't mix these calls. A size entry should either be clamped by the value or the reference value.

Parameters

gse	The sizeentry you want to set value boundaries for.
field	The index of the field you want to set value boundaries for.
lower	The new lower boundary of the value of the chosen `field` .
upper	The new upper boundary of the value of the chosen `field` .

gimp_size_entry_get_value ()

gdouble
gimp_size_entry_get_value (GimpSizeEntry *gse,
                           gint field);

Returns the value of field # field of the GimpSizeEntry.

The value returned is a distance or resolution in the GimpUnit the user has selected in the GimpSizeEntry's GimpUnitComboBox.

NOTE: In most cases you won't be interested in this value because the GimpSizeEntry's purpose is to shield the programmer from unit calculations. Use gimp_size_entry_get_refval() instead.

Parameters

gse	The sizeentry you want to know a value of.
field	The index of the field you want to know the value of.

Returns

The value of the chosen field .

gimp_size_entry_set_value ()

void
gimp_size_entry_set_value (GimpSizeEntry *gse,
                           gint field,
                           gdouble value);

Sets the value for field # field of the GimpSizeEntry.

The value passed is treated to be a distance or resolution in the GimpUnit the user has selected in the GimpSizeEntry's GimpUnitComboBox.

NOTE: In most cases you won't be interested in this value because the GimpSizeEntry's purpose is to shield the programmer from unit calculations. Use gimp_size_entry_set_refval() instead.

Parameters

gse	The sizeentry you want to set a value for.
field	The index of the field you want to set a value for.
value	The new value for `field` .

gimp_size_entry_set_refval_boundaries ()

void
gimp_size_entry_set_refval_boundaries (GimpSizeEntry *gse,
                                       gint field,
                                       gdouble lower,
                                       gdouble upper);

Limits the range of possible reference values which can be entered in field # field of the GimpSizeEntry.

The current reference value of the field will be clamped to fit in the field 's new boundaries.

Parameters

gse	The sizeentry you want to set the reference value boundaries for.
field	The index of the field you want to set the reference value boundaries for.
lower	The new lower boundary of the reference value of the chosen `field` .
upper	The new upper boundary of the reference value of the chosen `field` .

gimp_size_entry_set_refval_digits ()

void
gimp_size_entry_set_refval_digits (GimpSizeEntry *gse,
                                   gint field,
                                   gint digits);

Sets the decimal digits of field # field of the GimpSizeEntry to digits .

If you don't specify this value explicitly, the reference value's number of digits will equal to 0 for GIMP_SIZE_ENTRY_UPDATE_SIZE and to 2 for GIMP_SIZE_ENTRY_UPDATE_RESOLUTION.

Parameters

gse	The sizeentry you want to set the reference value digits for.
field	The index of the field you want to set the reference value for.
digits	The new number of decimal digits for the GtkSpinButton which displays `field` 's reference value.

gimp_size_entry_get_refval ()

gdouble
gimp_size_entry_get_refval (GimpSizeEntry *gse,
                            gint field);

Returns the reference value for field # field of the GimpSizeEntry.

The reference value is either a distance in pixels or a resolution in dpi, depending on which GimpSizeEntryUpdatePolicy you chose in gimp_size_entry_new().

Parameters

gse	The sizeentry you want to know a reference value of.
field	The index of the field you want to know the reference value of.

Returns

The reference value of the chosen field .

gimp_size_entry_set_refval ()

void
gimp_size_entry_set_refval (GimpSizeEntry *gse,
                            gint field,
                            gdouble refval);

Sets the reference value for field # field of the GimpSizeEntry.

The refval passed is either a distance in pixels or a resolution in dpi, depending on which GimpSizeEntryUpdatePolicy you chose in gimp_size_entry_new().

Parameters

gse	The sizeentry you want to set a reference value for.
field	The index of the field you want to set the reference value for.
refval	The new reference value for `field` .

gimp_size_entry_get_unit ()

GimpUnit
gimp_size_entry_get_unit (GimpSizeEntry *gse);

Returns the GimpUnit the user has selected in the GimpSizeEntry's GimpUnitComboBox.

Parameters

gse

The sizeentry you want to know the unit of.

Returns

The sizeentry's unit.

gimp_size_entry_set_unit ()

void
gimp_size_entry_set_unit (GimpSizeEntry *gse,
                          GimpUnit unit);

Sets the GimpSizeEntry's unit. The reference value for all fields will stay the same but the value in units or pixels per unit will change according to which GimpSizeEntryUpdatePolicy you chose in gimp_size_entry_new().

Parameters

gse	The sizeentry you want to change the unit for.
unit	The new unit.

gimp_size_entry_set_pixel_digits ()

void
gimp_size_entry_set_pixel_digits (GimpSizeEntry *gse,
                                  gint digits);

This function allows you set up a GimpSizeEntry so that sub-pixel sizes can be entered.

Parameters

gse	a GimpSizeEntry
digits	the number of digits to display for a pixel size

gimp_size_entry_show_unit_menu ()

void
gimp_size_entry_show_unit_menu (GimpSizeEntry *gse,
                                gboolean show);

Controls whether a unit menu is shown in the size entry. If show is TRUE, the menu is shown; otherwise it is hidden.

Parameters

gse	a GimpSizeEntry
show	Boolean

Since: 2.4

gimp_size_entry_grab_focus ()

void
gimp_size_entry_grab_focus (GimpSizeEntry *gse);

This function is rather ugly and just a workaround for the fact that it's impossible to implement gtk_widget_grab_focus() for a GtkTable.

Parameters

gse

The sizeentry you want to grab the keyboard focus.

gimp_size_entry_set_activates_default ()

void
gimp_size_entry_set_activates_default (GimpSizeEntry *gse,
                                       gboolean setting);

Iterates over all entries in the GimpSizeEntry and calls gtk_entry_set_activates_default() on them.

Parameters

gse	A GimpSizeEntry
setting	`TRUE` to activate window's default widget on Enter keypress

Since: 2.4

gimp_size_entry_get_help_widget ()

GtkWidget *
gimp_size_entry_get_help_widget (GimpSizeEntry *gse,
                                 gint field);

You shouldn't fiddle with the internals of a GimpSizeEntry but if you want to set tooltips using gimp_help_set_help_data() you can use this function to get a pointer to the spinbuttons.

Parameters

gse	a GimpSizeEntry
field	the index of the widget you want to get a pointer to

Returns

a GtkWidget pointer that you can attach a tooltip to.

Types and Values

GimpSizeEntry

typedef struct _GimpSizeEntry GimpSizeEntry;

GimpSizeEntryField

typedef struct _GimpSizeEntryField GimpSizeEntryField;

enum GimpSizeEntryUpdatePolicy

Update policies for GimpSizeEntry.

Members

GIMP_SIZE_ENTRY_UPDATE_NONE	the size entry's meaning is up to the user
GIMP_SIZE_ENTRY_UPDATE_SIZE	the size entry displays values
GIMP_SIZE_ENTRY_UPDATE_RESOLUTION	the size entry displays resolutions

Signal Details

The `“refval-changed”` signal

void
user_function (GimpSizeEntry *gimpsizeentry,
               gpointer       user_data)

Flags: Run First

The `“unit-changed”` signal

void
user_function (GimpSizeEntry *gimpsizeentry,
               gpointer       user_data)

Flags: Run First

The `“value-changed”` signal

void
user_function (GimpSizeEntry *gimpsizeentry,
               gpointer       user_data)

Flags: Run First

GimpSizeEntry

Functions

Signals

Types and Values

Object Hierarchy

Implemented Interfaces

Description

Functions

gimp_size_entry_new ()

Parameters

Returns

gimp_size_entry_add_field ()

Parameters

gimp_size_entry_attach_label ()

Parameters

Returns

gimp_size_entry_set_resolution ()

Parameters

gimp_size_entry_set_size ()

Parameters

gimp_size_entry_set_value_boundaries ()

Parameters

gimp_size_entry_get_value ()

Parameters

Returns

gimp_size_entry_set_value ()

Parameters

gimp_size_entry_set_refval_boundaries ()

Parameters

gimp_size_entry_set_refval_digits ()

Parameters

gimp_size_entry_get_refval ()

Parameters

Returns

gimp_size_entry_set_refval ()

Parameters

gimp_size_entry_get_unit ()

Parameters

Returns

gimp_size_entry_set_unit ()

Parameters

gimp_size_entry_set_pixel_digits ()

Parameters

gimp_size_entry_show_unit_menu ()

Parameters

gimp_size_entry_grab_focus ()

Parameters

gimp_size_entry_set_activates_default ()

Parameters

gimp_size_entry_get_help_widget ()

Parameters

Returns

Types and Values

GimpSizeEntry

GimpSizeEntryField

enum GimpSizeEntryUpdatePolicy

Members

Signal Details

The “refval-changed” signal

The “unit-changed” signal

The “value-changed” signal

See Also

The `“refval-changed”` signal

The `“unit-changed”` signal

The `“value-changed”` signal