1spinbox(n) Tk Built-In Commands spinbox(n)
2______________________________________________________________________________
6
8 spinbox - Create and manipulate 'spinbox' value spinner widgets
9
11 spinbox pathName ?options?
12
14 -activebackground -highlightthickness -repeatinterval
15 -background -insertbackground -selectbackground
16 -borderwidth -insertborderwidth -selectborderwidth
17 -cursor -insertontime -selectforeground
18 -exportselection -insertwidth -takefocus
19 -font -insertofftime -textvariable
20 -foreground -justify -xscrollcommand
21 -highlightbackground -relief
22 -highlightcolor -repeatdelay
23 See the options manual entry for details on the standard options.
25
27 Command-Line Name:-buttonbackground
28 Database Name: buttonBackground
29 Database Class: Background
30 The background color to be used for the spin buttons.
32 Command-Line Name:-buttoncursor
34 Database Name: buttonCursor
35 Database Class: Cursor
36 The cursor to be used when over the spin buttons. If this is
38 empty (the default), a default cursor will be used.
39 Command-Line Name:-buttondownrelief
41 Database Name: buttonDownRelief
42 Database Class: Relief
43 The relief to be used for the upper spin button.
45 Command-Line Name:-buttonuprelief
47 Database Name: buttonUpRelief
48 Database Class: Relief
49 The relief to be used for the lower spin button.
51 Command-Line Name:-command
53 Database Name: command
54 Database Class: Command
55 Specifies a Tcl command to invoke whenever a spinbutton is in‐
57 voked. The command recognizes several percent substitutions: %W
58 for the widget path, %s for the current value of the widget, and
59 %d for the direction of the button pressed (up or down).
60 Command-Line Name:-disabledbackground
62 Database Name: disabledBackground
63 Database Class: DisabledBackground
64 Specifies the background color to use when the spinbox is dis‐
66 abled. If this option is the empty string, the normal back‐
67 ground color is used.
68 Command-Line Name:-disabledforeground
70 Database Name: disabledForeground
71 Database Class: DisabledForeground
72 Specifies the foreground color to use when the spinbox is dis‐
74 abled. If this option is the empty string, the normal fore‐
75 ground color is used.
76 Command-Line Name:-format
78 Database Name: format
79 Database Class: Format
80 Specifies an alternate format to use when setting the string
82 value when using the -from and -to range. This must be a format
83 specifier of the form %<pad>.<pad>f, as it will format a float‐
84 ing-point number.
85 Command-Line Name:-from
87 Database Name: from
88 Database Class: From
89 A floating-point value corresponding to the lowest value for a
91 spinbox, to be used in conjunction with -to and -increment.
92 When all are specified correctly, the spinbox will use these
93 values to control its contents. This value must be less than
94 the -to option. If -values is specified, it supersedes this op‐
95 tion.
96 Command-Line Name:-invalidcommand or -invcmd
98 Database Name: invalidCommand
99 Database Class: InvalidCommand
100 Specifies a script to eval when -validatecommand returns 0.
102 Setting it to an empty string disables this feature (the de‐
103 fault). The best use of this option is to set it to bell. See
104 VALIDATION below for more information.
105 Command-Line Name:-increment
107 Database Name: increment
108 Database Class: Increment
109 A floating-point value specifying the increment. When used with
111 -from and -to, the value in the widget will be adjusted by -in‐
112 crement when a spin button is pressed (up adds the value, down
113 subtracts the value).
114 Command-Line Name:-readonlybackground
116 Database Name: readonlyBackground
117 Database Class: ReadonlyBackground
118 Specifies the background color to use when the spinbox is read‐
120 only. If this option is the empty string, the normal background
121 color is used.
122 Command-Line Name:-state
124 Database Name: state
125 Database Class: State
126 Specifies one of three states for the spinbox: normal, dis‐
128 abled, or readonly. If the spinbox is readonly, then the value
129 may not be changed using widget commands and no insertion cursor
130 will be displayed, even if the input focus is in the widget; the
131 contents of the widget may still be selected. If the spinbox is
132 disabled, the value may not be changed, no insertion cursor will
133 be displayed, the contents will not be selectable, and the spin‐
134 box may be displayed in a different color, depending on the val‐
135 ues of the -disabledforeground and -disabledbackground options.
136 Command-Line Name:-to
138 Database Name: to
139 Database Class: To
140 A floating-point value corresponding to the highest value for
142 the spinbox, to be used in conjunction with -from and -incre‐
143 ment. When all are specified correctly, the spinbox will use
144 these values to control its contents. This value must be
145 greater than the -from option. If -values is specified, it su‐
146 persedes this option.
147 Command-Line Name:-validate
149 Database Name: validate
150 Database Class: Validate
151 Specifies the mode in which validation should operate: none, fo‐
153 cus, focusin, focusout, key, or all. It defaults to none. When
154 you want validation, you must explicitly state which mode you
155 wish to use. See VALIDATION below for more.
156 Command-Line Name:-validatecommand or -vcmd
158 Database Name: validateCommand
159 Database Class: ValidateCommand
160 Specifies a script to evaluate when you want to validate the in‐
162 put in the widget. Setting it to an empty string disables this
163 feature (the default). Validation occurs according to the value
164 of -validate. This command must return a valid Tcl boolean
165 value. If it returns 0 (or the valid Tcl boolean equivalent)
166 then the value of the widget will not change and the -invalid‐
167 command will be evaluated if it is set. If it returns 1, then
168 value will be changed. See VALIDATION below for more informa‐
169 tion.
170 Command-Line Name:-values
172 Database Name: values
173 Database Class: Values
174 Must be a proper list value. If specified, the spinbox will use
176 these values as to control its contents, starting with the first
177 value. This option has precedence over the -from and -to range.
178 Command-Line Name:-width
180 Database Name: width
181 Database Class: Width
182 Specifies an integer value indicating the desired width of the
184 spinbox window, in average-size characters of the widget's font.
185 If the value is less than or equal to zero, the widget picks a
186 size just large enough to hold its current text.
187 Command-Line Name:-wrap
189 Database Name: wrap
190 Database Class: wrap
191 Must be a proper boolean value. If on, the spinbox will wrap
193 around the values of data in the widget.
194______________________________________________________________________________
195
197 The spinbox command creates a new window (given by the pathName argu‐
198 ment) and makes it into a spinbox widget. Additional options, de‐
199 scribed above, may be specified on the command line or in the option
200 database to configure aspects of the spinbox such as its colors, font,
201 and relief. The spinbox command returns its pathName argument. At the
202 time this command is invoked, there must not exist a window named path‐
203 Name, but pathName's parent must exist.
204 A spinbox is an extended entry widget that allows he user to move, or
206 spin, through a fixed set of ascending or descending values such as
207 times or dates in addition to editing the value as in an entry. When
208 first created, a spinbox's string is empty. A portion of the spinbox
209 may be selected as described below. If a spinbox is exporting its se‐
210 lection (see the -exportselection option), then it will observe the
211 standard protocols for handling the selection; spinbox selections are
212 available as type STRING. Spinboxes also observe the standard Tk rules
213 for dealing with the input focus. When a spinbox has the input focus
214 it displays an insertion cursor to indicate where new characters will
215 be inserted.
216 Spinboxes are capable of displaying strings that are too long to fit
218 entirely within the widget's window. In this case, only a portion of
219 the string will be displayed; commands described below may be used to
220 change the view in the window. Spinboxes use the standard -xscrollcom‐
221 mand mechanism for interacting with scrollbars (see the description of
222 the -xscrollcommand option for details). They also support scanning,
223 as described below.
224
226 Validation works by setting the -validatecommand option to a script
227 which will be evaluated according to the -validate option as follows:
228 none Default. This means no validation will occur.
230 focus The -validatecommand will be called when the spinbox receives
232 or loses focus.
233 focusin The -validatecommand will be called when the spinbox receives
235 focus.
236 focusout The -validatecommand will be called when the spinbox loses
238 focus.
239 key The -validatecommand will be called when the spinbox is
241 edited.
242 all The -validatecommand will be called for all above conditions.
244 It is possible to perform percent substitutions on the -validatecommand
246 and -invalidcommand scripts, just as you would in a bind script. The
247 following substitutions are recognized:
248 %d Type of action: 1 for insert, 0 for delete, or -1 for focus,
250 forced or textvariable validation.
251 %i Index of char string to be inserted/deleted, if any, otherwise -1.
253 %P The value of the spinbox should edition occur. If you are config‐
255 uring the spinbox widget to have a new textvariable, this will be
256 the value of that textvariable.
257 %s The current value of spinbox before edition.
259 %S The text string being inserted/deleted, if any. Otherwise it is
261 an empty string.
262 %v The type of validation currently set.
264 %V The type of validation that triggered the callback (key, focusin,
266 focusout, forced).
267 %W The name of the spinbox widget.
269 In general, the -textvariable and -validatecommand can be dangerous to
271 mix. Any problems have been overcome so that using the -validatecom‐
272 mand will not interfere with the traditional behavior of the spinbox
273 widget. Using the -textvariable for read-only purposes will never
274 cause problems. The danger comes when you try set the -textvariable to
275 something that the -validatecommand would not accept, which causes
276 -validate to become none (the -invalidcommand will not be triggered).
277 The same happens when an error occurs evaluating the -validatecommand.
278 Primarily, an error will occur when the -validatecommand or -invalid‐
280 command encounters an error in its script while evaluating or -vali‐
281 datecommand does not return a valid Tcl boolean value. The -validate
282 option will also set itself to none when you edit the spinbox widget
283 from within either the -validatecommand or the -invalidcommand. Such
284 editions will override the one that was being validated. If you wish
285 to edit the value of the widget during validation and still have the
286 -validate option set, you should include the command
287 %W config -validate %v
288 in the -validatecommand or -invalidcommand (whichever one you were
289 editing the spinbox widget from). It is also recommended to not set an
290 associated -textvariable during validation, as that can cause the spin‐
291 box widget to become out of sync with the -textvariable.
292 Also, the -validate option will set itself to none when the spinbox
294 value gets changed because of adjustment of -from or -to and the -vali‐
295 datecommand returns false. For instance
296 spinbox pathName -from 1 -to 10 -validate all -vcmd {return 0}
297 will in fact set the -validate option to none because the default value
298 for the spinbox gets changed (due to the -from and -to options) to a
299 value not accepted by the validation script.
300 Moreover, forced validation is performed when invoking any spinbutton
302 of the spinbox. If the validation script returns false in this situa‐
303 tion, then the -validate option will be automatically set to none.
304
306 The spinbox command creates a new Tcl command whose name is pathName.
307 This command may be used to invoke various operations on the widget.
308 It has the following general form:
309 pathName option ?arg arg ...?
310 Option and the args determine the exact behavior of the command.
311 INDICES
313 Many of the widget commands for spinboxes take one or more indices as
314 arguments. An index specifies a particular character in the spinbox's
315 string, in any of the following ways:
316 number Specifies the character as a numerical index, where 0 cor‐
318 responds to the first character in the string.
319 anchor Indicates the anchor point for the selection, which is set
321 with the select from and select adjust widget commands.
322 end Indicates the character just after the last one in the
324 spinbox's string. This is equivalent to specifying a nu‐
325 merical index equal to the length of the spinbox's string.
326 insert Indicates the character adjacent to and immediately follow‐
328 ing the insertion cursor.
329 sel.first Indicates the first character in the selection. It is an
331 error to use this form if the selection is not in the spin‐
332 box window.
333 sel.last Indicates the character just after the last one in the se‐
335 lection. It is an error to use this form if the selection
336 is not in the spinbox window.
337 @number In this form, number is treated as an x-coordinate in the
339 spinbox's window; the character spanning that x-coordinate
340 is used. For example, “@0” indicates the left-most charac‐
341 ter in the window.
342 Abbreviations may be used for any of the forms above, e.g. “e” or
344 “sel.f”. In general, out-of-range indices are automatically rounded to
345 the nearest legal value.
346 SUBCOMMANDS
348 The following commands are possible for spinbox widgets:
349 pathName bbox index
351 Returns a list of four numbers describing the bounding box of
352 the character given by index. The first two elements of the
353 list give the x and y coordinates of the upper-left corner of
354 the screen area covered by the character (in pixels relative to
355 the widget) and the last two elements give the width and height
356 of the character, in pixels. The bounding box may refer to a
357 region outside the visible area of the window.
358 pathName cget option
360 Returns the current value of the configuration option given by
361 option. Option may have any of the values accepted by the spin‐
362 box command.
363 pathName configure ?option? ?value option value ...?
365 Query or modify the configuration options of the widget. If no
366 option is specified, returns a list describing all of the avail‐
367 able options for pathName (see Tk_ConfigureInfo for information
368 on the format of this list). If option is specified with no
369 value, then the command returns a list describing the one named
370 option (this list will be identical to the corresponding sublist
371 of the value returned if no option is specified). If one or
372 more option-value pairs are specified, then the command modifies
373 the given widget option(s) to have the given value(s); in this
374 case the command returns an empty string. Option may have any
375 of the values accepted by the spinbox command.
376 pathName delete first ?last?
378 Delete one or more elements of the spinbox. First is the index
379 of the first character to delete, and last is the index of the
380 character just after the last one to delete. If last is not
381 specified it defaults to first+1, i.e. a single character is
382 deleted. This command returns an empty string.
383 pathName get
385 Returns the spinbox's string.
386 pathName icursor index
388 Arrange for the insertion cursor to be displayed just before the
389 character given by index. Returns an empty string.
390 pathName identify x y
392 Returns the name of the window element corresponding to coordi‐
393 nates x and y in the spinbox. Return value is one of: none,
394 buttondown, buttonup, entry.
395 pathName index index
397 Returns the numerical index corresponding to index.
398 pathName insert index string
400 Insert the characters of string just before the character indi‐
401 cated by index. Returns an empty string.
402 pathName invoke element
404 Causes the specified element, either buttondown or buttonup, to
405 be invoked, triggering the action associated with it.
406 pathName scan option args
408 This command is used to implement scanning on spinboxes. It has
409 two forms, depending on option:
410 pathName scan mark x
412 Records x and the current view in the spinbox window;
413 used in conjunction with later scan dragto commands.
414 Typically this command is associated with a mouse button
415 press in the widget. It returns an empty string.
416 pathName scan dragto x
418 This command computes the difference between its x argu‐
419 ment and the x argument to the last scan mark command for
420 the widget. It then adjusts the view left or right by 10
421 times the difference in x-coordinates. This command is
422 typically associated with mouse motion events in the wid‐
423 get, to produce the effect of dragging the spinbox at
424 high speed through the window. The return value is an
425 empty string.
426 pathName selection option arg
428 This command is used to adjust the selection within a spinbox.
429 It has several forms, depending on option:
430 pathName selection adjust index
432 Locate the end of the selection nearest to the character
433 given by index, and adjust that end of the selection to
434 be at index (i.e. including but not going beyond index).
435 The other end of the selection is made the anchor point
436 for future select to commands. If the selection is not
437 currently in the spinbox, then a new selection is created
438 to include the characters between index and the most re‐
439 cent selection anchor point, inclusive. Returns an empty
440 string.
441 pathName selection clear
443 Clear the selection if it is currently in this widget.
444 If the selection is not in this widget then the command
445 has no effect. Returns an empty string.
446 pathName selection element ?element?
448 Sets or gets the currently selected element. If a spin‐
449 button element is specified, it will be displayed de‐
450 pressed.
451 pathName selection from index
453 Set the selection anchor point to just before the charac‐
454 ter given by index. Does not change the selection. Re‐
455 turns an empty string.
456 pathName selection present
458 Returns 1 if there is are characters selected in the
459 spinbox, 0 if nothing is selected.
460 pathName selection range start end
462 Sets the selection to include the characters starting
463 with the one indexed by start and ending with the one
464 just before end. If end refers to the same character as
465 start or an earlier one, then the spinbox's selection is
466 cleared.
467 pathName selection to index
469 If index is before the anchor point, set the selection to
470 the characters from index up to but not including the an‐
471 chor point. If index is the same as the anchor point, do
472 nothing. If index is after the anchor point, set the se‐
473 lection to the characters from the anchor point up to but
474 not including index. The anchor point is determined by
475 the most recent select from or select adjust command in
476 this widget. If the selection is not in this widget then
477 a new selection is created using the most recent anchor
478 point specified for the widget. Returns an empty string.
479 pathName set ?string?
481 If string is specified, the spinbox will try and set it to this
482 value, otherwise it just returns the spinbox's string. If vali‐
483 dation is on, it will occur when setting the string.
484 pathName validate
486 This command is used to force an evaluation of the -validatecom‐
487 mand independent of the conditions specified by the -validate
488 option. This is done by temporarily setting the -validate op‐
489 tion to all. It returns 0 or 1.
490 pathName xview args
492 This command is used to query and change the horizontal position
493 of the text in the widget's window. It can take any of the fol‐
494 lowing forms:
495 pathName xview
497 Returns a list containing two elements. Each element is
498 a real fraction between 0 and 1; together they describe
499 the horizontal span that is visible in the window. For
500 example, if the first element is .2 and the second ele‐
501 ment is .6, 20% of the spinbox's text is off-screen to
502 the left, the middle 40% is visible in the window, and
503 40% of the text is off-screen to the right. These are
504 the same values passed to scrollbars via the -xscrollcom‐
505 mand option.
506 pathName xview index
508 Adjusts the view in the window so that the character
509 given by index is displayed at the left edge of the win‐
510 dow.
511 pathName xview moveto fraction
513 Adjusts the view in the window so that the character
514 fraction of the way through the text appears at the left
515 edge of the window. Fraction must be a fraction between
516 0 and 1.
517 pathName xview scroll number what
519 This command shifts the view in the window left or right
520 according to number and what. Number must be an integer.
521 What must be either units or pages or an abbreviation of
522 one of these. If what is units, the view adjusts left or
523 right by number average-width characters on the display;
524 if it is pages then the view adjusts by number screen‐
525 fuls. If number is negative then characters farther to
526 the left become visible; if it is positive then charac‐
527 ters farther to the right become visible.
528
530 Tk automatically creates class bindings for spinboxes that give them
531 the following default behavior. In the descriptions below, “word”
532 refers to a contiguous group of letters, digits, or “_” characters, or
533 any single character other than these.
534 [1] Clicking mouse button 1 positions the insertion cursor just be‐
536 fore the character underneath the mouse cursor, sets the input
537 focus to this widget, and clears any selection in the widget.
538 Dragging with mouse button 1 strokes out a selection between the
539 insertion cursor and the character under the mouse.
540 [2] Double-clicking with mouse button 1 selects the word under the
542 mouse and positions the insertion cursor at the beginning of the
543 word. Dragging after a double click will stroke out a selection
544 consisting of whole words.
545 [3] Triple-clicking with mouse button 1 selects all of the text in
547 the spinbox and positions the insertion cursor before the first
548 character.
549 [4] The ends of the selection can be adjusted by dragging with mouse
551 button 1 while the Shift key is down; this will adjust the end
552 of the selection that was nearest to the mouse cursor when but‐
553 ton 1 was pressed. If the button is double-clicked before drag‐
554 ging then the selection will be adjusted in units of whole
555 words.
556 [5] Clicking mouse button 1 with the Control key down will position
558 the insertion cursor in the spinbox without affecting the selec‐
559 tion.
560 [6] If any normal printing characters are typed in a spinbox, they
562 are inserted at the point of the insertion cursor.
563 [7] The view in the spinbox can be adjusted by dragging with the
565 middle mouse button (button 2, or button 3 in TkAqua). If the
566 middle mouse button is clicked without moving the mouse, the se‐
567 lection is copied into the spinbox at the position of the mouse
568 cursor.
569 [8] If the mouse is dragged out of the spinbox on the left or right
571 sides while button 1 is pressed, the spinbox will automatically
572 scroll to make more text visible (if there is more text off-
573 screen on the side where the mouse left the window).
574 [9] The Left and Right keys move the insertion cursor one character
576 to the left or right; they also clear any selection in the
577 spinbox and set the selection anchor. If Left or Right is typed
578 with the Shift key down, then the insertion cursor moves and the
579 selection is extended to include the new character. Control-
580 Left and Control-Right move the insertion cursor by words, and
581 Control-Shift-Left and Control-Shift-Right move the insertion
582 cursor by words and also extend the selection. Control-b and
583 Control-f behave the same as Left and Right, respectively.
584 Meta-b and Meta-f behave the same as Control-Left and Control-
585 Right, respectively.
586 [10] The Home key, or Control-a, will move the insertion cursor to
588 the beginning of the spinbox and clear any selection in the
589 spinbox. Shift-Home moves the insertion cursor to the beginning
590 of the spinbox and also extends the selection to that point.
591 [11] The End key, or Control-e, will move the insertion cursor to the
593 end of the spinbox and clear any selection in the spinbox.
594 Shift-End moves the cursor to the end and extends the selection
595 to that point.
596 [12] The Select key and Control-Space set the selection anchor to the
598 position of the insertion cursor. They do not affect the cur‐
599 rent selection. Shift-Select and Control-Shift-Space adjust the
600 selection to the current position of the insertion cursor, se‐
601 lecting from the anchor to the insertion cursor if there was not
602 any selection previously.
603 [13] Control-/ selects all the text in the spinbox.
605 [14] Control-\ clears any selection in the spinbox.
607 [15] The F16 key (labelled Copy on many Sun workstations) or Meta-w
609 copies the selection in the widget to the clipboard, if there is
610 a selection.
611 [16] The F20 key (labelled Cut on many Sun workstations) or Control-w
613 copies the selection in the widget to the clipboard and deletes
614 the selection. If there is no selection in the widget then
615 these keys have no effect.
616 [17] The F18 key (labelled Paste on many Sun workstations) or Con‐
618 trol-y inserts the contents of the clipboard at the position of
619 the insertion cursor.
620 [18] The Delete key deletes the selection, if there is one in the
622 spinbox. If there is no selection, it deletes the character to
623 the right of the insertion cursor.
624 [19] The BackSpace key and Control-h delete the selection, if there
626 is one in the spinbox. If there is no selection, it deletes the
627 character to the left of the insertion cursor.
628 [20] Control-d deletes the character to the right of the insertion
630 cursor.
631 [21] Meta-d deletes the word to the right of the insertion cursor.
633 [22] Control-k deletes all the characters to the right of the inser‐
635 tion cursor.
636 [23] Control-t reverses the order of the two characters to the right
638 of the insertion cursor.
639 If the spinbox is disabled using the -state option, then the spinbox's
641 view can still be adjusted and text in the spinbox can still be se‐
642 lected, but no insertion cursor will be displayed and no text modifica‐
643 tions will take place.
644 The behavior of spinboxes can be changed by defining new bindings for
646 individual widgets or by redefining the class bindings.
647
649 ttk::spinbox(n)
650
652 spinbox, entry, widget
653Tk 8.4 spinbox(n)