## GimpNumberPairEntry

GimpNumberPairEntry — A GtkEntry subclass to enter ratios.

## Synopsis

                        GimpNumberPairEntry;
    enum                GimpAspectType;
    GtkWidget *         gimp_number_pair_entry_new          (const gchar *separators,
                                                             gboolean allow_simplification,
                                                             gdouble min_valid_value,
                                                             gdouble max_valid_value);
    void                gimp_number_pair_entry_set_default_values
                                                            (GimpNumberPairEntry *entry,
                                                             gdouble left,
                                                             gdouble right);
    void                gimp_number_pair_entry_get_default_values
                                                            (GimpNumberPairEntry *entry,
                                                             gdouble *left,
                                                             gdouble *right);
    void                gimp_number_pair_entry_set_values   (GimpNumberPairEntry *entry,
                                                             gdouble left,
                                                             gdouble right);
    void                gimp_number_pair_entry_get_values   (GimpNumberPairEntry *entry,
                                                             gdouble *left,
                                                             gdouble *right);
    GimpAspectType      gimp_number_pair_entry_get_aspect   (GimpNumberPairEntry *entry);
    void                gimp_number_pair_entry_set_aspect   (GimpNumberPairEntry *entry,
                                                             GimpAspectType aspect);
    gdouble             gimp_number_pair_entry_get_ratio    (GimpNumberPairEntry *entry);
    void                gimp_number_pair_entry_set_ratio    (GimpNumberPairEntry *entry,
                                                             gdouble ratio);
    gboolean            gimp_number_pair_entry_get_user_override
                                                            (GimpNumberPairEntry *entry);
    void                gimp_number_pair_entry_set_user_override
                                                            (GimpNumberPairEntry *entry,
                                                             gboolean user_override);
    const gchar *       gimp_number_pair_entry_get_default_text
                                                            (GimpNumberPairEntry *entry);
    void                gimp_number_pair_entry_set_default_text
                                                            (GimpNumberPairEntry *entry,
                                                             const gchar *string);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkEntry
                               +----GimpNumberPairEntry

## Implemented Interfaces

GimpNumberPairEntry implements AtkImplementorIface, GtkBuildable, GtkEditable and GtkCellEditable.

## Properties

      "allow-simplification"     gboolean              : Read / Write
      "aspect"                   GimpAspectType        : Read / Write
      "default-left-number"      gdouble               : Read / Write
      "default-right-number"     gdouble               : Read / Write
      "default-text"             gchar*                : Read / Write
      "left-number"              gdouble               : Read / Write
      "max-valid-value"          gdouble               : Read / Write
      "min-valid-value"          gdouble               : Read / Write
      "ratio"                    gdouble               : Read / Write
      "right-number"             gdouble               : Read / Write
      "separators"               gchar*                : Read / Write / Construct Only
      "user-override"            gboolean              : Read / Write

## Signals

      "numbers-changed"                                : Run First
      "ratio-changed"                                  : Run First

## Description

A GtkEntry subclass to enter ratios.

## Details

### GimpNumberPairEntry

    typedef struct _GimpNumberPairEntry GimpNumberPairEntry;

### enum GimpAspectType

    typedef enum {
      GIMP_ASPECT_SQUARE,    /*< desc="Square"    >*/
      GIMP_ASPECT_PORTRAIT,  /*< desc="Portrait"  >*/
      GIMP_ASPECT_LANDSCAPE  /*< desc="Landscape" >*/
    } GimpAspectType;

Aspect ratios.

`GIMP_ASPECT_SQUARE` | it's a 1:1 square
`GIMP_ASPECT_PORTRAIT` | it's higher than it's wide
`GIMP_ASPECT_LANDSCAPE` | it's wider than it's high

### gimp_number_pair_entry_new ()

    GtkWidget *         gimp_number_pair_entry_new          (const gchar *separators,
                                                             gboolean allow_simplification,
                                                             gdouble min_valid_value,
                                                             gdouble max_valid_value);

