## GtkSpinButton

GtkSpinButton — Retrieve an integer or floating-point number from the user

## Functions

void | gtk_spin_button_configure ()
GtkWidget * | gtk_spin_button_new ()
GtkWidget * | gtk_spin_button_new_with_range ()
void | gtk_spin_button_set_adjustment ()
GtkAdjustment * | gtk_spin_button_get_adjustment ()
void | gtk_spin_button_set_digits ()
void | gtk_spin_button_set_increments ()
void | gtk_spin_button_set_range ()
gint | gtk_spin_button_get_value_as_int ()
void | gtk_spin_button_set_value ()
void | gtk_spin_button_set_update_policy ()
void | gtk_spin_button_set_numeric ()
void | gtk_spin_button_spin ()
void | gtk_spin_button_set_wrap ()
void | gtk_spin_button_set_snap_to_ticks ()
void | gtk_spin_button_update ()
guint | gtk_spin_button_get_digits ()
void | gtk_spin_button_get_increments ()
gboolean | gtk_spin_button_get_numeric ()
void | gtk_spin_button_get_range ()
gboolean | gtk_spin_button_get_snap_to_ticks ()
GtkSpinButtonUpdatePolicy | gtk_spin_button_get_update_policy ()
gdouble | gtk_spin_button_get_value ()
gboolean | gtk_spin_button_get_wrap ()

## Properties

GtkAdjustment * | adjustment | Read / Write
gdouble | climb-rate | Read / Write
guint | digits | Read / Write
gboolean | numeric | Read / Write
gboolean | snap-to-ticks | Read / Write
GtkSpinButtonUpdatePolicy | update-policy | Read / Write
gdouble | value | Read / Write
gboolean | wrap | Read / Write

## Style Properties

GtkShadowType | shadow-type | Read

## Signals

void | change-value | Action
gint | input | Run Last
gboolean | output | Run Last
void | value-changed | Run Last
void | wrapped | Run Last

## Types and Values

struct | GtkSpinButton
enum | GtkSpinButtonUpdatePolicy
enum | GtkSpinType
#define | gtk_spin_button_get_value_as_float
#define | GTK_INPUT_ERROR

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkObject
                ╰── GtkWidget
                    ╰── GtkEntry
                        ╰── GtkSpinButton

## Implemented Interfaces

GtkSpinButton implements AtkImplementorIface, GtkBuildable, GtkEditable and GtkCellEditable.

## Includes

    #include <gtk/gtk.h>

## Description

A GtkSpinButton is an ideal way to allow the user to set the value of some attribute. Rather than having to directly type a number into a GtkEntry, GtkSpinButton allows the user to click on one of two arrows to increment or decrement the displayed value. A value can still be typed in, with the bonus that it can be checked to ensure it is in a given range.

The main properties of a GtkSpinButton are through a GtkAdjustment. See the GtkAdjustment section for more details about an adjustment's properties.

Example 17. Using a GtkSpinButton to get an integer.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18

    /* Provides a function to retrieve an integer value from a GtkSpinButton
     * and creates a spin button to model percentage values.
     */
    gint grab_int_value (GtkSpinButton *a_spinner, gpointer user_data) {
       return gtk_spin_button_get_value_as_int (a_spinner);
    }
    void create_integer_spin_button (void) {
       GtkWidget *window, *spinner;
       GtkAdjustment *spinner_adj;
       spinner_adj = (GtkAdjustment *) gtk_adjustment_new (50.0, 0.0, 100.0, 1.0, 5.0, 5.0);
       window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
       gtk_container_set_border_width (GTK_CONTAINER (window), 5);
       /* creates the spinner, with no decimal places */
       spinner = gtk_spin_button_new (spinner_adj, 1.0, 0);
       gtk_container_add (GTK_CONTAINER (window), spinner);
       gtk_widget_show_all (window);
       return;
    }

