Class
GtkSpinButton
Description [src]
class Gtk.SpinButton : Gtk.Entry
implements Atk.ImplementorIface, Gtk.Buildable, Gtk.CellEditable, Gtk.Editable, Gtk.Orientable {
/* No available fields */
}
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 GtkAdjustment
section for more details about an adjustment’s
properties. Note that GtkSpinButton will by default make its entry
large enough to accomodate the lower and upper bounds of the adjustment,
which can lead to surprising results. Best practice is to set both
the GtkEntry:width-chars
and GtkEntry:max-width-chars
poperties
to the desired number of characters to display in the entry.
CSS nodes
spinbutton.horizontal
├── undershoot.left
├── undershoot.right
├── entry
│ ╰── ...
├── button.down
╰── button.up
spinbutton.vertical
├── undershoot.left
├── undershoot.right
├── button.up
├── entry
│ ╰── ...
╰── button.down
GtkSpinButtons 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 GtkEntry subnodes (if present) are put below the entry node. The orientation of the spin button is reflected in the .vertical or .horizontal style class on the main node.
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 *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 (GTK_WINDOW_TOPLEVEL);
gtk_container_set_border_width (GTK_CONTAINER (window), 5);
// creates the spinbutton, with no decimal places
button = gtk_spin_button_new (adjustment, 1.0, 0);
gtk_container_add (GTK_CONTAINER (window), button);
gtk_widget_show_all (window);
}
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_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 (GTK_WINDOW_TOPLEVEL);
gtk_container_set_border_width (GTK_CONTAINER (window), 5);
// creates the spinbutton, with three decimal places
button = gtk_spin_button_new (adjustment, 0.001, 3);
gtk_container_add (GTK_CONTAINER (window), button);
gtk_widget_show_all (window);
}
Constructors
gtk_spin_button_new_with_range
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
.
Instance methods
gtk_spin_button_configure
Changes the properties of an existing spin button. The adjustment, climb rate, and number of decimal places are updated accordingly.
gtk_spin_button_get_increments
Gets the current step and page the increments used by spin_button
. See gtk_spin_button_set_increments().
gtk_spin_button_get_numeric
Returns whether non-numeric text can be typed into the spin button. See gtk_spin_button_set_numeric().
gtk_spin_button_get_snap_to_ticks
Returns whether the values are corrected to the nearest step. See gtk_spin_button_set_snap_to_ticks().
gtk_spin_button_get_update_policy
Gets the update behavior of a spin button. See gtk_spin_button_set_update_policy().
gtk_spin_button_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().
gtk_spin_button_set_digits
Set the precision to be displayed by spin_button
. Up to 20 digit precision
is allowed.
gtk_spin_button_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.
gtk_spin_button_set_numeric
Sets the flag that determines if non-numeric text can be typed into the spin button.
gtk_spin_button_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.
gtk_spin_button_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.
gtk_spin_button_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.
gtk_spin_button_spin
Increment or decrement a spin button’s value in a specified direction by a specified amount.
Methods inherited from GtkBuildable (10)
Methods inherited from GtkCellEditable (3)
Methods inherited from GtkEditable (13)
Methods inherited from GtkOrientable (2)
Properties
Properties inherited from GtkCellEditable (1)
Properties inherited from GtkOrientable (1)
Signals
Gtk.SpinButton::change-value
The ::change-value signal is a [keybinding signal][GtkBindingSignal] which gets emitted when the user initiates a value change.
Gtk.SpinButton::input
The ::input signal can be used to influence the conversion of
the users input into a double value. The signal handler is
expected to use gtk_entry_get_text()
to retrieve the text of
the entry and set new_value
to the new value.
Gtk.SpinButton::output
The ::output signal can be used to change to formatting of the value that is displayed in the spin buttons entry.
Gtk.SpinButton::value-changed
The ::value-changed signal is emitted when the value represented by
spinbutton
changes. Also see the GtkSpinButton::output
signal.
Gtk.SpinButton::wrapped
The ::wrapped signal is emitted right after the spinbutton wraps from its maximum to minimum value or vice-versa.
since: 2.10