Creates a new GimpNumberPairEntry widget, which is a GtkEntry that accepts two numbers separated by a separator. Typical input example with a 'x' separator: "377x233".

The widget supports simplification of the entered ratio when the input ends in '=', if "allow-simplification" is TRUE.

The "separators" property contains a string of characters valid as separators when parsing input. The first separator is used when displaying the current values.

It is possible to specify what range of values that shall be considered as valid when parsing user input, by changing "min-valid-value" and "max-valid-value".

The first separator of `separators` is used to display the current value.

`separators` : | The allowed separators.
`allow_simplification` : | Whether to do simplification on the entered term.
`min_valid_value` : | The minimum allowed result value.
`max_valid_value` : | The maximum allowed result value.
Returns : | The new GimpNumberPairEntry widget.

Since GIMP 2.4

### gimp_number_pair_entry_set_default_values ()

    void                gimp_number_pair_entry_set_default_values
                                                            (GimpNumberPairEntry *entry,
                                                             gdouble left,
                                                             gdouble right);

`entry` : | A GimpNumberPairEntry widget.
`left` : | Default left value in the entry.
`right` : | Default right value in the entry.

Since GIMP 2.4

### gimp_number_pair_entry_get_default_values ()

    void                gimp_number_pair_entry_get_default_values
                                                            (GimpNumberPairEntry *entry,
                                                             gdouble *left,
                                                             gdouble *right);

`entry` : | A GimpNumberPairEntry widget.
`left` : | Pointer of where to put left value.
`right` : | Pointer of where to put right value.

Since GIMP 2.4

### gimp_number_pair_entry_set_values ()

    void                gimp_number_pair_entry_set_values   (GimpNumberPairEntry *entry,
                                                             gdouble left,
                                                             gdouble right);

Forces setting the numbers displayed by a GimpNumberPairEntry, ignoring if the user has set his/her own value. The state of user-override will not be changed.

`entry` : | A GimpNumberPairEntry widget.
`left` : | Left number in the entry.
`right` : | Right number in the entry.

Since GIMP 2.4

### gimp_number_pair_entry_get_values ()

    void                gimp_number_pair_entry_get_values   (GimpNumberPairEntry *entry,
                                                             gdouble *left,
                                                             gdouble *right);

Gets the numbers displayed by a GimpNumberPairEntry.

`entry` : | A GimpNumberPairEntry widget.
`left` : | Pointer of where to store the left number (may be `NULL`).
`right` : | Pointer of to store the right number (may be `NULL`).

Since GIMP 2.4

### gimp_number_pair_entry_get_aspect ()

    GimpAspectType      gimp_number_pair_entry_get_aspect   (GimpNumberPairEntry *entry);

Gets the aspect of the ratio displayed by a GimpNumberPairEntry.

`entry` : | A GimpNumberPairEntry widget.
Returns : | The entry's current aspect.

Since GIMP 2.4

### gimp_number_pair_entry_set_aspect ()

    void                gimp_number_pair_entry_set_aspect   (GimpNumberPairEntry *entry,
                                                             GimpAspectType aspect);

Sets the aspect of the ratio by swapping the left_number and right_number if necessary (or setting them to 1.0 in case that `aspect` is `GIMP_ASPECT_SQUARE`).

`entry` : | A GimpNumberPairEntry widget.
`aspect` : | The new aspect.

Since GIMP 2.4

### gimp_number_pair_entry_get_ratio ()

    gdouble             gimp_number_pair_entry_get_ratio    (GimpNumberPairEntry *entry);

Retrieves the ratio of the numbers displayed by a GimpNumberPairEntry.

`entry` : | A GimpNumberPairEntry widget.
Returns : | The ratio value.

Since GIMP 2.4

### gimp_number_pair_entry_set_ratio ()

    void                gimp_number_pair_entry_set_ratio    (GimpNumberPairEntry *entry,
                                                             gdouble ratio);

Sets the numbers of the GimpNumberPairEntry to have the desired ratio. If the new ratio is different than the previous ratio, the "ratio-changed" signal is emitted.

