gtk.SpinButton
Prev | The gtk Class Reference | Next

## gtk.SpinButton

gtk.SpinButton — retrieve an integer or floating-point number from the user.

## Synopsis

    class gtk.SpinButton(gtk.Entry):
        gtk.SpinButton(adjustment=None, climb_rate=0.0, digits=0)
        def configure(adjustment, climb_rate, digits)
        def set_adjustment(adjustment)
        def get_adjustment()
        def set_digits(digits)
        def get_digits()
        def set_increments(step, page)
        def get_increments()
        def set_range(min, max)
        def get_range()
        def get_value()
        def get_value_as_int()
        def set_value(value)
        def set_update_policy(policy)
        def get_update_policy()
        def set_numeric(numeric)
        def get_numeric()
        def spin(direction, increment=1.0)
        def set_wrap(wrap)
        def get_wrap()
        def set_snap_to_ticks(snap_to_ticks)
        def get_snap_to_ticks()
        def update()

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget
          +-- gtk.Entry (implements gtk.Editable, gtk.CellEditable)
            +-- gtk.SpinButton

## Implemented Interfaces

`gtk.SpinButton` implements `gtk.Buildable`

## gtk.SpinButton Properties

gtk.Object Properties

gtk.Widget Properties

gtk.Entry Properties

"adjustment" | Read-Write | The adjustment that holds the value of the spinbutton
"climb-rate" | Read-Write | The acceleration rate when you hold down a button
"digits" | Read-Write | The number of decimal places to display
"numeric" | Read-Write | If `True`, non-numeric characters should be ignored
"snap-to-ticks" | Read-Write | If `True`, erroneous values are automatically changed to a spin button's nearest step increment
"update-policy" | Read-Write | either `gtk.UPDATE_ALWAYS` (the spin button should update always), or `gtk.UPDATE_IF_VALID` the spin button should update only when the value is legal)
"value" | Read-Write | the current value
"wrap" | Read-Write | If `True`, a spin button should wrap upon reaching its limits

## gtk.SpinButton Style Properties

gtk.Widget Style Properties

gtk.Entry Style Properties

"shadow-type" | Read | the shadow type of the spinbutton - one of: `gtk.SHADOW_NONE`, `gtk.SHADOW_IN`, `gtk.SHADOW_OUT`, `gtk.SHADOW_ETCHED_IN` or `gtk.SHADOW_ETCHED_OUT`

## gtk.SpinButton Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

gtk.Entry Signal Prototypes

gtk.Editable Signal Prototypes

gtk.CellEditable Signal Prototypes

"change-value" | `def callback(`spinbutton`, `scrolltype`, `user_param1`, `...`)`
"input" | `def callback(`spinbutton`, `value_ptr`, `user_param1`, `...`)`
"output" | `def callback(`spinbutton`, `user_param1`, `...`)`
"value-changed" | `def callback(`spinbutton`, `user_param1`, `...`)`
"wrapped | `def callback(`spinbutton`, `user_param1`, `...`)`

## Description

