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);
}
[]

Hierarchy

hierarchy this GtkSpinButton implements_0 AtkImplementorIface this--implements_0 implements_1 GtkBuildable this--implements_1 implements_2 GtkCellEditable this--implements_2 implements_3 GtkEditable this--implements_3 implements_4 GtkOrientable this--implements_4 ancestor_0 GtkEntry ancestor_0--this ancestor_1 GtkWidget ancestor_1--ancestor_0 ancestor_2 GInitiallyUnowned ancestor_2--ancestor_1 ancestor_3 GObject ancestor_3--ancestor_2
[]

Constructors

gtk_spin_button_new

Creates a new GtkSpinButton.

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_adjustment

Get the adjustment associated with a GtkSpinButton.

gtk_spin_button_get_digits

Fetches the precision of spin_button. See gtk_spin_button_set_digits().

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_range

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

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_value

Get the value in the spin_button.

gtk_spin_button_get_value_as_int

Get the value spin_button represented as an integer.

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_adjustment

Replaces the GtkAdjustment associated with spin_button.

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_range

Sets the minimum and maximum allowable values for 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_value

Sets the value of spin_button.

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.

gtk_spin_button_update

Manually force an update of the spin button.

Methods inherited from GtkEntry (74)
Methods inherited from GtkWidget (263)
Methods inherited from GObject (43)
Methods inherited from GtkBuildable (10)
Methods inherited from GtkCellEditable (3)
Methods inherited from GtkEditable (13)
Methods inherited from GtkOrientable (2)
[]

Properties

Gtk.SpinButton:adjustment
No description available.

Gtk.SpinButton:climb-rate
No description available.

Gtk.SpinButton:digits
No description available.

Gtk.SpinButton:numeric
No description available.

Gtk.SpinButton:snap-to-ticks
No description available.

Gtk.SpinButton:update-policy
No description available.

Gtk.SpinButton:value
No description available.

Gtk.SpinButton:wrap
No description available.

Properties inherited from GtkEntry (51)
Properties inherited from GtkWidget (39)
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

Signals inherited from GtkEntry (14)
Signals inherited from GtkWidget (69)
Signals inherited from GObject (1)
Signals inherited from GtkCellEditable (2)
Signals inherited from GtkEditable (3)

Class structure

[]

Virtual methods

Gtk.SpinButtonClass.change_value
No description available.

Gtk.SpinButtonClass.input
No description available.

Gtk.SpinButtonClass.output
No description available.

Gtk.SpinButtonClass.value_changed
No description available.

Gtk.SpinButtonClass.wrapped
No description available.