1spinbox(n) Tk Built-In Commands spinbox(n)
2______________________________________________________________________________
6
8 spinbox - Create and manipulate spinbox 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 [-buttonbackground buttonBackground] The background color to be used
28 for the spin buttons. [-buttoncursor buttonCursor] The cursor to be
29 used when over the spin buttons. If this is empty (the default), a
30 default cursor will be used. [-buttondownrelief buttonDownRelief] The
31 relief to be used for the upper spin button. [-buttonuprelief but‐
32 tonUpRelief] The relief to be used for the lower spin button. [-com‐
33 mand command] Specifies a Tcl command to invoke whenever a spinbutton
34 is invoked. The command recognizes several percent substitutions: %W
35 for the widget path, %s for the current value of the widget, and %d for
36 the direction of the button pressed (up or down). [-disabledback‐
37 ground disabledBackground] Specifies the background color to use when
38 the spinbox is disabled. If this option is the empty string, the nor‐
39 mal background color is used. [-disabledforeground disabledForeground]
40 Specifies the foreground color to use when the spinbox is disabled. If
41 this option is the empty string, the normal foreground color is used.
42 [-format format] Specifies an alternate format to use when setting the
43 string value when using the -from and -to range. This must be a format
44 specifier of the form %<pad>.<pad>f, as it will format a floating-point
45 number. [-from from] A floating-point value corresponding to the low‐
46 est value for a spinbox, to be used in conjunction with -to and -incre‐
47 ment. When all are specified correctly, the spinbox will use these
48 values to control its contents. This value must be less than the -to
49 option. If -values is specified, it supercedes this option.
50 [-invalidcommand or -invcmd invalidCommand] Specifies a script to eval
51 when validateCommand returns 0. Setting it to an empty string disables
52 this feature (the default). The best use of this option is to set it
53 to bell. See Validation below for more information. [-incre‐
54 ment increment] A floating-point value specifying the increment. When
55 used with -from and -to, the value in the widget will be adjusted by
56 -increment when a spin button is pressed (up adds the value, down sub‐
57 tracts the value). [-readonlybackground readonlyBackground] Specifies
58 the background color to use when the spinbox is readonly. If this
59 option is the empty string, the normal background color is used.
60 [-state state] Specifies one of three states for the spinbox: normal,
61 disabled, or readonly. If the spinbox is readonly, then the value may
62 not be changed using widget commands and no insertion cursor will be
63 displayed, even if the input focus is in the widget; the contents of
64 the widget may still be selected. If the spinbox is disabled, the
65 value may not be changed, no insertion cursor will be displayed, the
66 contents will not be selectable, and the spinbox may be displayed in a
67 different color, depending on the values of the -disabledforeground and
68 -disabledbackground options. [-to to] A floating-point value corre‐
69 sponding to the highest value for the spinbox, to be used in conjunc‐
70 tion with -from and -increment. When all are specified correctly, the
71 spinbox will use these values to control its contents. This value must
72 be greater than the -from option. If -values is specified, it
73 supercedes this option. [-validate validate] Specifies the mode in
74 which validation should operate: none, focus, focusin, focusout, key,
75 or all. It defaults to none. When you want validation, you must
76 explicitly state which mode you wish to use. See Validation below for
77 more. [-validatecommand or -vcmd validateCommand] Specifies a script
78 to evaluate when you want to validate the input in the widget. Setting
79 it to an empty string disables this feature (the default). Validation
80 occurs according to the value of -validate. This command must return a
81 valid Tcl boolean value. If it returns 0 (or the valid Tcl boolean
82 equivalent) then the value of the widget will not change and the
83 invalidCommand will be evaluated if it is set. If it returns 1, then
84 value will be changed. See Validation below for more information.
85 [-values values] Must be a proper list value. If specified, the spin‐
86 box will use these values as to control its contents, starting with the
87 first value. This option has precedence over the -from and -to range.
88 [-width width] Specifies an integer value indicating the desired width
89 of the spinbox window, in average-size characters of the widget's font.
90 If the value is less than or equal to zero, the widget picks a size
91 just large enough to hold its current text. [-wrap wrap] Must be a
92 proper boolean value. If on, the spinbox will wrap around the values
93 of data in the widget.
94_________________________________________________________________
95
97 The spinbox command creates a new window (given by the pathName argu‐
98 ment) and makes it into a spinbox widget. Additional options,
99 described above, may be specified on the command line or in the option
100 database to configure aspects of the spinbox such as its colors, font,
101 and relief. The spinbox command returns its pathName argument. At the
102 time this command is invoked, there must not exist a window named path‐
103 Name, but pathName's parent must exist.
104 A spinbox is an extended entry widget that allows he user to move, or
106 spin, through a fixed set of ascending or descending values such as
107 times or dates in addition to editing the value as in an entry. When
108 first created, a spinbox's string is empty. A portion of the spinbox
109 may be selected as described below. If a spinbox is exporting its
110 selection (see the exportSelection option), then it will observe the
111 standard protocols for handling the selection; spinbox selections are
112 available as type STRING. Spinboxes also observe the standard Tk rules
113 for dealing with the input focus. When a spinbox has the input focus
114 it displays an insertion cursor to indicate where new characters will
115 be inserted.
116 Spinboxes are capable of displaying strings that are too long to fit
118 entirely within the widget's window. In this case, only a portion of
119 the string will be displayed; commands described below may be used to
120 change the view in the window. Spinboxes use the standard xScrollCom‐
121 mand mechanism for interacting with scrollbars (see the description of
122 the xScrollCommand option for details). They also support scanning, as
123 described below.
124
126 Validation works by setting the validateCommand option to a script
127 which will be evaluated according to the validate option as follows:
128 none Default. This means no validation will occur.
130 focus validateCommand will be called when the spinbox receives or
132 loses focus.
133 focusin validateCommand will be called when the spinbox receives
135 focus.
136 focusout validateCommand will be called when the spinbox loses focus.
138 key validateCommand will be called when the spinbox is edited.
140 all validateCommand will be called for all above conditions.
142 It is possible to perform percent substitutions on the validateCommand
144 and invalidCommand, just as you would in a bind script. The following
145 substitutions are recognized:
146 %d Type of action: 1 for insert, 0 for delete, or -1 for focus,
148 forced or textvariable validation.
149 %i Index of char string to be inserted/deleted, if any, otherwise -1.
151 %P The value of the spinbox should edition occur. If you are config‐
153 uring the spinbox widget to have a new textvariable, this will be
154 the value of that textvariable.
155 %s The current value of spinbox before edition.
157 %S The text string being inserted/deleted, if any. Otherwise it is
159 an empty string.
160 %v The type of validation currently set.
162 %V The type of validation that triggered the callback (key, focusin,
164 focusout, forced).
165 %W The name of the spinbox widget.
167 In general, the textVariable and validateCommand can be dangerous to
169 mix. Any problems have been overcome so that using the validateCommand
170 will not interfere with the traditional behavior of the spinbox widget.
171 Using the textVariable for read-only purposes will never cause prob‐
172 lems. The danger comes when you try set the textVariable to something
173 that the validateCommand would not accept, which causes validate to
174 become none (the invalidCommand will not be triggered). The same hap‐
175 pens when an error occurs evaluating the validateCommand.
176 Primarily, an error will occur when the validateCommand or invalidCom‐
178 mand encounters an error in its script while evaluating or validateCom‐
179 mand does not return a valid Tcl boolean value. The validate option
180 will also set itself to none when you edit the spinbox widget from
181 within either the validateCommand or the invalidCommand. Such editions
182 will override the one that was being validated. If you wish to edit
183 the value of the widget during validation and still have the validate
184 option set, you should include the command
185 %W config -validate %v
186 in the validateCommand or invalidCommand (whichever one you were edit‐
187 ing the spinbox widget from). It is also recommended to not set an
188 associated textVariable during validation, as that can cause the spin‐
189 box widget to become out of sync with the textVariable.
190
192 The spinbox command creates a new Tcl command whose name is pathName.
193 This command may be used to invoke various operations on the widget.
194 It has the following general form:
195 pathName option ?arg arg ...?
196 Option and the args determine the exact behavior of the command.
197 INDICES
199 Many of the widget commands for spinboxes take one or more indices as
200 arguments. An index specifies a particular character in the spinbox's
201 string, in any of the following ways:
202 number Specifies the character as a numerical index, where 0 cor‐
204 responds to the first character in the string.
205 anchor Indicates the anchor point for the selection, which is set
207 with the select from and select adjust widget commands.
208 end Indicates the character just after the last one in the
210 spinbox's string. This is equivalent to specifying a
211 numerical index equal to the length of the spinbox's
212 string.
213 insert Indicates the character adjacent to and immediately follow‐
215 ing the insertion cursor.
216 sel.first Indicates the first character in the selection. It is an
218 error to use this form if the selection is not in the spin‐
219 box window.
220 sel.last Indicates the character just after the last one in the
222 selection. It is an error to use this form if the selec‐
223 tion is not in the spinbox window.
224 @number In this form, number is treated as an x-coordinate in the
226 spinbox's window; the character spanning that x-coordinate
227 is used. For example, “@0” indicates the left-most charac‐
228 ter in the window.
229 Abbreviations may be used for any of the forms above, e.g. “e” or
231 “sel.f”. In general, out-of-range indices are automatically rounded to
232 the nearest legal value.
233 SUBCOMMANDS
235 The following commands are possible for spinbox widgets:
236 pathName bbox index
238 Returns a list of four numbers describing the bounding box of
239 the character given by index. The first two elements of the
240 list give the x and y coordinates of the upper-left corner of
241 the screen area covered by the character (in pixels relative to
242 the widget) and the last two elements give the width and height
243 of the character, in pixels. The bounding box may refer to a
244 region outside the visible area of the window.
245 pathName cget option
247 Returns the current value of the configuration option given by
248 option. Option may have any of the values accepted by the spin‐
249 box command.
250 pathName configure ?option? ?value option value ...?
252 Query or modify the configuration options of the widget. If no
253 option is specified, returns a list describing all of the avail‐
254 able options for pathName (see Tk_ConfigureInfo for information
255 on the format of this list). If option is specified with no
256 value, then the command returns a list describing the one named
257 option (this list will be identical to the corresponding sublist
258 of the value returned if no option is specified). If one or
259 more option-value pairs are specified, then the command modifies
260 the given widget option(s) to have the given value(s); in this
261 case the command returns an empty string. Option may have any
262 of the values accepted by the spinbox command.
263 pathName delete first ?last?
265 Delete one or more elements of the spinbox. First is the index
266 of the first character to delete, and last is the index of the
267 character just after the last one to delete. If last is not
268 specified it defaults to first+1, i.e. a single character is
269 deleted. This command returns an empty string.
270 pathName get
272 Returns the spinbox's string.
273 pathName icursor index
275 Arrange for the insertion cursor to be displayed just before the
276 character given by index. Returns an empty string.
277 pathName identify x y
279 Returns the name of the window element corresponding to coordi‐
280 nates x and y in the spinbox. Return value is one of: none,
281 buttondown, buttonup, entry.
282 pathName index index
284 Returns the numerical index corresponding to index.
285 pathName insert index string
287 Insert the characters of string just before the character indi‐
288 cated by index. Returns an empty string.
289 pathName invoke element
291 Causes the specified element, either buttondown or buttonup, to
292 be invoked, triggering the action associated with it.
293 pathName scan option args
295 This command is used to implement scanning on spinboxes. It has
296 two forms, depending on option:
297 pathName scan mark x
299 Records x and the current view in the spinbox window;
300 used in conjunction with later scan dragto commands.
301 Typically this command is associated with a mouse button
302 press in the widget. It returns an empty string.
303 pathName scan dragto x
305 This command computes the difference between its x argu‐
306 ment and the x argument to the last scan mark command for
307 the widget. It then adjusts the view left or right by 10
308 times the difference in x-coordinates. This command is
309 typically associated with mouse motion events in the wid‐
310 get, to produce the effect of dragging the spinbox at
311 high speed through the window. The return value is an
312 empty string.
313 pathName selection option arg
315 This command is used to adjust the selection within a spinbox.
316 It has several forms, depending on option:
317 pathName selection adjust index
319 Locate the end of the selection nearest to the character
320 given by index, and adjust that end of the selection to
321 be at index (i.e. including but not going beyond index).
322 The other end of the selection is made the anchor point
323 for future select to commands. If the selection is not
324 currently in the spinbox, then a new selection is created
325 to include the characters between index and the most
326 recent selection anchor point, inclusive. Returns an
327 empty string.
328 pathName selection clear
330 Clear the selection if it is currently in this widget.
331 If the selection is not in this widget then the command
332 has no effect. Returns an empty string.
333 pathName selection element ?element?
335 Sets or gets the currently selected element. If a spin‐
336 button element is specified, it will be displayed
337 depressed.
338 pathName selection from index
340 Set the selection anchor point to just before the charac‐
341 ter given by index. Does not change the selection.
342 Returns an empty string.
343 pathName selection present
345 Returns 1 if there is are characters selected in the
346 spinbox, 0 if nothing is selected.
347 pathName selection range start end
349 Sets the selection to include the characters starting
350 with the one indexed by start and ending with the one
351 just before end. If end refers to the same character as
352 start or an earlier one, then the spinbox's selection is
353 cleared.
354 pathName selection to index
356 If index is before the anchor point, set the selection to
357 the characters from index up to but not including the
358 anchor point. If index is the same as the anchor point,
359 do nothing. If index is after the anchor point, set the
360 selection to the characters from the anchor point up to
361 but not including index. The anchor point is determined
362 by the most recent select from or select adjust command
363 in this widget. If the selection is not in this widget
364 then a new selection is created using the most recent
365 anchor point specified for the widget. Returns an empty
366 string.
367 pathName set ?string?
369 If string is specified, the spinbox will try and set it to this
370 value, otherwise it just returns the spinbox's string. If vali‐
371 dation is on, it will occur when setting the string.
372 pathName validate
374 This command is used to force an evaluation of the validateCom‐
375 mand independent of the conditions specified by the validate
376 option. This is done by temporarily setting the validate option
377 to all. It returns 0 or 1.
378 pathName xview args
380 This command is used to query and change the horizontal position
381 of the text in the widget's window. It can take any of the fol‐
382 lowing forms:
383 pathName xview
385 Returns a list containing two elements. Each element is
386 a real fraction between 0 and 1; together they describe
387 the horizontal span that is visible in the window. For
388 example, if the first element is .2 and the second ele‐
389 ment is .6, 20% of the spinbox's text is off-screen to
390 the left, the middle 40% is visible in the window, and
391 40% of the text is off-screen to the right. These are
392 the same values passed to scrollbars via the -xscrollcom‐
393 mand option.
394 pathName xview index
396 Adjusts the view in the window so that the character
397 given by index is displayed at the left edge of the win‐
398 dow.
399 pathName xview moveto fraction
401 Adjusts the view in the window so that the character
402 fraction of the way through the text appears at the left
403 edge of the window. Fraction must be a fraction between
404 0 and 1.
405 pathName xview scroll number what
407 This command shifts the view in the window left or right
408 according to number and what. Number must be an integer.
409 What must be either units or pages or an abbreviation of
410 one of these. If what is units, the view adjusts left or
411 right by number average-width characters on the display;
412 if it is pages then the view adjusts by number screen‐
413 fuls. If number is negative then characters farther to
414 the left become visible; if it is positive then charac‐
415 ters farther to the right become visible.
416
419 Tk automatically creates class bindings for spinboxes that give them
420 the following default behavior. In the descriptions below, “word”
421 refers to a contiguous group of letters, digits, or “_” characters, or
422 any single character other than these.
423 [1] Clicking mouse button 1 positions the insertion cursor just
425 before the character underneath the mouse cursor, sets the input
426 focus to this widget, and clears any selection in the widget.
427 Dragging with mouse button 1 strokes out a selection between the
428 insertion cursor and the character under the mouse.
429 [2] Double-clicking with mouse button 1 selects the word under the
431 mouse and positions the insertion cursor at the beginning of the
432 word. Dragging after a double click will stroke out a selection
433 consisting of whole words.
434 [3] Triple-clicking with mouse button 1 selects all of the text in
436 the spinbox and positions the insertion cursor before the first
437 character.
438 [4] The ends of the selection can be adjusted by dragging with mouse
440 button 1 while the Shift key is down; this will adjust the end
441 of the selection that was nearest to the mouse cursor when but‐
442 ton 1 was pressed. If the button is double-clicked before drag‐
443 ging then the selection will be adjusted in units of whole
444 words.
445 [5] Clicking mouse button 1 with the Control key down will position
447 the insertion cursor in the spinbox without affecting the selec‐
448 tion.
449 [6] If any normal printing characters are typed in a spinbox, they
451 are inserted at the point of the insertion cursor.
452 [7] The view in the spinbox can be adjusted by dragging with mouse
454 button 2. If mouse button 2 is clicked without moving the
455 mouse, the selection is copied into the spinbox at the position
456 of the mouse cursor.
457 [8] If the mouse is dragged out of the spinbox on the left or right
459 sides while button 1 is pressed, the spinbox will automatically
460 scroll to make more text visible (if there is more text off-
461 screen on the side where the mouse left the window).
462 [9] The Left and Right keys move the insertion cursor one character
464 to the left or right; they also clear any selection in the
465 spinbox and set the selection anchor. If Left or Right is typed
466 with the Shift key down, then the insertion cursor moves and the
467 selection is extended to include the new character. Control-
468 Left and Control-Right move the insertion cursor by words, and
469 Control-Shift-Left and Control-Shift-Right move the insertion
470 cursor by words and also extend the selection. Control-b and
471 Control-f behave the same as Left and Right, respectively.
472 Meta-b and Meta-f behave the same as Control-Left and Control-
473 Right, respectively.
474 [10] The Home key, or Control-a, will move the insertion cursor to
476 the beginning of the spinbox and clear any selection in the
477 spinbox. Shift-Home moves the insertion cursor to the beginning
478 of the spinbox and also extends the selection to that point.
479 [11] The End key, or Control-e, will move the insertion cursor to the
481 end of the spinbox and clear any selection in the spinbox.
482 Shift-End moves the cursor to the end and extends the selection
483 to that point.
484 [12] The Select key and Control-Space set the selection anchor to the
486 position of the insertion cursor. They do not affect the cur‐
487 rent selection. Shift-Select and Control-Shift-Space adjust the
488 selection to the current position of the insertion cursor,
489 selecting from the anchor to the insertion cursor if there was
490 not any selection previously.
491 [13] Control-/ selects all the text in the spinbox.
493 [14] Control-\ clears any selection in the spinbox.
495 [15] The F16 key (labelled Copy on many Sun workstations) or Meta-w
497 copies the selection in the widget to the clipboard, if there is
498 a selection.
499 [16] The F20 key (labelled Cut on many Sun workstations) or Control-w
501 copies the selection in the widget to the clipboard and deletes
502 the selection. If there is no selection in the widget then
503 these keys have no effect.
504 [17] The F18 key (labelled Paste on many Sun workstations) or Con‐
506 trol-y inserts the contents of the clipboard at the position of
507 the insertion cursor.
508 [18] The Delete key deletes the selection, if there is one in the
510 spinbox. If there is no selection, it deletes the character to
511 the right of the insertion cursor.
512 [19] The BackSpace key and Control-h delete the selection, if there
514 is one in the spinbox. If there is no selection, it deletes the
515 character to the left of the insertion cursor.
516 [20] Control-d deletes the character to the right of the insertion
518 cursor.
519 [21] Meta-d deletes the word to the right of the insertion cursor.
521 [22] Control-k deletes all the characters to the right of the inser‐
523 tion cursor.
524 [23] Control-t reverses the order of the two characters to the right
526 of the insertion cursor.
527 If the spinbox is disabled using the -state option, then the spinbox's
529 view can still be adjusted and text in the spinbox can still be
530 selected, but no insertion cursor will be displayed and no text modifi‐
531 cations will take place.
532 The behavior of spinboxes can be changed by defining new bindings for
534 individual widgets or by redefining the class bindings.
535
538 spinbox, entry, widget
539Tk 8.4 spinbox(n)