23. The Spinbox widget

23. The `Spinbox` widget

The Spinbox widget allows the user to select values from a given set. The values may be a range of numbers, or a fixed set of strings.

On the screen, a Spinbox has an area for displaying the current values, and a pair of arrowheads.

The user can click the upward-pointing arrowhead to advance the value to the next higher value in sequence. If the value is already at maximum, you can set up the widget, if you wish, so that the new value will wrap around to the lowest value.
The user can click the downward-pointing arrowhead to advance the value to the next lower value in sequence. This arrow may also be configured to wrap around, so that if the current value is the lowest, clicking on the down-arrow will display the highest value.
The user can also enter values directly, treating the widget as if it were an Entry. The user can move the focus to the widget (see Section 53, “Focus: routing keyboard input”), either by clicking on it or by using tab or shift-tab, and then edit the displayed value.

To create a new Spinbox widget as the child of a root window or frame parent:

    w = tk.Spinbox(parent, option, ...)

The constructor returns the new Spinbox widget. Options include:

Table 32. Spinbox widget options

`activebackground`	Background color when the cursor is over the widget; see Section 5.3, “Colors”.
`bg` or `background`	Background color of the widget.
`bd` or `borderwidth`	Width of the border around the widget; see Section 5.1, “Dimensions”. The default value is one pixel.
`buttonbackground`	The background color displayed on the arrowheads. The default is gray.
`buttoncursor`	The cursor to be displayed when the mouse is over the arrowheads; see Section 5.8, “Cursors”.
`buttondownrelief`	The relief style for the downward-pointing arrowhead; see Section 5.6, “Relief styles”. The default style is `tk.RAISED`.
`buttonup`	The relief style for the upward-pointing arrowhead; see Section 5.6, “Relief styles”. The default style is `tk.RAISED`.
`command`	Use this option to specify a function or method to be called whenever the user clicks on one of the arrowheads. Note that the callback is not called when the user edits the value directly as if it were an `Entry`.
`cursor`	Selects the cursor that is displayed when the mouse is over the entry part of the widget; see Section 5.8, “Cursors”.
`disabledbackground`	These options select the background and foreground colors displayed when the widget's `state` is `tk.DISABLED`.
`disabledforeground`
`exportselection`	Normally, the text in the entry portion of a `Spinbox` can be cut and pasted. To prohibit this behavior, set the `exportselection` option to `True`.
`font`	Use this option to select a different typeface for the entry text; see Section 5.4, “Type fonts”.
`fg` or `foreground`	This option selects the color used to display the text in the entry part of the widget, and the color of the arrowheads.
`format`	Use this option to control the formatting of numeric values in combination with the `from_` and `to` options. For example, `format='%10.4f'` would display the value as a ten-character field, with four digits after the decimal.
`from_`	Use this option in combination with the `to` option (described below) to constrain the values to a numeric range. For example, `from_=1` and `to=9` would allow only values between 1 and 9 inclusive. See also the `increment` option below.
`highlightbackground`	The color of the focus highlight when the `Spinbox` does not have focus. See Section 53, “Focus: routing keyboard input”.
`highlightcolor`	The color of the focus highlight when the `Spinbox` has the focus.
`highlightthickness`	The thickness of the focus highlight. Default is `1`. Set to `0` to suppress display of the focus highlight.
`increment`	When you constrain the values with the `from_` and `to` options, you can use the `increment` option to specify how much the value increases or decreases when the user clicks on an arrowhead. For example, with options `from_=0.0`, `to=2.0`, and `increment=0.5`, the up-arrowhead will step through values 0.0, 0.5, 1.0, 1.5, and 2.0.
`insertbackground`	Selects the color of the insertion cursor displayed in the entry part of the widget.
`insertborderwidth`	This option controls the width of the border around the insertion cursor. Normally, the insertion cursor will have no border. If this option is set to a nonzero value, the insertion cursor will be displayed in the `tk.RAISED` relief style.
`insertofftime`	These two options control the blink cycle of the insertion cursor: the amount of time it spends off and on, respectively, in milliseconds. For example, with options `insertofftime=200` and `insertontime=400`, the cursor would blink off for 0.2 seconds and then on for 0.4 seconds.
`insertontime`
`insertwidth`	Use this option to specify the width of the insertion cursor; for possible values, see Section 5.1, “Dimensions”. The default width is two pixels.
`justify`	This option controls the position of the text in the entry part of the widget. Values may be `tk.LEFT` to left-justify the text; `tk.CENTER` to center it; or `RIGHT` to right-justify the text.
`readonlybackground`	This option specifies the background color that will be displayed when the widget's `state` is `'readonly'`; see Section 5.3, “Colors”.
`relief`	Use this option to select a relief style for the widget; see Section 5.6, “Relief styles”. The default style is `tk.SUNKEN`.
`repeatdelay`	These options specify the auto-repeat behavior of mouse clicks on the arrowheads; values are in milliseconds. The `repeatdelay` value specifies how long the mouse button must be held down before it repeats, and `repeatinterval` specifies how often the function repeats. Default values are 400 and 100 milliseconds, respectively.
`repeatinterval`
`selectbackground`	The background color to use displaying selected items.
`selectborderwidth`	The width of the border to display around selected items.
`selectforeground`	The foreground color to use displaying selected items.
`state`	Normally, a `Spinbox` widget is created in the `tk.NORMAL` state. Set this option to `tk.DISABLED` to make the widget unresponsive to mouse or keyboard actions. If you set it to `'readonly'`, the value in the entry part of the widget cannot be modified with keystrokes, but the value can still be copied to the clipboard, and the widget still responds to clicks on the arrowheads.
`takefocus`	Normally, the entry part of a `Spinbox` widget can have focus (see Section 53, “Focus: routing keyboard input”). To remove the widget from the focus traversal sequence, set `takefocus=False`.
`textvariable`	If you want to retrieve the current value of the widget, you can use the `.get()` method below, or you can associate a control variable with the widget by passing that control variable as the value of this option. See Section 52, “Control variables: the values behind the widgets”.
`to`	This option specifies the upper limit of a range values. See the `from_` option, above, and also the `increment` option.
`values`	There are two ways to specify the possible values of the widget. One way is to provide a tuple of strings as the value of the `values` option. For example, `values=('red', 'blue', 'green')` would allow only those three strings as values. To configure the widget to accept a range of numeric values, see the `from_` option above.
`width`	Use this option to specify the number of characters allowed in the entry part of the widget. The default value is 20.
`wrap`	Normally, when the widget is at its highest value, the up-arrowhead does nothing, and when the widget is at its lowest value, the down-arrowhead does nothing. If you select `wrap=True`, the up-arrowhead will advance from the highest value back to the lowest, and the down-arrowhead will advance from the lowest value back to the highest.
`xscrollcommand`	Use this option to connect a scrollbar to the entry part of the widget. For details, see Section 22.2, “Connecting a `Scrollbar` to another widget”.

