## GimpSizeEntry GimpSizeEntry — Widget for entering pixel values and resolutions. |

## Synopsis

                GimpSizeEntry;
                GimpSizeEntryField;
    enum        GimpSizeEntryUpdatePolicy;
    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);
    void        gimp_size_entry_add_field       (GimpSizeEntry *gse,
                                                 GtkSpinButton *value_spinbutton,
                                                 GtkSpinButton *refval_spinbutton);
    GtkWidget*  gimp_size_entry_attach_label    (GimpSizeEntry *gse,
                                                 const gchar *text,
                                                 gint row,
                                                 gint column,
                                                 gfloat alignment);
    void        gimp_size_entry_set_resolution  (GimpSizeEntry *gse,
                                                 gint field,
                                                 gdouble resolution,
                                                 gboolean keep_size);
    void        gimp_size_entry_set_size        (GimpSizeEntry *gse,
                                                 gint field,
                                                 gdouble lower,
                                                 gdouble upper);
    void        gimp_size_entry_set_value_boundaries
                                                (GimpSizeEntry *gse,
                                                 gint field,
                                                 gdouble lower,
                                                 gdouble upper);
    gdouble     gimp_size_entry_get_value       (GimpSizeEntry *gse,
                                                 gint field);
    void        gimp_size_entry_set_value       (GimpSizeEntry *gse,
                                                 gint field,
                                                 gdouble value);
    void        gimp_size_entry_set_refval_boundaries
                                                (GimpSizeEntry *gse,
                                                 gint field,
                                                 gdouble lower,
                                                 gdouble upper);
    void        gimp_size_entry_set_refval_digits
                                                (GimpSizeEntry *gse,
                                                 gint field,
                                                 gint digits);
    gdouble     gimp_size_entry_get_refval      (GimpSizeEntry *gse,
                                                 gint field);
    void        gimp_size_entry_set_refval      (GimpSizeEntry *gse,
                                                 gint field,
                                                 gdouble refval);
    GimpUnit    gimp_size_entry_get_unit        (GimpSizeEntry *gse);
    void        gimp_size_entry_set_unit        (GimpSizeEntry *gse,
                                                 GimpUnit unit);
    void        gimp_size_entry_set_pixel_digits
                                                (GimpSizeEntry *gse,
                                                 gint digits);
    void        gimp_size_entry_grab_focus      (GimpSizeEntry *gse);
    GtkWidget*  gimp_size_entry_get_help_widget (GimpSizeEntry *gse,
                                                 gint field);

## Object Hierarchy

      GObject
       +----GtkObject
             +----GtkWidget
                   +----GtkContainer
                         +----GtkTable
                               +----GimpSizeEntry

## Implemented Interfaces

GimpSizeEntry implements AtkImplementorIface.

## Signal Prototypes

    "refval-changed"
                void        user_function      (GimpSizeEntry *gimpsizeentry,
                                                gpointer user_data);
    "unit-changed"
                void        user_function      (GimpSizeEntry *gimpsizeentry,
                                                gpointer user_data);
    "value-changed"
                void        user_function      (GimpSizeEntry *gimpsizeentry,
                                                gpointer user_data);

## 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 it's "value".

There is a GimpUnitMenu 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 GimpUnitMenu 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.

## Details

### GimpSizeEntry

    typedef struct _GimpSizeEntry GimpSizeEntry;

### GimpSizeEntryField

    typedef struct _GimpSizeEntryField GimpSizeEntryField;

### enum GimpSizeEntryUpdatePolicy

    typedef enum
    {
      GIMP_SIZE_ENTRY_UPDATE_NONE       = 0,
      GIMP_SIZE_ENTRY_UPDATE_SIZE       = 1,
      GIMP_SIZE_ENTRY_UPDATE_RESOLUTION = 2
    } GimpSizeEntryUpdatePolicy;

### 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:

1. `gimp_size_entry_new()`

2. (for each additional input field) `gimp_size_entry_add_field()`

3. `gimp_size_entry_set_unit()`

For each input field:

4. `gimp_size_entry_set_resolution()`

5. `gimp_size_entry_set_refval_boundaries()` (or `gimp_size_entry_set_value_boundaries()`)

6. `gimp_size_entry_set_size()`

7. `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 GimpUnitMenu to allow the caller to add labels or a GimpChainButton.

`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 shold 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 shold 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.

`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).

`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.

`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 GimpUnitMenu.

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

`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 these values 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.

`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 GimpUnitMenu.

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.

`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 GimpUnitMenu.

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.

`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.

`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.

`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()`.

`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()`.

`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 GimpUnitMenu.

`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()`.

`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);

Similar to `gimp_unit_menu_set_pixel_digits()`, this function allows you set up a GimpSizeEntry so that sub-pixel sizes can be entered.

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

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

`gse` : | The sizeentry you want to grab the keyboard focus.

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

`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.

## Signals

### The "refval-changed" signal

    void        user_function                  (GimpSizeEntry *gimpsizeentry,
                                                gpointer user_data);

`gimpsizeentry` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The "unit-changed" signal

    void        user_function                  (GimpSizeEntry *gimpsizeentry,
                                                gpointer user_data);

`gimpsizeentry` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The "value-changed" signal

    void        user_function                  (GimpSizeEntry *gimpsizeentry,
                                                gpointer user_data);

`gimpsizeentry` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

## See Also

GimpUnit

GimpUnitMenu

`gimp_coordinates_new()`