An attempt is made to convert the decimal number into a fraction with left_number and right_number < 1000.

`entry` : | A GimpNumberPairEntry widget.
`ratio` : | Ratio to set in the widget.

Since GIMP 2.4

### gimp_number_pair_entry_get_user_override ()

    gboolean            gimp_number_pair_entry_get_user_override
                                                            (GimpNumberPairEntry *entry);

`entry` : | A GimpNumberPairEntry widget.
Returns : | Wether or not the the widget is in user overridden mode.

Since GIMP 2.4

### gimp_number_pair_entry_set_user_override ()

    void                gimp_number_pair_entry_set_user_override
                                                            (GimpNumberPairEntry *entry,
                                                             gboolean user_override);

When the entry is not in user overridden mode, the values will change when the default values are changed. When in user overridden mode, setting default values will not affect the active values.

`entry` : | A GimpNumberPairEntry widget.
`user_override` : | `TRUE` sets the entry in user overridden mode, `FALSE` disables.

Since GIMP 2.4

### gimp_number_pair_entry_get_default_text ()

    const gchar *       gimp_number_pair_entry_get_default_text
                                                            (GimpNumberPairEntry *entry);

`entry` : | A GimpNumberPairEntry widget.
Returns : | the string manully set to be shown, or `NULL` if values are shown in a normal fashion.

Since GIMP 2.4

### gimp_number_pair_entry_set_default_text ()

    void                gimp_number_pair_entry_set_default_text
                                                            (GimpNumberPairEntry *entry,
                                                             const gchar *string);

Causes the entry to show a given string when in automatic mode, instead of the default numbers. The only thing this does is making the GimpNumberPairEntry showing this string, the internal state and API calls are not affected.

Set the default string to `NULL` to display default values as normal.

`entry` : | A GimpNumberPairEntry widget.
`string` : | Default string.

Since GIMP 2.4

## Property Details

### The `"allow-simplification"` property

      "allow-simplification"     gboolean              : Read / Write

Whether to allow simplification.

Default value: FALSE

### The `"aspect"` property

      "aspect"                   GimpAspectType        : Read / Write

Default value: GIMP_ASPECT_SQUARE

### The `"default-left-number"` property

      "default-left-number"      gdouble               : Read / Write

Allowed values: >= G_MINDOUBLE

Default value: 100

### The `"default-right-number"` property

      "default-right-number"     gdouble               : Read / Write

Allowed values: >= G_MINDOUBLE

Default value: 100

### The `"default-text"` property

      "default-text"             gchar*                : Read / Write

String to show when in automatic mode.

Default value: NULL

### The `"left-number"` property

      "left-number"              gdouble               : Read / Write

Allowed values: >= G_MINDOUBLE

Default value: 100

### The `"max-valid-value"` property

      "max-valid-value"          gdouble               : Read / Write

Maximum value valid when parsing input.

Allowed values: >= G_MINDOUBLE

Default value: 1.79769e+308

### The `"min-valid-value"` property

      "min-valid-value"          gdouble               : Read / Write

Minimum value valid when parsing input.

Allowed values: >= G_MINDOUBLE

Default value: 2.22507e-308

### The `"ratio"` property

      "ratio"                    gdouble               : Read / Write

Allowed values: >= G_MINDOUBLE

Default value: 1

### The `"right-number"` property

      "right-number"             gdouble               : Read / Write

Allowed values: >= G_MINDOUBLE

Default value: 100

### The `"separators"` property

      "separators"               gchar*                : Read / Write / Construct Only

A string of valid separators.

Default value: NULL

### The `"user-override"` property

      "user-override"            gboolean              : Read / Write

Whether the widget is in 'user override' mode.

Default value: FALSE

## Signal Details

### The `"numbers-changed"` signal

    void                user_function                      (GimpNumberPairEntry *gimpnumberpairentry,
                                                            gpointer             user_data)                : Run First

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

### The `"ratio-changed"` signal

    void                user_function                      (GimpNumberPairEntry *gimpnumberpairentry,
                                                            gpointer             user_data)                : Run First

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