A `gtk.SpinButton` is a subclass of `gtk.Entry` that provides a way for a user to set the value of some numeric attribute within a predefined range. Rather than having to directly type a number into a `gtk.Entry`, a `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 and validated. A `gtk.SpinButton` uses a `gtk.Adjustment` to specify the range and value of interest. See the `gtk.Adjustment` section for more details about an adjustment's properties.

## Constructor

        gtk.SpinButton(adjustment=None, climb_rate=0.0, digits=0)

`adjustment` : | a `gtk.Adjustment` or None to create a new adjustment
`climb_rate` : | the acceleration factor
`digits` : | the number of decimal places to display
Returns : | a new `gtk.SpinButton` widget

Creates a new `gtk.SpinButton` widget using the `gtk.Adjustment` specified by `adjustment`, the acceleration factor specified by `climb_rate` and displaying the number of decimals specified by `digits`. If `adjustment` is `None` or is not specified a new `gtk.Adjustment` will be created. If `climb_rate` is not specified it defaults to 0.0. If `digits` is not specified it defaults to 0.

## Methods

### gtk.SpinButton.configure

        def configure(adjustment, climb_rate, digits)

`adjustment` : | a `gtk.Adjustment` or None to create a new adjustment
`climb_rate` : | the acceleration factor
`digits` : | the number of decimal places to display

The `configure`() method changes the properties of an existing spin button by associating the `gtk.Adjustment` specified by `adjustment`, setting the acceleration rate to the c value specified by `climb_rate` and setting the number of decimal places to display to the value specified by `digits`. If `adjustment` is `None` a new `gtk.Adjustment` will be created.

### gtk.SpinButton.set_adjustment

        def set_adjustment(adjustment)

`adjustment` : | a `gtk.Adjustment` to replace the existing adjustment

The `set_adjustment`() method sets the "adjustment" property to the value specified by `adjustment` replacing the current adjustment object associated with the spinbutton.

### gtk.SpinButton.get_adjustment

        def get_adjustment()

Returns : | the `gtk.Adjustment` object associated with the spinbutton

The `get_adjustment`() method returns the value of the "adjustment" property.

### gtk.SpinButton.set_digits

        def set_digits(digits)

`digits` : | the number of decimal places to be displayed for the spin button's value

The `set_digits`() method sets the "digits" property to the value specified by `digits`. The value of "digits" determines the number of decimal places (up to 20 digits) to be displayed by the spinbutton.

### gtk.SpinButton.get_digits

        def get_digits()

Returns : | the current number of decimal places to be displayed

The `get_digits`() method returns the value of the "digits" property. The value of "digits" determines the number of decimal places the spinbutton displays. See the `set_digits`() method for more detail.

### gtk.SpinButton.set_increments

        def set_increments(step, page)

`step` : | increment applied for each left mousebutton press.
`page` : | increment applied for each middle mousebutton press.

The `set_increments`() method sets the `step_increment` and `page_increment` attributes of the `gtk.Adjustment` associated with the spinbutton to the values specified by `step` and `page` respectively. These affect how quickly the value changes when the spin button's arrows are activated.

### gtk.SpinButton.get_increments

        def get_increments()

Returns : | a tuple containing the step and page increments

The `get_increments`() method returns a tuple containing the values of the `step_increment` and `page_increment` attributes of the `gtk.Adjustment` associated with the spinbutton. See the `set_increments`() method for more detail.

### gtk.SpinButton.set_range

        def set_range(min, max)

`min` : | the minimum allowable value
`max` : | the maximum allowable value

The `set_range`() method sets the minimum and maximum allowable values for spinbutton by setting the `lower` and `upper` attributes of the associated `gtk.Adjustment` to the values of `min` and `max` respectively.

### gtk.SpinButton.get_range

        def get_range()

Returns : | a tuple containing the minimum and maximum allowed values

The `get_range`() method returns a tuple containing the range allowed for the spinbutton. See the `set_range`() method for more detail.

### gtk.SpinButton.get_value

        def get_value()

Returns : | the value of the spin_button

The `get_value`() method returns the value of the "value" property of the spinbutton (really the `value` attribute of the associated `gtk.Adjustment`).

### gtk.SpinButton.get_value_as_int

        def get_value_as_int()

Returns : | the value of the spinbutton as an integer

The `get_value_as_int`() method returns the value of the spinbutton represented as an integer.

### gtk.SpinButton.set_value

        def set_value(value)

`value` : | the new value

The `set_value`() method sets the value of the "value" property to the value specified by `value` (sets the `value` attribute of the associated `gtk.Adjustment`.

### gtk.SpinButton.set_update_policy

        def set_update_policy(policy)

`policy` : | the new update policy

The `set_update_policy`() method sets the "update-policy" property to the value of `policy`. The value of `policy` is either of:

`gtk.UPDATE_ALWAYS` | the value is always displayed.
`gtk.UPDATE_IF_VALID` | the value is only displayed if it is valid within the bounds of the spinbutton's `gtk.Adjustment`.

### gtk.SpinButton.get_update_policy

        def get_update_policy()

Returns : | the current update policy

The `get_update_policy`() method returns the value of the "update-policy" property that determines the update behavior of a spin button. See the `set_update_policy`() method for more detail.

### gtk.SpinButton.set_numeric

        def set_numeric(numeric)

`numeric` : | a flag indicating if only numeric entry is allowed.

The `set_numeric`() method sets the value of the "numeric" property to the value of `numeric`. If `numeric` is `True` only numeric text can be typed into the spin button.

### gtk.SpinButton.get_numeric

        def get_numeric()

Returns : | `True` if only numeric text can be entered

The `get_numeric`() method returns the value of the "numeric" preoperty. See the `set_numeric`() method for more detail.

### gtk.SpinButton.spin

        def spin(direction, increment=1.0)

`direction` : | the direction to spin.
`increment` : | the step increment to apply in the specified direction.

The `spin`() method increments or decrements a spin button's value in the direction specified by `direction` with a step size specified by `increment`. The value of `increment` is only used if direction is `gtk.SPIN_USER_DEFINED`. The value of `direction` must be one of:

`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