Example 18. Using a GtkSpinButton to get a floating point value.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18

    /* Provides a function to retrieve a floating point value from a
     * GtkSpinButton, and creates a high precision spin button.
     */
    gfloat grab_int_value (GtkSpinButton *a_spinner, gpointer user_data) {
       return gtk_spin_button_get_value (a_spinner);
    }
    void create_floating_spin_button (void) {
       GtkWidget *window, *spinner;
       GtkAdjustment *spinner_adj;
       spinner_adj = (GtkAdjustment *) gtk_adjustment_new (2.500, 0.0, 5.0, 0.001, 0.1, 0.1);
       window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
       gtk_container_set_border_width (GTK_CONTAINER (window), 5);
       /* creates the spinner, with three decimal places */
       spinner = gtk_spin_button_new (spinner_adj, 0.001, 3);
       gtk_container_add (GTK_CONTAINER (window), spinner);
       gtk_widget_show_all (window);
       return;
    }

## Functions

### gtk_spin_button_configure ()

    void
    gtk_spin_button_configure (GtkSpinButton *spin_button,
                               GtkAdjustment *adjustment,
                               gdouble climb_rate,
                               guint digits);

Changes the properties of an existing spin button. The adjustment, climb rate, and number of decimal places are all changed accordingly, after this function call.

#### Parameters

spin_button | a GtkSpinButton |
adjustment | a GtkAdjustment. | [allow-none]
climb_rate | the new climb rate. |
digits | the number of decimal places to display in the spin button. |

### gtk_spin_button_new ()

    GtkWidget *
    gtk_spin_button_new (GtkAdjustment *adjustment,
                         gdouble climb_rate,
                         guint digits);

Creates a new GtkSpinButton.

#### Parameters

adjustment | the GtkAdjustment object that this spin button should use. |
climb_rate | specifies how much the spin button changes when an arrow is clicked on. |
digits | the number of decimal places to display. |

#### Returns

The new spin button as a GtkWidget.

### gtk_spin_button_new_with_range ()

    GtkWidget *
    gtk_spin_button_new_with_range (gdouble min,
                                    gdouble max,
                                    gdouble step);

This is a convenience constructor that allows creation of a numeric GtkSpinButton without manually creating an adjustment. The value is initially set to the minimum value and a page increment of 10 * `step` is the default. The precision of the spin button is equivalent to the precision of `step` .

Note that the way in which the precision is derived works best if `step` is a power of ten. If the resulting precision is not suitable for your needs, use `gtk_spin_button_set_digits()` to correct it.

#### Parameters

min | Minimum allowable value |
max | Maximum allowable value |
step | Increment added or subtracted by spinning the widget |

#### Returns

The new spin button as a GtkWidget.

### gtk_spin_button_set_adjustment ()

    void
    gtk_spin_button_set_adjustment (GtkSpinButton *spin_button,
                                    GtkAdjustment *adjustment);

Replaces the GtkAdjustment associated with `spin_button` .

#### Parameters

spin_button | a GtkSpinButton |
adjustment | a GtkAdjustment to replace the existing adjustment |

### gtk_spin_button_get_adjustment ()

    GtkAdjustment *
    gtk_spin_button_get_adjustment (GtkSpinButton *spin_button);

Get the adjustment associated with a GtkSpinButton

#### Parameters

spin_button | a GtkSpinButton |

#### Returns

the GtkAdjustment of `spin_button` .

[transfer none]

### gtk_spin_button_set_digits ()

    void
    gtk_spin_button_set_digits (GtkSpinButton *spin_button,
                                guint digits);

Set the precision to be displayed by `spin_button` . Up to 20 digit precision is allowed.

#### Parameters

spin_button | a GtkSpinButton |
digits | the number of digits after the decimal point to be displayed for the spin button's value |

### gtk_spin_button_set_increments ()

    void
    gtk_spin_button_set_increments (GtkSpinButton *spin_button,
                                    gdouble step,
                                    gdouble page);

