gtk.SpinButton

gtk.SpinButton
Prev	The gtk Class Reference	Next

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)
    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

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)

`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.