### gtk.SpinButton.set_wrap

        def set_wrap(wrap)

`wrap` : | if `True` wrapping is performed.

The `set_wrap`() method sets the "wrap" property to the value of `wrap`. If `wrap` is `True` the spin button value wraps around to the opposite limit when the upper or lower limit of the range is exceeded.

### gtk.SpinButton.get_wrap

        def get_wrap()

Returns : | `True` if the spin button wraps

The `get_wrap`() method returns the value of the "wrap" property. If the value of "wrap" is `True` the spinbutton's value wraps around to the opposite limit when the upper or lower limit of the range is exceeded. See the `set_wrap`() method.

### gtk.SpinButton.set_snap_to_ticks

        def set_snap_to_ticks(snap_to_ticks)

`snap_to_ticks` : | if `True` invalid values should be corrected.

The `set_snap_to_ticks`() method sets the "snap-to-ticks" property to the value of `snap_to_ticks`. If `snap_to_ticks` is `True` values are corrected to the nearest step increment when a spin button is activated after providing an invalid value.

### gtk.SpinButton.get_snap_to_ticks

        def get_snap_to_ticks()

Returns : | `True` if values are snapped to the nearest step.

The `get_snap_to_ticks`() method returns the value of the "snap-to-ticks" property. If the value of "snap-to-ticks" is `True` the input values are corrected to the nearest step. See the `set_snap_to_ticks`() method.

### gtk.SpinButton.update

        def update()

The `update`() method manually forces an update of the spin button.

## Signals

### The "change-value" gtk.SpinButton Signal

        def callback(spinbutton, scrolltype, user_param1, ...)

`spinbutton` : | the spinbutton that received the signal
`scrolltype` : | the scrolltype: `gtk.SCROLL_STEP_UP`, `gtk.SCROLL_STEP_DOWN`, `gtk.SCROLL_PAGE_UP`, `gtk.SCROLL_PAGE_DOWN, `gtk.SCROLL_START` or `gtk.SCROLL_END``
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "change-value" signal is emitted when the spinbutton value is changed by keyboard action using the Up Arrow, Down Arrow, Page Up, Page Down, Control+Page Up or Control+Page Down keys.

### The "input" gtk.SpinButton Signal

        def callback(spinbutton, value_ptr, user_param1, ...)

`spinbutton` : | the spinbutton that received the signal
`value_ptr` : | a pointer to the value
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if the input value was retrieved and handled; `False` if not handled and -1 if an error occurred during processing.

The "input" signal is emitted when the value changes. The value_ptr is a GPointer to the value that cannot be accessed from PyGTK. This signal cannot be handled in PyGTK.

### The "output" gtk.SpinButton Signal

        def callback(spinbutton, user_param1, ...)

`spinbutton` : | the spinbutton that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)
Returns : | `True` if no further processing is required.

The "output" signal is emitted when the spinbutton display value is changed either by setting a new value or changing the digits and on realizing the widget. Returns `True` if the handler successfully set the text and no further processing is required.

### The "value-changed" gtk.SpinButton Signal

        def callback(spinbutton, user_param1, ...)

`spinbutton` : | the spinbutton that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "value-changed" signal is emitted when any of the settings (i.e. value, digits) that change the display of the spinbutton are changed.

### The "wrapped" gtk.SpinButton Signal

        def callback(spinbutton, user_param1, ...)

`spinbutton` : | the object which received the signal the object which received the signal.
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in GTK+ 2.10 and above.

The "wrapped" signal is emitted right after the spinbutton wraps from its maximum to minimum value or vice-versa.

Prev | Up | Next
gtk.Socket | Home | gtk.Spinner