Sets the step and page increments for spin_button. This affects how quickly the value changes when the spin button's arrows are activated.

#### Parameters

spin_button | a GtkSpinButton |
step | increment applied for a button 1 press. |
page | increment applied for a button 2 press. |

### gtk_spin_button_set_range ()

    void
    gtk_spin_button_set_range (GtkSpinButton *spin_button,
                               gdouble min,
                               gdouble max);

Sets the minimum and maximum allowable values for `spin_button`

#### Parameters

spin_button | a GtkSpinButton |
min | minimum allowable value |
max | maximum allowable value |

### gtk_spin_button_get_value_as_int ()

    gint
    gtk_spin_button_get_value_as_int (GtkSpinButton *spin_button);

Get the value `spin_button` represented as an integer.

#### Parameters

spin_button | a GtkSpinButton |

#### Returns

the value of `spin_button`

### gtk_spin_button_set_value ()

    void
    gtk_spin_button_set_value (GtkSpinButton *spin_button,
                               gdouble value);

Set the value of `spin_button` .

#### Parameters

spin_button | a GtkSpinButton |
value | the new value |

### gtk_spin_button_set_update_policy ()

    void
    gtk_spin_button_set_update_policy (GtkSpinButton *spin_button,
                                       GtkSpinButtonUpdatePolicy policy);

Sets the update behavior of a spin button. This determines whether the spin button is always updated or only when a valid value is set.

#### Parameters

spin_button | a GtkSpinButton |
policy | a GtkSpinButtonUpdatePolicy value |

### gtk_spin_button_set_numeric ()

    void
    gtk_spin_button_set_numeric (GtkSpinButton *spin_button,
                                 gboolean numeric);

Sets the flag that determines if non-numeric text can be typed into the spin button.

#### Parameters

spin_button | a GtkSpinButton |
numeric | flag indicating if only numeric entry is allowed. |

### gtk_spin_button_spin ()

    void
    gtk_spin_button_spin (GtkSpinButton *spin_button,
                          GtkSpinType direction,
                          gdouble increment);

Increment or decrement a spin button's value in a specified direction by a specified amount.

#### Parameters

spin_button | a GtkSpinButton |
direction | a GtkSpinType indicating the direction to spin. |
increment | step increment to apply in the specified direction. |

### gtk_spin_button_set_wrap ()

    void
    gtk_spin_button_set_wrap (GtkSpinButton *spin_button,
                              gboolean wrap);

Sets the flag that determines if a spin button value wraps around to the opposite limit when the upper or lower limit of the range is exceeded.

#### Parameters

spin_button | a GtkSpinButton |
wrap | a flag indicating if wrapping behavior is performed. |

### gtk_spin_button_set_snap_to_ticks ()

    void
    gtk_spin_button_set_snap_to_ticks (GtkSpinButton *spin_button,
                                       gboolean snap_to_ticks);

Sets the policy as to whether values are corrected to the nearest step increment when a spin button is activated after providing an invalid value.

#### Parameters

spin_button | a GtkSpinButton |
snap_to_ticks | a flag indicating if invalid values should be corrected. |

### gtk_spin_button_update ()

    void
    gtk_spin_button_update (GtkSpinButton *spin_button);

Manually force an update of the spin button.

#### Parameters

spin_button | a GtkSpinButton |

### gtk_spin_button_get_digits ()

    guint
    gtk_spin_button_get_digits (GtkSpinButton *spin_button);

Fetches the precision of `spin_button` . See `gtk_spin_button_set_digits()`.

#### Parameters

spin_button | a GtkSpinButton |

#### Returns

the current precision

### gtk_spin_button_get_increments ()

    void
    gtk_spin_button_get_increments (GtkSpinButton *spin_button,
                                    gdouble *step,
                                    gdouble *page);

Gets the current step and page the increments used by `spin_button` . See `gtk_spin_button_set_increments()`.