These methods are available on Spinbox widgets:

.bbox(index)

This method returns the bounding box of the character at position index in the entry part of the widget. The result is a tuple (x, y, w, h), where the values are the x and y coordinates of the upper left corner, and the character's width and height in pixels, in that order.

.delete(first, last=None)

This method deletes characters from the entry part of the Spinbox. The values of first and last are interpreted in the standard way for Python slices.

.get()

This method returns the value of the Spinbox. The value is always returned as a string, even if the widget is set up to contain a number.

.icursor(index)

Use this method to position the insertion cursor at the location specified by index, using the standard Python convention for positions.

.identify(x, y)

Given a position (x, y) within the widget, this method returns a string describing what is at that location. Values may be any of:

'entry' for the entry area.
'buttonup' for the upward-pointing arrowhead.
'buttondown' for the downward-pointing arrowhead.
'' (an empty string) if these coordinates are not within the widget.

.index(i)

This method returns the numerical position of an index i. Arguments may be any of:

tk.END to get the position after the last character of the entry.
tk.INSERT to get the position of the insertion cursor.
tk.ANCHOR to get the position of the selection anchor.
tk.SEL_FIRST' to get the position of the start of the selection. If the selection is not within the widget, this method raises a tk.TclError exception.
tk.SEL_LAST to get the position just past the end of the selection. If the selection is not within the widget, this method raises a tk.TclError exception.
A string of the form “@x” denotes an x-coordinate within the widget. The return value is the position of the character containing that coordinate. If the coordinate is outside the widget altogether, the return value will be the position of the character closest to that position.

.insert(index, text)

This method inserts characters from the string text at the position specified by index. For the possible index values, see the .index() method above.

.invoke(element)

Call this method to get the same effect as the user clicking on an arrowhead. The element argument is 'buttonup' for the up-arrowhead, and 'buttondown' for the down-arrowhead.

.scan_dragto(x)

This method works the same as the .scan_dragto() method described in Section 10, “The Entry widget”.

.scan_mark(x)

This method works the same as the .scan_mark() method described in Section 10, “The Entry widget”.

.selection('from', index)

Sets the selection anchor in the widget to the position specified by the index. For the possible values of index, see the .index() method above. The initial value of the selection anchor is 0.

.selection('to', index)

Selects the text between the selection anchor and the given index.

.selection('range', start, end)

Select the text between the start and end indices. For allowable index values, see the .index() method above.

.selection_clear()

Clears the selection.

.selection_get()

Returns the selected text. If there is currently no selection, this method will raise a tk.TclError exception.

Tkinter 8.5 reference: a GUI for Python

23. The Spinbox widget

23. The `Spinbox` widget