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 an adjustment. See the [[email protected]] documentation for more details about
an adjustment's properties.
Note that `GtkSpinButton` will by default make its entry large enough to accommodate the lower and upper bounds of the adjustment. If
this is not desired, the automatic sizing can be turned off by explicitly setting [[email protected]:width-chars] to a value != -1.
Using a GtkSpinButton to get an integer
```c // Provides a function to retrieve an integer value from a GtkSpinButton // and creates a spin button to model percentage values.
int grab_int_value (GtkSpinButton *button, gpointer user_data) { return gtk_spin_button_get_value_as_int (button); }
void create_integer_spin_button (void) {
GtkWidget *window, *button; GtkAdjustment *adjustment;
adjustment = gtk_adjustment_new (50.0, 0.0, 100.0, 1.0, 5.0, 0.0);
window = gtk_window_new ();
// creates the spinbutton, with no decimal places button = gtk_spin_button_new (adjustment, 1.0, 0); gtk_window_set_child (GTK_WINDOW (
window), button);
gtk_widget_show (window); } ```
Using a GtkSpinButton to get a floating point value
```c // Provides a function to retrieve a floating point value from a // GtkSpinButton, and creates a high precision spin button.
float grab_float_value (GtkSpinButton *button, gpointer user_data) { return gtk_spin_button_get_value (button); }
void create_floating_spin_button (void) { GtkWidget *window, *button; GtkAdjustment *adjustment;
adjustment = gtk_adjustment_new (2.500, 0.0, 5.0, 0.001, 0.1, 0.0);
window = gtk_window_new ();
// creates the spinbutton, with three decimal places button = gtk_spin_button_new (adjustment, 0.001, 3); gtk_window_set_child (
GTK_WINDOW (window), button);
gtk_widget_show (window); } ```
CSS nodes
``` spinbutton.horizontal ├── text │ ├── undershoot.left │ ╰── undershoot.right ├── button.down ╰──
button.up ```
``` spinbutton.vertical ├── button.up ├── text │ ├── undershoot.left │ ╰── undershoot.right ╰──
button.down ```
`GtkSpinButton`s main CSS node has the name spinbutton. It creates subnodes for the entry and the two buttons, with these names. The
button nodes have the style classes .up and .down. The `GtkText` subnodes (if present) are put below the text node. The orientation of the
spin button is reflected in the .vertical or .horizontal style class on the main node.
Accessiblity
`GtkSpinButton` uses the gtk_accessible_role_spin_button role.
- public void configure (Adjustment? adjustment, double climb_rate, uint digits)
Changes the properties of an existing spin button.
- public unowned Adjustment get_adjustment ()
Get the adjustment associated with a `GtkSpinButton`.
- public double get_climb_rate ()
Returns the acceleration rate for repeated changes.
- public uint get_digits ()
Fetches the precision of this.
- public void get_increments (out double step, out double page)
Gets the current step and page the increments used by
this.
- public bool get_numeric ()
Returns whether non-numeric text can be typed into the spin button.
- public void get_range (out double min, out double max)
Gets the range allowed for this.
- public bool get_snap_to_ticks ()
Returns whether the values are corrected to the nearest step.
- public SpinButtonUpdatePolicy get_update_policy ()
Gets the update behavior of a spin button.
- public double get_value ()
Get the value in the this.
- public int get_value_as_int ()
Get the value this represented as an
integer.
- public bool 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.
- public void set_adjustment (Adjustment adjustment)
Replaces the `GtkAdjustment` associated with
this.
- public void set_climb_rate (double climb_rate)
Sets the acceleration rate for repeated changes when you hold down a
button or key.
- public void set_digits (uint digits)
Set the precision to be displayed by this
.
- public void set_increments (double step, double page)
Sets the step and page increments for spin_button.
- public void set_numeric (bool numeric)
Sets the flag that determines if non-numeric text can be typed into
the spin button.
- public void set_range (double min, double max)
Sets the minimum and maximum allowable values for
this.
- public void set_snap_to_ticks (bool 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.
- public void set_update_policy (SpinButtonUpdatePolicy policy)
Sets the update behavior of a spin button.
- public void set_value (double value)
Sets the value of this.
- public void set_wrap (bool 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.
- public void spin (SpinType direction, double increment)
Increment or decrement a spin button’s value in a specified
direction by a specified amount.
- public void update ()
Manually force an update of the spin button.