#### Parameters

spin_button | a GtkSpinButton |
step | location to store step increment, or `NULL`. | [out][allow-none]
page | location to store page increment, or `NULL`. | [out][allow-none]

### gtk_spin_button_get_numeric ()

    gboolean
    gtk_spin_button_get_numeric (GtkSpinButton *spin_button);

Returns whether non-numeric text can be typed into the spin button. See `gtk_spin_button_set_numeric()`.

#### Parameters

spin_button | a GtkSpinButton |

#### Returns

`TRUE` if only numeric text can be entered

### gtk_spin_button_get_range ()

    void
    gtk_spin_button_get_range (GtkSpinButton *spin_button,
                               gdouble *min,
                               gdouble *max);

Gets the range allowed for `spin_button` . See `gtk_spin_button_set_range()`.

#### Parameters

spin_button | a GtkSpinButton |
min | location to store minimum allowed value, or `NULL`. | [out][allow-none]
max | location to store maximum allowed value, or `NULL`. | [out][allow-none]

### gtk_spin_button_get_snap_to_ticks ()

    gboolean
    gtk_spin_button_get_snap_to_ticks (GtkSpinButton *spin_button);

Returns whether the values are corrected to the nearest step. See `gtk_spin_button_set_snap_to_ticks()`.

#### Parameters

spin_button | a GtkSpinButton |

#### Returns

`TRUE` if values are snapped to the nearest step.

### gtk_spin_button_get_update_policy ()

    GtkSpinButtonUpdatePolicy
    gtk_spin_button_get_update_policy (GtkSpinButton *spin_button);

Gets the update behavior of a spin button. See `gtk_spin_button_set_update_policy()`.

#### Parameters

spin_button | a GtkSpinButton |

#### Returns

the current update policy

### gtk_spin_button_get_value ()

    gdouble
    gtk_spin_button_get_value (GtkSpinButton *spin_button);

Get the value in the `spin_button` .

#### Parameters

spin_button | a GtkSpinButton |

#### Returns

the value of `spin_button`

### gtk_spin_button_get_wrap ()

    gboolean
    gtk_spin_button_get_wrap (GtkSpinButton *spin_button);

Returns whether the spin button's value wraps around to the opposite limit when the upper or lower limit of the range is exceeded. See `gtk_spin_button_set_wrap()`.

#### Parameters

spin_button | a GtkSpinButton |

#### Returns

`TRUE` if the spin button wraps around

## Types and Values

### struct GtkSpinButton

    struct GtkSpinButton;

`entry` is the GtkEntry part of the GtkSpinButton widget, and can be used accordingly. All other fields contain private data and should only be modified using the functions below.

### enum GtkSpinButtonUpdatePolicy

GTK_UPDATE_ALWAYS | When refreshing your GtkSpinButton, the value is always displayed.
GTK_UPDATE_IF_VALID | When refreshing your GtkSpinButton, the value is only displayed if it is valid within the bounds of the spin button's GtkAdjustment.

#### Members

GTK_UPDATE_ALWAYS |  |
GTK_UPDATE_IF_VALID |  |

### enum GtkSpinType

GTK_SPIN_STEP_FORWARD, GTK_SPIN_STEP_BACKWARD, GTK_SPIN_PAGE_FORWARD, GTK_SPIN_PAGE_BACKWARD | These values spin a GtkSpinButton by the relevant values of the spin button's GtkAdjustment.
GTK_SPIN_HOME, GTK_SPIN_END | These set the spin button's value to the minimum or maxmimum possible values, (set by its GtkAdjustment), respectively.
GTK_SPIN_USER_DEFINED | The programmer must specify the exact amount to spin the GtkSpinButton.

#### Members

