class Gtk::SpinButton

• Gtk::SpinButton
• Gtk::Widget
• GObject::InitiallyUnowned
• GObject::Object
• Reference
• Object

Overview

Allows to enter or change numeric values.

Rather than having to directly type a number into a Gtk::Entry, Gtk::SpinButton 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::SpinButton are through an adjustment. See the Gtk::Adjustment documentation for more details about an adjustment's properties.

Note that Gtk::SpinButton 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 [property@Gtk.Editable:width-chars] to a value != -1.

Using a Gtk::SpinButton to get an integer

WARNING ⚠️ The following code is in c ⚠️

// Provides a function to retrieve an integer value from a Gtk::SpinButton
// and creates a spin button to model percentage values.

int
grab_int_value (Gtk::SpinButton *button,
                gpointer       user_data)
{
  return gtk_spin_button_get_value_as_int (button);
}

void
create_integer_spin_button (void)
{

  Gtk::Widget *window, *button;
  Gtk::Adjustment *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_window_present (GTK_WINDOW (window));
}

Using a Gtk::SpinButton to get a floating point value

WARNING ⚠️ The following code is in c ⚠️

// Provides a function to retrieve a floating point value from a
// Gtk::SpinButton, and creates a high precision spin button.

float
grab_float_value (Gtk::SpinButton *button,
                  gpointer       user_data)
{
  return gtk_spin_button_get_value (button);
}

void
create_floating_spin_button (void)
{
  Gtk::Widget *window, *button;
  Gtk::Adjustment *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_window_present (GTK_WINDOW (window));
}

Shortcuts and Gestures

The following signals have default keybindings:

• [signal@Gtk.SpinButton::change-value]

CSS nodes

spinbutton.horizontal
├── text
│ ├── undershoot.left
│ ╰── undershoot.right
├── button.down
╰── button.up

spinbutton.vertical
├── button.up
├── text
│ ├── undershoot.left
│ ╰── undershoot.right
╰── button.down

Gtk::SpinButtons 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 Gtk::Text 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.

Accessibility

Gtk::SpinButton uses the Gtk::AccessibleRole#spin_button role.

Included Modules

• Gtk::Accessible
• Gtk::AccessibleRange
• Gtk::Buildable
• Gtk::CellEditable
• Gtk::ConstraintTarget
• Gtk::Editable
• Gtk::Orientable

Defined in:

Constructors

• .new(adjustment : Gtk::Adjustment | Nil, climb_rate : Float64, digits : UInt32) : self

  Creates a new Gtk::SpinButton.

• .new

  Initialize a new SpinButton.

• .new(*, accessible_role : Gtk::AccessibleRole | Nil = nil, activates_default : Bool | Nil = nil, adjustment : Gtk::Adjustment | Nil = nil, can_focus : Bool | Nil = nil, can_target : Bool | Nil = nil, climb_rate : Float64 | Nil = nil, css_classes : Enumerable(String) | Nil = nil, css_name : String | Nil = nil, cursor : Gdk::Cursor | Nil = nil, cursor_position : Int32 | Nil = nil, digits : UInt32 | Nil = nil, editable : Bool | Nil = nil, editing_canceled : Bool | Nil = nil, enable_undo : Bool | Nil = nil, focus_on_click : Bool | Nil = nil, focusable : Bool | Nil = nil, halign : Gtk::Align | Nil = nil, has_default : Bool | Nil = nil, has_focus : Bool | Nil = nil, has_tooltip : Bool | Nil = nil, height_request : Int32 | Nil = nil, hexpand : Bool | Nil = nil, hexpand_set : Bool | Nil = nil, layout_manager : Gtk::LayoutManager | Nil = nil, limit_events : Bool | Nil = nil, margin_bottom : Int32 | Nil = nil, margin_end : Int32 | Nil = nil, margin_start : Int32 | Nil = nil, margin_top : Int32 | Nil = nil, max_width_chars : Int32 | Nil = nil, name : String | Nil = nil, numeric : Bool | Nil = nil, opacity : Float64 | Nil = nil, orientation : Gtk::Orientation | Nil = nil, overflow : Gtk::Overflow | Nil = nil, parent : Gtk::Widget | Nil = nil, receives_default : Bool | Nil = nil, root : Gtk::Root | Nil = nil, scale_factor : Int32 | Nil = nil, selection_bound : Int32 | Nil = nil, sensitive : Bool | Nil = nil, snap_to_ticks : Bool | Nil = nil, text : String | Nil = nil, tooltip_markup : String | Nil = nil, tooltip_text : String | Nil = nil, update_policy : Gtk::SpinButtonUpdatePolicy | Nil = nil, valign : Gtk::Align | Nil = nil, value : Float64 | Nil = nil, vexpand : Bool | Nil = nil, vexpand_set : Bool | Nil = nil, visible : Bool | Nil = nil, width_chars : Int32 | Nil = nil, width_request : Int32 | Nil = nil, wrap : Bool | Nil = nil, xalign : Float32 | Nil = nil)
• .new_with_range(min : Float64, max : Float64, step : Float64) : self

  Creates a new Gtk::SpinButton with the given properties.

