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
57 invoked. The command recognizes several percent substitutions:
58 %W for the widget path, %s for the current value of the widget,
59 and %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
95 option.
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
103 default). The best use of this option is to set it to bell.
104 See 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
112 -increment when a spin button is pressed (up adds the value,
113 down 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
146 supersedes 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,
153 focus, focusin, focusout, key, or all. It defaults to none.
154 When you want validation, you must explicitly state which mode
155 you 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
162 input in the widget. Setting it to an empty string disables
163 this feature (the default). Validation occurs according to the
164 value of -validate. This command must return a valid Tcl bool‐
165 ean value. If it returns 0 (or the valid Tcl boolean equiva‐
166 lent) then the value of the widget will not change and the
167 -invalidcommand will be evaluated if it is set. If it returns
168 1, then value will be changed. See VALIDATION below for more
169 information.
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,
199 described 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
210 selection (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
325 numerical index equal to the length of the spinbox's
326 string.
327 insert Indicates the character adjacent to and immediately follow‐
329 ing the insertion cursor.
330 sel.first Indicates the first character in the selection. It is an
332 error to use this form if the selection is not in the spin‐
333 box window.
334 sel.last Indicates the character just after the last one in the
336 selection. It is an error to use this form if the selec‐
337 tion is not in the spinbox window.
338 @number In this form, number is treated as an x-coordinate in the
340 spinbox's window; the character spanning that x-coordinate
341 is used. For example, “@0” indicates the left-most charac‐
342 ter in the window.
343 Abbreviations may be used for any of the forms above, e.g. “e” or
345 “sel.f”. In general, out-of-range indices are automatically rounded to
346 the nearest legal value.
347 SUBCOMMANDS
349 The following commands are possible for spinbox widgets:
350 pathName bbox index
352 Returns a list of four numbers describing the bounding box of
353 the character given by index. The first two elements of the
354 list give the x and y coordinates of the upper-left corner of
355 the screen area covered by the character (in pixels relative to
356 the widget) and the last two elements give the width and height
357 of the character, in pixels. The bounding box may refer to a
358 region outside the visible area of the window.
359 pathName cget option
361 Returns the current value of the configuration option given by
362 option. Option may have any of the values accepted by the spin‐
363 box command.
364 pathName configure ?option? ?value option value ...?
366 Query or modify the configuration options of the widget. If no
367 option is specified, returns a list describing all of the avail‐
368 able options for pathName (see Tk_ConfigureInfo for information
369 on the format of this list). If option is specified with no
370 value, then the command returns a list describing the one named
371 option (this list will be identical to the corresponding sublist
372 of the value returned if no option is specified). If one or
373 more option-value pairs are specified, then the command modifies
374 the given widget option(s) to have the given value(s); in this
375 case the command returns an empty string. Option may have any
376 of the values accepted by the spinbox command.
377 pathName delete first ?last?
379 Delete one or more elements of the spinbox. First is the index
380 of the first character to delete, and last is the index of the
381 character just after the last one to delete. If last is not
382 specified it defaults to first+1, i.e. a single character is
383 deleted. This command returns an empty string.
384 pathName get
386 Returns the spinbox's string.
387 pathName icursor index
389 Arrange for the insertion cursor to be displayed just before the
390 character given by index. Returns an empty string.
391 pathName identify x y
393 Returns the name of the window element corresponding to coordi‐
394 nates x and y in the spinbox. Return value is one of: none,
395 buttondown, buttonup, entry.
396 pathName index index
398 Returns the numerical index corresponding to index.
399 pathName insert index string
401 Insert the characters of string just before the character indi‐
402 cated by index. Returns an empty string.
403 pathName invoke element
405 Causes the specified element, either buttondown or buttonup, to
406 be invoked, triggering the action associated with it.
407 pathName scan option args
409 This command is used to implement scanning on spinboxes. It has
410 two forms, depending on option:
411 pathName scan mark x
413 Records x and the current view in the spinbox window;
414 used in conjunction with later scan dragto commands.
415 Typically this command is associated with a mouse button
416 press in the widget. It returns an empty string.
417 pathName scan dragto x
419 This command computes the difference between its x argu‐
420 ment and the x argument to the last scan mark command for
421 the widget. It then adjusts the view left or right by 10
422 times the difference in x-coordinates. This command is
423 typically associated with mouse motion events in the wid‐
424 get, to produce the effect of dragging the spinbox at
425 high speed through the window. The return value is an
426 empty string.
427 pathName selection option arg
429 This command is used to adjust the selection within a spinbox.
430 It has several forms, depending on option:
431 pathName selection adjust index
433 Locate the end of the selection nearest to the character
434 given by index, and adjust that end of the selection to
435 be at index (i.e. including but not going beyond index).
436 The other end of the selection is made the anchor point
437 for future select to commands. If the selection is not
438 currently in the spinbox, then a new selection is created
439 to include the characters between index and the most
440 recent selection anchor point, inclusive. Returns an
441 empty string.
442 pathName selection clear
444 Clear the selection if it is currently in this widget.
445 If the selection is not in this widget then the command
446 has no effect. Returns an empty string.
447 pathName selection element ?element?
449 Sets or gets the currently selected element. If a spin‐
450 button element is specified, it will be displayed
451 depressed.
452 pathName selection from index
454 Set the selection anchor point to just before the charac‐
455 ter given by index. Does not change the selection.
456 Returns an empty string.
457 pathName selection present
459 Returns 1 if there is are characters selected in the
460 spinbox, 0 if nothing is selected.
461 pathName selection range start end
463 Sets the selection to include the characters starting
464 with the one indexed by start and ending with the one
465 just before end. If end refers to the same character as
466 start or an earlier one, then the spinbox's selection is
467 cleared.
468 pathName selection to index
470 If index is before the anchor point, set the selection to
471 the characters from index up to but not including the
472 anchor point. If index is the same as the anchor point,
473 do nothing. If index is after the anchor point, set the
474 selection to the characters from the anchor point up to
475 but not including index. The anchor point is determined
476 by the most recent select from or select adjust command
477 in this widget. If the selection is not in this widget
478 then a new selection is created using the most recent
479 anchor point specified for the widget. Returns an empty
480 string.
481 pathName set ?string?
483 If string is specified, the spinbox will try and set it to this
484 value, otherwise it just returns the spinbox's string. If vali‐
485 dation is on, it will occur when setting the string.
486 pathName validate
488 This command is used to force an evaluation of the -validatecom‐
489 mand independent of the conditions specified by the -validate
490 option. This is done by temporarily setting the -validate
491 option to all. It returns 0 or 1.
492 pathName xview args
494 This command is used to query and change the horizontal position
495 of the text in the widget's window. It can take any of the fol‐
496 lowing forms:
497 pathName xview
499 Returns a list containing two elements. Each element is
500 a real fraction between 0 and 1; together they describe
501 the horizontal span that is visible in the window. For
502 example, if the first element is .2 and the second ele‐
503 ment is .6, 20% of the spinbox's text is off-screen to
504 the left, the middle 40% is visible in the window, and
505 40% of the text is off-screen to the right. These are
506 the same values passed to scrollbars via the -xscrollcom‐
507 mand option.
508 pathName xview index
510 Adjusts the view in the window so that the character
511 given by index is displayed at the left edge of the win‐
512 dow.
513 pathName xview moveto fraction
515 Adjusts the view in the window so that the character
516 fraction of the way through the text appears at the left
517 edge of the window. Fraction must be a fraction between
518 0 and 1.
519 pathName xview scroll number what
521 This command shifts the view in the window left or right
522 according to number and what. Number must be an integer.
523 What must be either units or pages or an abbreviation of
524 one of these. If what is units, the view adjusts left or
525 right by number average-width characters on the display;
526 if it is pages then the view adjusts by number screen‐
527 fuls. If number is negative then characters farther to
528 the left become visible; if it is positive then charac‐
529 ters farther to the right become visible.
530
532 Tk automatically creates class bindings for spinboxes that give them
533 the following default behavior. In the descriptions below, “word”
534 refers to a contiguous group of letters, digits, or “_” characters, or
535 any single character other than these.
536 [1] Clicking mouse button 1 positions the insertion cursor just
538 before the character underneath the mouse cursor, sets the input
539 focus to this widget, and clears any selection in the widget.
540 Dragging with mouse button 1 strokes out a selection between the
541 insertion cursor and the character under the mouse.
542 [2] Double-clicking with mouse button 1 selects the word under the
544 mouse and positions the insertion cursor at the beginning of the
545 word. Dragging after a double click will stroke out a selection
546 consisting of whole words.
547 [3] Triple-clicking with mouse button 1 selects all of the text in
549 the spinbox and positions the insertion cursor before the first
550 character.
551 [4] The ends of the selection can be adjusted by dragging with mouse
553 button 1 while the Shift key is down; this will adjust the end
554 of the selection that was nearest to the mouse cursor when but‐
555 ton 1 was pressed. If the button is double-clicked before drag‐
556 ging then the selection will be adjusted in units of whole
557 words.
558 [5] Clicking mouse button 1 with the Control key down will position
560 the insertion cursor in the spinbox without affecting the selec‐
561 tion.
562 [6] If any normal printing characters are typed in a spinbox, they
564 are inserted at the point of the insertion cursor.
565 [7] The view in the spinbox can be adjusted by dragging with mouse
567 button 2. If mouse button 2 is clicked without moving the
568 mouse, the selection is copied into the spinbox at the position
569 of the mouse cursor.
570 [8] If the mouse is dragged out of the spinbox on the left or right
572 sides while button 1 is pressed, the spinbox will automatically
573 scroll to make more text visible (if there is more text off-
574 screen on the side where the mouse left the window).
575 [9] The Left and Right keys move the insertion cursor one character
577 to the left or right; they also clear any selection in the
578 spinbox and set the selection anchor. If Left or Right is typed
579 with the Shift key down, then the insertion cursor moves and the
580 selection is extended to include the new character. Control-
581 Left and Control-Right move the insertion cursor by words, and
582 Control-Shift-Left and Control-Shift-Right move the insertion
583 cursor by words and also extend the selection. Control-b and
584 Control-f behave the same as Left and Right, respectively.
585 Meta-b and Meta-f behave the same as Control-Left and Control-
586 Right, respectively.
587 [10] The Home key, or Control-a, will move the insertion cursor to
589 the beginning of the spinbox and clear any selection in the
590 spinbox. Shift-Home moves the insertion cursor to the beginning
591 of the spinbox and also extends the selection to that point.
592 [11] The End key, or Control-e, will move the insertion cursor to the
594 end of the spinbox and clear any selection in the spinbox.
595 Shift-End moves the cursor to the end and extends the selection
596 to that point.
597 [12] The Select key and Control-Space set the selection anchor to the
599 position of the insertion cursor. They do not affect the cur‐
600 rent selection. Shift-Select and Control-Shift-Space adjust the
601 selection to the current position of the insertion cursor,
602 selecting from the anchor to the insertion cursor if there was
603 not any selection previously.
604 [13] Control-/ selects all the text in the spinbox.
606 [14] Control-\ clears any selection in the spinbox.
608 [15] The F16 key (labelled Copy on many Sun workstations) or Meta-w
610 copies the selection in the widget to the clipboard, if there is
611 a selection.
612 [16] The F20 key (labelled Cut on many Sun workstations) or Control-w
614 copies the selection in the widget to the clipboard and deletes
615 the selection. If there is no selection in the widget then
616 these keys have no effect.
617 [17] The F18 key (labelled Paste on many Sun workstations) or Con‐
619 trol-y inserts the contents of the clipboard at the position of
620 the insertion cursor.
621 [18] The Delete key deletes the selection, if there is one in the
623 spinbox. If there is no selection, it deletes the character to
624 the right of the insertion cursor.
625 [19] The BackSpace key and Control-h delete the selection, if there
627 is one in the spinbox. If there is no selection, it deletes the
628 character to the left of the insertion cursor.
629 [20] Control-d deletes the character to the right of the insertion
631 cursor.
632 [21] Meta-d deletes the word to the right of the insertion cursor.
634 [22] Control-k deletes all the characters to the right of the inser‐
636 tion cursor.
637 [23] Control-t reverses the order of the two characters to the right
639 of the insertion cursor.
640 If the spinbox is disabled using the -state option, then the spinbox's
642 view can still be adjusted and text in the spinbox can still be
643 selected, but no insertion cursor will be displayed and no text modifi‐
644 cations will take place.
645 The behavior of spinboxes can be changed by defining new bindings for
647 individual widgets or by redefining the class bindings.
648
650 ttk::spinbox(n)
651
653 spinbox, entry, widget
654Tk 8.4 spinbox(n)