GTK_SPIN_STEP_FORWARD |  |
GTK_SPIN_STEP_BACKWARD |  |
GTK_SPIN_PAGE_FORWARD |  |
GTK_SPIN_PAGE_BACKWARD |  |
GTK_SPIN_HOME |  |
GTK_SPIN_END |  |
GTK_SPIN_USER_DEFINED |  |

### gtk_spin_button_get_value_as_float

    #define gtk_spin_button_get_value_as_float gtk_spin_button_get_value

`gtk_spin_button_get_value_as_float` is deprecated and should not be used in newly-written code.

Use `gtk_spin_button_get_value()` instead.

Gets the value in the `spin_button`.

#### Returns

the value of `spin_button`

### GTK_INPUT_ERROR

    #define GTK_INPUT_ERROR -1

## Property Details

### The `“adjustment”` property

      “adjustment”               GtkAdjustment *

The adjustment that holds the value of the spinbutton.

Flags: Read / Write

### The `“climb-rate”` property

      “climb-rate”               gdouble

The acceleration rate when you hold down a button.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

### The `“digits”` property

      “digits”                   guint

The number of decimal places to display.

Flags: Read / Write

Allowed values: <= 20

Default value: 0

### The `“numeric”` property

      “numeric”                  gboolean

Whether non-numeric characters should be ignored.

Flags: Read / Write

Default value: FALSE

### The `“snap-to-ticks”` property

      “snap-to-ticks”            gboolean

Whether erroneous values are automatically changed to a spin button's nearest step increment.

Flags: Read / Write

Default value: FALSE

### The `“update-policy”` property

      “update-policy”            GtkSpinButtonUpdatePolicy

Whether the spin button should update always, or only when the value is legal.

Flags: Read / Write

Default value: GTK_UPDATE_ALWAYS

### The `“value”` property

      “value”                    gdouble

Reads the current value, or sets a new value.

Flags: Read / Write

Default value: 0

### The `“wrap”` property

      “wrap”                     gboolean

Whether a spin button should wrap upon reaching its limits.

Flags: Read / Write

Default value: FALSE

## Style Property Details

### The `“shadow-type”` style property

      “shadow-type”              GtkShadowType

the type of border that surrounds the arrows of a spin button.

Flags: Read

Default value: GTK_SHADOW_IN

## Signal Details

### The `“change-value”` signal

    void
    user_function (GtkSpinButton *spinbutton,
                   GtkScrollType  arg1,
                   gpointer       user_data)

#### Parameters

spinbutton | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Action

### The `“input”` signal

    gint
    user_function (GtkSpinButton *spinbutton,
                   gpointer       arg1,
                   gpointer       user_data)

#### Parameters

spinbutton | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

#### Returns

Flags: Run Last

### The `“output”` signal

    gboolean
    user_function (GtkSpinButton *spin_button,
                   gpointer       user_data)

The ::output signal can be used to change to formatting of the value that is displayed in the spin buttons entry.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17

    /* show leading zeros */
    static gboolean
    on_output (GtkSpinButton *spin,
               gpointer       data)
    {
       GtkAdjustment *adj;
       gchar *text;
       int value;

       adj = gtk_spin_button_get_adjustment (spin);
       value = (int)gtk_adjustment_get_value (adj);
       text = g_strdup_printf ("%02d", value);
       gtk_entry_set_text (GTK_ENTRY (spin), text);
       g_free (text);

       return TRUE;
    }

#### Parameters

spin_button | the object which received the signal |
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the value has been displayed.

Flags: Run Last

### The `“value-changed”` signal

    void
    user_function (GtkSpinButton *spinbutton,
                   gpointer       user_data)

#### Parameters

spinbutton | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“wrapped”` signal

    void
    user_function (GtkSpinButton *spinbutton,
                   gpointer       user_data)

The wrapped signal is emitted right after the spinbutton wraps from its maximum to minimum value or vice-versa.

#### Parameters

spinbutton | the object which received the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since 2.10

## See Also

GtkEntry | retrieve text rather than numbers.