Class Method Summary

• .g_type : UInt64

  Returns the type id (GType) registered in GLib type system.

Instance Method Summary

• #==(other : self)

  Returns true if this reference is the same as other.

• #activate_signal
• #activates_default : Bool

  Retrieves the value set by Gtk::SpinButton#activates_default=.

• #activates_default=(activates_default : Bool) : Nil

  Sets whether activating the spin button will activate the default widget for the window containing the spin button.

• #activates_default? : Bool
• #adjustment : Gtk::Adjustment

  Get the adjustment associated with a Gtk::SpinButton.

• #adjustment=(adjustment : Gtk::Adjustment) : Nil

  Replaces the Gtk::Adjustment associated with spin_button.

• #adjustment=(value : Gtk::Adjustment | Nil) : Gtk::Adjustment | Nil
• #change_value_signal
• #climb_rate : Float64

  Returns the acceleration rate for repeated changes.

• #climb_rate=(climb_rate : Float64) : Nil

  Sets the acceleration rate for repeated changes when you hold down a button or key.

• #configure(adjustment : Gtk::Adjustment | Nil, climb_rate : Float64, digits : UInt32) : Nil

  Changes the properties of an existing spin button.

• #digits : UInt32

  Fetches the precision of spin_button.

• #digits=(digits : UInt32) : Nil

  Set the precision to be displayed by spin_button.

• #hash(hasher)

  See Object#hash(hasher)

• #increments : Nil

  Gets the current step and page the increments used by spin_button.

• #input_signal
• #numeric : Bool

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

• #numeric=(numeric : Bool) : Nil

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

• #numeric? : Bool
• #output_signal
• #range : Nil

  Gets the range allowed for spin_button.

• #set_increments(step : Float64, page : Float64) : Nil

  Sets the step and page increments for spin_button.

• #set_range(min : Float64, max : Float64) : Nil

  Sets the minimum and maximum allowable values for spin_button.

• #snap_to_ticks : Bool

  Returns whether the values are corrected to the nearest step.

• #snap_to_ticks=(snap_to_ticks : Bool) : Nil

  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.

• #snap_to_ticks? : Bool
• #spin(direction : Gtk::SpinType, increment : Float64) : Nil

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

• #update : Nil

  Manually force an update of the spin button.

• #update_policy : Gtk::SpinButtonUpdatePolicy

  Gets the update behavior of a spin button.

• #update_policy=(policy : Gtk::SpinButtonUpdatePolicy) : Nil

  Sets the update behavior of a spin button.

• #value : Float64

  Get the value in the spin_button.

• #value=(value : Float64) : Nil

  Sets the value of spin_button.

• #value_as_int : Int32

  Get the value spin_button represented as an integer.

• #value_changed_signal
• #wrap : Bool

  Returns whether the spin button’s value wraps around to the opposite limit when the upper or lower limit of the range is exceeded.

• #wrap=(wrap : Bool) : Nil

  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.

• #wrap? : Bool
• #wrapped_signal

Constructor Detail

Class Method Detail

Instance Method Detail