## GtkSpinButton

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

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkSpinButton;
    enum        GtkSpinButtonUpdatePolicy;
    enum        GtkSpinType;
    void        gtk_spin_button_configure       (GtkSpinButton *spin_button,
                                                 GtkAdjustment *adjustment,
                                                 gdouble climb_rate,
                                                 guint digits);
    GtkWidget*  gtk_spin_button_new             (GtkAdjustment *adjustment,
                                                 gdouble climb_rate,
                                                 guint digits);
    GtkWidget*  gtk_spin_button_new_with_range  (gdouble min,
                                                 gdouble max,
                                                 gdouble step);
    void        gtk_spin_button_set_adjustment  (GtkSpinButton *spin_button,
                                                 GtkAdjustment *adjustment);
    GtkAdjustment* gtk_spin_button_get_adjustment
                                                (GtkSpinButton *spin_button);
    void        gtk_spin_button_set_digits      (GtkSpinButton *spin_button,
                                                 guint digits);
    void        gtk_spin_button_set_increments  (GtkSpinButton *spin_button,
                                                 gdouble step,
                                                 gdouble page);
    void        gtk_spin_button_set_range       (GtkSpinButton *spin_button,
                                                 gdouble min,
                                                 gdouble max);
    #define     gtk_spin_button_get_value_as_float
    gint        gtk_spin_button_get_value_as_int
                                                (GtkSpinButton *spin_button);
    void        gtk_spin_button_set_value       (GtkSpinButton *spin_button,
                                                 gdouble value);
    void        gtk_spin_button_set_update_policy
                                                (GtkSpinButton *spin_button,
                                                 GtkSpinButtonUpdatePolicy policy);
    void        gtk_spin_button_set_numeric     (GtkSpinButton *spin_button,
                                                 gboolean numeric);
    void        gtk_spin_button_spin            (GtkSpinButton *spin_button,
                                                 GtkSpinType direction,
                                                 gdouble increment);
    void        gtk_spin_button_set_wrap        (GtkSpinButton *spin_button,
                                                 gboolean wrap);
    void        gtk_spin_button_set_snap_to_ticks
                                                (GtkSpinButton *spin_button,
                                                 gboolean snap_to_ticks);
    void        gtk_spin_button_update          (GtkSpinButton *spin_button);
    guint       gtk_spin_button_get_digits      (GtkSpinButton *spin_button);
    void        gtk_spin_button_get_increments  (GtkSpinButton *spin_button,
                                                 gdouble *step,
                                                 gdouble *page);
    gboolean    gtk_spin_button_get_numeric     (GtkSpinButton *spin_button);
    void        gtk_spin_button_get_range       (GtkSpinButton *spin_button,
                                                 gdouble *min,
                                                 gdouble *max);
    gboolean    gtk_spin_button_get_snap_to_ticks
                                                (GtkSpinButton *spin_button);
    GtkSpinButtonUpdatePolicy gtk_spin_button_get_update_policy
                                                (GtkSpinButton *spin_button);
    gdouble     gtk_spin_button_get_value       (GtkSpinButton *spin_button);
    gboolean    gtk_spin_button_get_wrap        (GtkSpinButton *spin_button);
    #define     GTK_INPUT_ERROR

## Object Hierarchy

      GObject
       +----GtkObject
             +----GtkWidget
                   +----GtkEntry
                         +----GtkSpinButton

## Implemented Interfaces

GtkSpinButton implements AtkImplementorIface, GtkEditable and GtkCellEditable.

## Properties

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

## Style Properties

      "shadow-type"          GtkShadowType        : Read

## Signal Prototypes

    "change-value"
                void        user_function      (GtkSpinButton *spinbutton,
                                                GtkScrollType arg1,
                                                gpointer user_data);
    "input"     gint        user_function      (GtkSpinButton *spinbutton,
                                                gpointer arg1,
                                                gpointer user_data);
    "output"    gboolean    user_function      (GtkSpinButton *spinbutton,
                                                gpointer user_data);
    "value-changed"
                void        user_function      (GtkSpinButton *spinbutton,
                                                gpointer user_data);

## 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 1. Using a GtkSpinButton to get an integer.

    /* 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 2. Using a GtkSpinButton to get a floating point value.

    /* 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;
    }

## Details

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

    typedef enum
    {
      GTK_UPDATE_ALWAYS,
      GTK_UPDATE_IF_VALID
    } 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.

### enum GtkSpinType

    typedef enum
    {
      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
    } 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.

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

`spin_button` : | a GtkSpinButton.
`adjustment` : | a GtkAdjustment.
`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.

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

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

`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

`spin_button` : |
Returns : | the GtkAdjustment of `spin_button`

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

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

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

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

### gtk_spin_button_get_value_as_float

    #define gtk_spin_button_get_value_as_float gtk_spin_button_get_value

### Warning

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

Gets the value in the `spin_button`. This function is deprecated, use `gtk_spin_button_get_value()` instead.

Returns : | the value of `spin_button`.

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

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

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

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

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

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

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

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

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

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

`spin_button` : | a GtkSpinButton
`step` : | location to store step increment, or `NULL`
`page` : | location to store page increment, or `NULL`

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

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

`spin_button` : | a GtkSpinButton
`min` : | location to store minimum allowed value, or `NULL`
`max` : | location to store maximum allowed value, or `NULL`

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

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

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

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

`spin_button` : | a GtkSpinButton
Returns : | `TRUE` if the spin button wraps around

### GTK_INPUT_ERROR

    #define GTK_INPUT_ERROR -1

## Properties

"`adjustment`" (GtkAdjustment : Read / Write) | The adjustment that holds the value of the spinbutton.
"`climb-rate`" (gdouble : Read / Write) | The acceleration rate when you hold down a button.
"`digits`" (guint : Read / Write) | The number of decimal places to display.
"`numeric`" (gboolean : Read / Write) | Whether non-numeric characters should be ignored.
"`snap-to-ticks`" (gboolean : Read / Write) | Whether erroneous values are automatically changed to a spin button's nearest step increment.
"`update-policy`" (GtkSpinButtonUpdatePolicy : Read / Write) | Whether the spin button should update always, or only when the value is legal.
"`value`" (gdouble : Read / Write) | Reads the current value, or sets a new value.
"`wrap`" (gboolean : Read / Write) | Whether a spin button should wrap upon reaching its limits.

## Style Properties

"`shadow-type`" (GtkShadowType : Read) | the type of border that surrounds the arrows of a spin button.

## Signals

### The "change-value" signal

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

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

### The "input" signal

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

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

### The "output" signal

    gboolean    user_function                  (GtkSpinButton *spinbutton,
                                                gpointer user_data);

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

### The "value-changed" signal

    void        user_function                  (GtkSpinButton *spinbutton,
                                                gpointer user_data);

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

## See Also

GtkEntry | retrieve text rather than numbers.