Next: , Previous: GtkVScale, Up: Top

24 GtkSpinButton

Retrieve an integer or floating-point number from the user

24.1 Overview

A <gtk-spin-button> 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 <gtk-entry>, <gtk-spin-button> 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 <gtk-spin-button> are through a <gtk-adjustment>. See the <gtk-adjustment> section for more details about an adjustment's properties. 

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

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

24.2 Usage

— Class: <gtk-spin-button>

Derives from <gtk-entry>.

This class defines the following slots:

adjustment
The adjustment that holds the value of the spinbutton
climb-rate
The acceleration rate when you hold down a button
digits
The number of decimal places to display
snap-to-ticks
Whether erroneous values are automatically changed to a spin button's nearest step increment
numeric
Whether non-numeric characters should be ignored
wrap
Whether a spin button should wrap upon reaching its limits
update-policy
Whether the spin button should update always, or only when the value is legal
value
Reads the current value, or sets a new value
— Signal on <gtk-spin-button>: value-changed
— Signal on <gtk-spin-button>: change-value (arg0 <gtk-scroll-type>)
— Signal on <gtk-spin-button>: input (arg0 <gpointer>) ⇒ <gint>
— Signal on <gtk-spin-button>: output ⇒ <gboolean>
— Signal on <gtk-spin-button>: wrapped

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

Since 2.10

— Function: gtk-spin-button-configure (self <gtk-spin-button>) (adjustment <gtk-adjustment>) (climb_rate double) (digits unsigned-int)
— Method: configure

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 <gtk-spin-button>.
adjustment
a <gtk-adjustment>.
climb-rate
the new climb rate.
digits
the number of decimal places to display in the spin button.
— Function: gtk-spin-button-new (adjustment <gtk-adjustment>) (climb_rate double) (digits unsigned-int) ⇒  (ret <gtk-widget>)

Creates a new <gtk-spin-button>.

adjustment
the <gtk-adjustment> 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.
ret
The new spin button as a <gtk-widget>.
— Function: gtk-spin-button-new-with-range (min double) (max double) (step double) ⇒  (ret <gtk-widget>)

This is a convenience constructor that allows creation of a numeric <gtk-spin-button> 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.

min
Minimum allowable value
max
Maximum allowable value
step
Increment added or subtracted by spinning the widget
ret
The new spin button as a <gtk-widget>.
— Function: gtk-spin-button-set-adjustment (self <gtk-spin-button>) (adjustment <gtk-adjustment>)
— Method: set-adjustment

Replaces the <gtk-adjustment> associated with spin-button.

spin-button
a <gtk-spin-button>
adjustment
a <gtk-adjustment> to replace the existing adjustment
— Function: gtk-spin-button-get-adjustment (self <gtk-spin-button>) ⇒  (ret <gtk-adjustment>)
— Method: get-adjustment

Get the adjustment associated with a <gtk-spin-button>

spin-button
a <gtk-spin-button>
ret
the <gtk-adjustment> of spin-button
— Function: gtk-spin-button-set-digits (self <gtk-spin-button>) (digits unsigned-int)
— Method: set-digits

Set the precision to be displayed by spin-button. Up to 20 digit precision is allowed.

spin-button
a <gtk-spin-button>
digits
the number of digits after the decimal point to be displayed for the spin button's value
— Function: gtk-spin-button-set-increments (self <gtk-spin-button>) (step double) (page double)
— Method: set-increments

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 <gtk-spin-button>
step
increment applied for a button 1 press.
page
increment applied for a button 2 press.
— Function: gtk-spin-button-set-range (self <gtk-spin-button>) (min double) (max double)
— Method: set-range

Sets the minimum and maximum allowable values for spin-button

spin-button
a <gtk-spin-button>
min
minimum allowable value
max
maximum allowable value
— Function: gtk-spin-button-get-value-as-int (self <gtk-spin-button>) ⇒  (ret int)
— Method: get-value-as-int

Get the value spin-button represented as an integer.

spin-button
a <gtk-spin-button>
ret
the value of spin-button
— Function: gtk-spin-button-set-value (self <gtk-spin-button>) (value double)
— Method: set-value

Set the value of spin-button.

spin-button
a <gtk-spin-button>
value
the new value
— Function: gtk-spin-button-set-update-policy (self <gtk-spin-button>) (policy <gtk-spin-button-update-policy>)
— Method: set-update-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 <gtk-spin-button>
policy
a <gtk-spin-button-update-policy> value
— Function: gtk-spin-button-set-numeric (self <gtk-spin-button>) (numeric bool)
— Method: set-numeric

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

spin-button
a <gtk-spin-button>
numeric
flag indicating if only numeric entry is allowed.
— Function: gtk-spin-button-spin (self <gtk-spin-button>) (direction <gtk-spin-type>) (increment double)
— Method: spin

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

spin-button
a <gtk-spin-button>
direction
a <gtk-spin-type> indicating the direction to spin.
increment
step increment to apply in the specified direction.
— Function: gtk-spin-button-set-wrap (self <gtk-spin-button>) (wrap bool)
— Method: set-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 <gtk-spin-button>
wrap
a flag indicating if wrapping behavior is performed.
— Function: gtk-spin-button-set-snap-to-ticks (self <gtk-spin-button>) (snap_to_ticks bool)
— Method: set-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 <gtk-spin-button>
snap-to-ticks
a flag indicating if invalid values should be corrected.
— Function: gtk-spin-button-update (self <gtk-spin-button>)
— Method: update

Manually force an update of the spin button.

spin-button
a <gtk-spin-button>
— Function: gtk-spin-button-get-digits (self <gtk-spin-button>) ⇒  (ret unsigned-int)
— Method: get-digits

Fetches the precision of spin-button. See gtk-spin-button-set-digits.

spin-button
a <gtk-spin-button>
ret
the current precision
— Function: gtk-spin-button-get-increments (self <gtk-spin-button>) ⇒  (step double) (page double)
— Method: get-increments

Gets the current step and page the increments used by spin-button. See gtk-spin-button-set-increments.

spin-button
a <gtk-spin-button>
step
location to store step increment, or ‘#f’
page
location to store page increment, or ‘#f’
— Function: gtk-spin-button-get-numeric (self <gtk-spin-button>) ⇒  (ret bool)
— Method: get-numeric

Returns whether non-numeric text can be typed into the spin button. See gtk-spin-button-set-numeric.

spin-button
a <gtk-spin-button>
ret
‘#t’ if only numeric text can be entered
— Function: gtk-spin-button-get-range (self <gtk-spin-button>) ⇒  (min double) (max double)
— Method: get-range

Gets the range allowed for spin-button. See gtk-spin-button-set-range.

spin-button
a <gtk-spin-button>
min
location to store minimum allowed value, or ‘#f’
max
location to store maximum allowed value, or ‘#f’
— Function: gtk-spin-button-get-snap-to-ticks (self <gtk-spin-button>) ⇒  (ret bool)
— Method: get-snap-to-ticks

Returns whether the values are corrected to the nearest step. See gtk-spin-button-set-snap-to-ticks.

spin-button
a <gtk-spin-button>
ret
‘#t’ if values are snapped to the nearest step.
— Function: gtk-spin-button-get-value (self <gtk-spin-button>) ⇒  (ret double)
— Method: get-value

Get the value in the spin-button.

spin-button
a <gtk-spin-button>
ret
the value of spin-button
— Function: gtk-spin-button-get-wrap (self <gtk-spin-button>) ⇒  (ret bool)
— Method: get-wrap

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 <gtk-spin-button>
ret
‘#t’ if the spin button wraps around