PyGTK - SpinButton Class


The SpinnButton widget, often called the Spinner is a gtk.Entry widget with up and down arrows on its right. A user can type in a numeric value directly in it or increment or decrement using up and down arrows. The gtk.SpinButton class is inherited from the gtk.Entry class. It uses a gtk.Adjustment object with which the range and step of the numeric value in the spinner can be restricted.

The SpinButton widget is created using the following constructor −

sp = gtk.SpinButton(adj, climb_rate, digits)

Here, adj represents the gtk.Adjustment object controlling range, climb_rate is an acceleration factor and the number of decimals specified by digits.

The gtk.SpinButton class has the following methods −

  • SpinButton.set_adjustment() − This sets the "adjustment" property.

  • SpinButton.set_digits() − This sets the "digits" property to the value to determine the number of decimal places to be displayed by the spinbutton.

  • SpinButton.set_increments(step, page) − This sets the step value which has increment applied for each left mousebutton press and page value which is increment applied for each middle mousebutton press.

  • SpinButton.set_range() − This sets the minimum and maximum allowable values for spinbutton.

  • SpinButton.set_value() − This sets the spin button to a new value programmatically.

  • SpinButton.update_policy() − The valid values are gtk.UPDATE_ALWAYS and gtk.UPDATE_VALID

  • SpinButton.spin(direction, increment=1) − This increments or decrements Spinner's value in the specified direction.

The following are the predefined direction constants −

gtk.SPIN_STEP_FORWARD forward by step_increment
gtk.SPIN_STEP_BACKWARD backward by step_increment
gtk.SPIN_PAGE_FORWARD forward by step_increment
gtk.SPIN_PAGE_BACKWARD backward by step_increment
gtk.SPIN_HOME move to minimum value
gtk.SPIN_END move to maximum value
gtk.SPIN_USER_DEFINED add increment to the value
  • SpinButton.set_wrap() — If wrap is True, the spin button value wraps around to the opposite limit when the upper or lower limit of the range exceeds.

The gtk.SpinButton widget emits the following signals −

change-value This is emitted when the spinbutton value is changed by keyboard action
input This is emitted when the value changes.
output This is emitted when the spinbutton display value is changed. Returns True if the handler successfully sets the text and no further processing is required.
value-changed This is emitted when any of the settings that change the display of the spinbutton is changed.
wrapped This is emitted right after the spinbutton wraps from its maximum to minimum value or vice-versa.


The following example constructs a simple Date Selector by using three SpinButton widgets. The Day Selector is applied an Adjustment object to restrict value between 1—31. The second selector is for the number of months 1—12. The third selector selects the year range 2000—2020.

Observe the code −

import gtk

class PyApp(gtk.Window):
   def __init__(self):
      super(PyApp, self).__init__()
      self.set_title("SpinButton Demo")
      self.set_size_request(300, 200)
      vbox = gtk.VBox(False, 5)
      hbox = gtk.HBox(True, 3)
      lbl1 = gtk.Label("Date")
      adj1 = gtk.Adjustment(1.0, 1.0, 31.0, 1.0, 5.0, 0.0)
      spin1 = gtk.SpinButton(adj1, 0, 0)
      lbl2 = gtk.Label("Month")
      adj2 = gtk.Adjustment(1.0, 1.0, 12.0, 1.0, 5.0, 0.0)
      spin2 = gtk.SpinButton(adj2, 0, 0)
      lbl3 = gtk.Label("Year")
      adj3 = gtk.Adjustment(1.0, 2000.0, 2020.0, 1.0, 5.0, 0.0)
      spin3 = gtk.SpinButton(adj3, 0, 0)
      frame = gtk.Frame()
      frame.set_label("Date of Birth")
      self.connect("destroy", gtk.main_quit)

Upon execution, the above code will produce the following output −

SpinButton Demo