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
98 The spinbox command creates a new window (given by the pathName argu‐
99 ment) and makes it into a spinbox widget. Additional options,
100 described above, may be specified on the command line or in the option
101 database to configure aspects of the spinbox such as its colors, font,
102 and relief. The spinbox command returns its pathName argument. At the
103 time this command is invoked, there must not exist a window named path‐
104 Name, but pathName's parent must exist.
105 A spinbox is an extended entry widget that allows he user to move, or
107 spin, through a fixed set of ascending or descending values such as
108 times or dates in addition to editing the value as in an entry. When
109 first created, a spinbox's string is empty. A portion of the spinbox
110 may be selected as described below. If a spinbox is exporting its
111 selection (see the exportSelection option), then it will observe the
112 standard protocols for handling the selection; spinbox selections are
113 available as type STRING. Spinboxes also observe the standard Tk rules
114 for dealing with the input focus. When a spinbox has the input focus
115 it displays an insertion cursor to indicate where new characters will
116 be inserted.
117 Spinboxes are capable of displaying strings that are too long to fit
119 entirely within the widget's window. In this case, only a portion of
120 the string will be displayed; commands described below may be used to
121 change the view in the window. Spinboxes use the standard xScrollCom‐
122 mand mechanism for interacting with scrollbars (see the description of
123 the xScrollCommand option for details). They also support scanning, as
124 described below.
125
128 Validation works by setting the validateCommand option to a script
129 which will be evaluated according to the validate option as follows:
130 none Default. This means no validation will occur.
132 focus validateCommand will be called when the spinbox receives or
134 loses focus.
135 focusin validateCommand will be called when the spinbox receives
137 focus.
138 focusout validateCommand will be called when the spinbox loses focus.
140 key validateCommand will be called when the spinbox is edited.
142 all validateCommand will be called for all above conditions.
144 It is possible to perform percent substitutions on the validateCommand
146 and invalidCommand, just as you would in a bind script. The following
147 substitutions are recognized:
148 %d Type of action: 1 for insert, 0 for delete, or -1 for focus,
150 forced or textvariable validation.
151 %i Index of char string to be inserted/deleted, if any, otherwise -1.
153 %P The value of the spinbox should edition occur. If you are config‐
155 uring the spinbox widget to have a new textvariable, this will be
156 the value of that textvariable.
157 %s The current value of spinbox before edition.
159 %S The text string being inserted/deleted, if any. Otherwise it is
161 an empty string.
162 %v The type of validation currently set.
164 %V The type of validation that triggered the callback (key, focusin,
166 focusout, forced).
167 %W The name of the spinbox widget.
169 In general, the textVariable and validateCommand can be dangerous to
171 mix. Any problems have been overcome so that using the validateCommand
172 will not interfere with the traditional behavior of the spinbox widget.
173 Using the textVariable for read-only purposes will never cause prob‐
174 lems. The danger comes when you try set the textVariable to something
175 that the validateCommand would not accept, which causes validate to
176 become none (the invalidCommand will not be triggered). The same hap‐
177 pens when an error occurs evaluating the validateCommand.
178 Primarily, an error will occur when the validateCommand or invalidCom‐
180 mand encounters an error in its script while evaluating or validateCom‐
181 mand does not return a valid Tcl boolean value. The validate option
182 will also set itself to none when you edit the spinbox widget from
183 within either the validateCommand or the invalidCommand. Such editions
184 will override the one that was being validated. If you wish to edit
185 the value of the widget during validation and still have the validate
186 option set, you should include the command
187 %W config -validate %v
188 in the validateCommand or invalidCommand (whichever one you were edit‐
189 ing the spinbox widget from). It is also recommended to not set an
190 associated textVariable during validation, as that can cause the spin‐
191 box widget to become out of sync with the textVariable.
192
195 The spinbox command creates a new Tcl command whose name is pathName.
196 This command may be used to invoke various operations on the widget.
197 It has the following general form:
198 pathName option ?arg arg ...?
199 Option and the args determine the exact behavior of the command.
200 Many of the widget commands for spinboxes take one or more indices as
202 arguments. An index specifies a particular character in the spinbox's
203 string, in any of the following ways:
204 number Specifies the character as a numerical index, where 0 cor‐
206 responds to the first character in the string.
207 anchor Indicates the anchor point for the selection, which is set
209 with the select from and select adjust widget commands.
210 end Indicates the character just after the last one in the
212 spinbox's string. This is equivalent to specifying a
213 numerical index equal to the length of the spinbox's
214 string.
215 insert Indicates the character adjacent to and immediately follow‐
217 ing the insertion cursor.
218 sel.first Indicates the first character in the selection. It is an
220 error to use this form if the selection isn't in the spin‐
221 box window.
222 sel.last Indicates the character just after the last one in the
224 selection. It is an error to use this form if the selec‐
225 tion isn't in the spinbox window.
226 @number In this form, number is treated as an x-coordinate in the
228 spinbox's window; the character spanning that x-coordinate
229 is used. For example, ``@0'' indicates the left-most char‐
230 acter in the window.
231 Abbreviations may be used for any of the forms above, e.g. ``e'' or
233 ``sel.f''. In general, out-of-range indices are automatically rounded
234 to the nearest legal value.
235 The following commands are possible for spinbox widgets:
237 pathName bbox index
239 Returns a list of four numbers describing the bounding box of
240 the character given by index. The first two elements of the
241 list give the x and y coordinates of the upper-left corner of
242 the screen area covered by the character (in pixels relative to
243 the widget) and the last two elements give the width and height
244 of the character, in pixels. The bounding box may refer to a
245 region outside the visible area of the window.
246 pathName cget option
248 Returns the current value of the configuration option given by
249 option. Option may have any of the values accepted by the spin‐
250 box command.
251 pathName configure ?option? ?value option value ...?
253 Query or modify the configuration options of the widget. If no
254 option is specified, returns a list describing all of the avail‐
255 able options for pathName (see Tk_ConfigureInfo for information
256 on the format of this list). If option is specified with no
257 value, then the command returns a list describing the one named
258 option (this list will be identical to the corresponding sublist
259 of the value returned if no option is specified). If one or
260 more option-value pairs are specified, then the command modifies
261 the given widget option(s) to have the given value(s); in this
262 case the command returns an empty string. Option may have any
263 of the values accepted by the spinbox command.
264 pathName delete first ?last?
266 Delete one or more elements of the spinbox. First is the index
267 of the first character to delete, and last is the index of the
268 character just after the last one to delete. If last isn't
269 specified it defaults to first+1, i.e. a single character is
270 deleted. This command returns an empty string.
271 pathName get
273 Returns the spinbox's string.
274 pathName icursor index
276 Arrange for the insertion cursor to be displayed just before the
277 character given by index. Returns an empty string.
278 pathName identify x y
280 Returns the name of the window element corresponding to coordi‐
281 nates x and y in the spinbox. Return value is one of: none,
282 buttondown, buttonup, entry.
283 pathName index index
285 Returns the numerical index corresponding to index.
286 pathName insert index string
288 Insert the characters of string just before the character indi‐
289 cated by index. Returns an empty string.
290 pathName invoke element
292 Causes the specified element, either buttondown or buttonup, to
293 be invoked, triggering the action associated with it.
294 pathName scan option args
296 This command is used to implement scanning on spinboxes. It has
297 two forms, depending on option:
298 pathName scan mark x
300 Records x and the current view in the spinbox window;
301 used in conjunction with later scan dragto commands.
302 Typically this command is associated with a mouse button
303 press in the widget. It returns an empty string.
304 pathName scan dragto x
306 This command computes the difference between its x argu‐
307 ment and the x argument to the last scan mark command for
308 the widget. It then adjusts the view left or right by 10
309 times the difference in x-coordinates. This command is
310 typically associated with mouse motion events in the wid‐
311 get, to produce the effect of dragging the spinbox at
312 high speed through the window. The return value is an
313 empty string.
314 pathName selection option arg
316 This command is used to adjust the selection within a spinbox.
317 It has several forms, depending on option:
318 pathName selection adjust index
320 Locate the end of the selection nearest to the character
321 given by index, and adjust that end of the selection to
322 be at index (i.e. including but not going beyond index).
323 The other end of the selection is made the anchor point
324 for future select to commands. If the selection isn't
325 currently in the spinbox, then a new selection is created
326 to include the characters between index and the most
327 recent selection anchor point, inclusive. Returns an
328 empty string.
329 pathName selection clear
331 Clear the selection if it is currently in this widget.
332 If the selection isn't in this widget then the command
333 has no effect. Returns an empty string.
334 pathName selection element ?element?
336 Sets or gets the currently selected element. If a spin‐
337 button element is specified, it will be displayed
338 depressed.
339 pathName selection from index
341 Set the selection anchor point to just before the charac‐
342 ter given by index. Doesn't change the selection.
343 Returns an empty string.
344 pathName selection present
346 Returns 1 if there is are characters selected in the
347 spinbox, 0 if nothing is selected.
348 pathName selection range start end
350 Sets the selection to include the characters starting
351 with the one indexed by start and ending with the one
352 just before end. If end refers to the same character as
353 start or an earlier one, then the spinbox's selection is
354 cleared.
355 pathName selection to index
357 If index is before the anchor point, set the selection to
358 the characters from index up to but not including the
359 anchor point. If index is the same as the anchor point,
360 do nothing. If index is after the anchor point, set the
361 selection to the characters from the anchor point up to
362 but not including index. The anchor point is determined
363 by the most recent select from or select adjust command
364 in this widget. If the selection isn't in this widget
365 then a new selection is created using the most recent
366 anchor point specified for the widget. Returns an empty
367 string.
368 pathName set ?string?
370 If string is specified, the spinbox will try and set it to this
371 value, otherwise it just returns the spinbox's string. If vali‐
372 dation is on, it will occur when setting the string.
373 pathName validate
375 This command is used to force an evaluation of the validateCom‐
376 mand independent of the conditions specified by the validate
377 option. This is done by temporarily setting the validate option
378 to all. It returns 0 or 1.
379 pathName xview args
381 This command is used to query and change the horizontal position
382 of the text in the widget's window. It can take any of the fol‐
383 lowing forms:
384 pathName xview
386 Returns a list containing two elements. Each element is
387 a real fraction between 0 and 1; together they describe
388 the horizontal span that is visible in the window. For
389 example, if the first element is .2 and the second ele‐
390 ment is .6, 20% of the spinbox's text is off-screen to
391 the left, the middle 40% is visible in the window, and
392 40% of the text is off-screen to the right. These are
393 the same values passed to scrollbars via the -xscrollcom‐
394 mand option.
395 pathName xview index
397 Adjusts the view in the window so that the character
398 given by index is displayed at the left edge of the win‐
399 dow.
400 pathName xview moveto fraction
402 Adjusts the view in the window so that the character
403 fraction of the way through the text appears at the left
404 edge of the window. Fraction must be a fraction between
405 0 and 1.
406 pathName xview scroll number what
408 This command shifts the view in the window left or right
409 according to number and what. Number must be an integer.
410 What must be either units or pages or an abbreviation of
411 one of these. If what is units, the view adjusts left or
412 right by number average-width characters on the display;
413 if it is pages then the view adjusts by number screen‐
414 fuls. If number is negative then characters farther to
415 the left become visible; if it is positive then charac‐
416 ters farther to the right become visible.
417
420 Tk automatically creates class bindings for spinboxes that give them
421 the following default behavior. In the descriptions below, ``word''
422 refers to a contiguous group of letters, digits, or ``_'' characters,
423 or any single character other than these.
424 [1] Clicking mouse button 1 positions the insertion cursor just
426 before the character underneath the mouse cursor, sets the input
427 focus to this widget, and clears any selection in the widget.
428 Dragging with mouse button 1 strokes out a selection between the
429 insertion cursor and the character under the mouse.
430 [2] Double-clicking with mouse button 1 selects the word under the
432 mouse and positions the insertion cursor at the beginning of the
433 word. Dragging after a double click will stroke out a selection
434 consisting of whole words.
435 [3] Triple-clicking with mouse button 1 selects all of the text in
437 the spinbox and positions the insertion cursor before the first
438 character.
439 [4] The ends of the selection can be adjusted by dragging with mouse
441 button 1 while the Shift key is down; this will adjust the end
442 of the selection that was nearest to the mouse cursor when but‐
443 ton 1 was pressed. If the button is double-clicked before drag‐
444 ging then the selection will be adjusted in units of whole
445 words.
446 [5] Clicking mouse button 1 with the Control key down will position
448 the insertion cursor in the spinbox without affecting the selec‐
449 tion.
450 [6] If any normal printing characters are typed in a spinbox, they
452 are inserted at the point of the insertion cursor.
453 [7] The view in the spinbox can be adjusted by dragging with mouse
455 button 2. If mouse button 2 is clicked without moving the
456 mouse, the selection is copied into the spinbox at the position
457 of the mouse cursor.
458 [8] If the mouse is dragged out of the spinbox on the left or right
460 sides while button 1 is pressed, the spinbox will automatically
461 scroll to make more text visible (if there is more text off-
462 screen on the side where the mouse left the window).
463 [9] The Left and Right keys move the insertion cursor one character
465 to the left or right; they also clear any selection in the
466 spinbox and set the selection anchor. If Left or Right is typed
467 with the Shift key down, then the insertion cursor moves and the
468 selection is extended to include the new character. Control-
469 Left and Control-Right move the insertion cursor by words, and
470 Control-Shift-Left and Control-Shift-Right move the insertion
471 cursor by words and also extend the selection. Control-b and
472 Control-f behave the same as Left and Right, respectively.
473 Meta-b and Meta-f behave the same as Control-Left and Control-
474 Right, respectively.
475 [10] The Home key, or Control-a, will move the insertion cursor to
477 the beginning of the spinbox and clear any selection in the
478 spinbox. Shift-Home moves the insertion cursor to the beginning
479 of the spinbox and also extends the selection to that point.
480 [11] The End key, or Control-e, will move the insertion cursor to the
482 end of the spinbox and clear any selection in the spinbox.
483 Shift-End moves the cursor to the end and extends the selection
484 to that point.
485 [12] The Select key and Control-Space set the selection anchor to the
487 position of the insertion cursor. They don't affect the current
488 selection. Shift-Select and Control-Shift-Space adjust the
489 selection to the current position of the insertion cursor,
490 selecting from the anchor to the insertion cursor if there was
491 not any selection previously.
492 [13] Control-/ selects all the text in the spinbox.
494 [14] Control-\ clears any selection in the spinbox.
496 [15] The F16 key (labelled Copy on many Sun workstations) or Meta-w
498 copies the selection in the widget to the clipboard, if there is
499 a selection.
500 [16] The F20 key (labelled Cut on many Sun workstations) or Control-w
502 copies the selection in the widget to the clipboard and deletes
503 the selection. If there is no selection in the widget then
504 these keys have no effect.
505 [17] The F18 key (labelled Paste on many Sun workstations) or Con‐
507 trol-y inserts the contents of the clipboard at the position of
508 the insertion cursor.
509 [18] The Delete key deletes the selection, if there is one in the
511 spinbox. If there is no selection, it deletes the character to
512 the right of the insertion cursor.
513 [19] The BackSpace key and Control-h delete the selection, if there
515 is one in the spinbox. If there is no selection, it deletes the
516 character to the left of the insertion cursor.
517 [20] Control-d deletes the character to the right of the insertion
519 cursor.
520 [21] Meta-d deletes the word to the right of the insertion cursor.
522 [22] Control-k deletes all the characters to the right of the inser‐
524 tion cursor.
525 [23] Control-t reverses the order of the two characters to the right
527 of the insertion cursor.
528 If the spinbox is disabled using the -state option, then the spinbox's
530 view can still be adjusted and text in the spinbox can still be
531 selected, but no insertion cursor will be displayed and no text modifi‐
532 cations will take place.
533 The behavior of spinboxes can be changed by defining new bindings for
535 individual widgets or by redefining the class bindings.
536
539 spinbox, entry, widget
540Tk 8.4 spinbox(n)