1Spinbox(3) User Contributed Perl Documentation Spinbox(3)
2
6 Tk::Spinbox - Create and manipulate Spinbox widgets
7
9 $spinbox = $parent->Spinbox(?options?);
10 -activebackground -highlightthickness -repeatinterval
12 -background -insertbackground -selectbackground
13 -borderwidth -insertborderwidth -selectborderwidth
14 -cursor -insertontime -selectforeground
15 -exportselection -insertwidth -takefocus
16 -font -insertofftime -textvariable
17 -foreground -justify -xscrollcommand
18 -highlightbackground -relief
19 -highlightcolor -repeatdelay
20
22 Option: -buttonbackground
23 Name: buttonBackground
24 Class: Background
25 The background color to be used for the spin buttons.
26 Option: -buttoncursor
28 Name: buttonCursor
29 Class: Cursor
30 The cursor to be used when over the spin buttons. If this is empty
31 (the default), a default cursor will be used.
32 Option: -buttondownrelief
34 Name: buttonDownRelief
35 Class: Relief
36 The relief to be used for the upper spin button.
37 Option: -buttonuprelief
39 Name: buttonUpRelief
40 Class: Relief
41 The relief to be used for the lower spin button.
42 Option: -command
44 Name: command
45 Class: Command
46 Specifies a Perl/Tk callback to invoke whenever a Spinbutton is
47 invoked. The callback has these two arguments appended to any
48 existing callback arguments: the current value of the widget and
49 the direction of the button press (up or down).
50 Option: -disabledbackground
52 Name: disabledBackground
53 Class: DisabledBackground
54 Specifies the background color to use when the Spinbox is disabled.
55 If this option is the empty string, the normal background color is
56 used.
57 Option: -disabledforeground
59 Name: disabledForeground
60 Class: DisabledForeground
61 Specifies the foreground color to use when the Spinbox is disabled.
62 If this option is the empty string, the normal foreground color is
63 used.
64 Option: -format
66 Name: format
67 Class: Format
68 Specifies an alternate format to use when setting the string value
69 when using the -from and -to range. This must be a format
70 specifier of the form %<pad>.<pad>f, as it will format a floating-
71 point number.
72 Option: -from
74 Name: from
75 Class: From
76 A floating-point value corresponding to the lowest value for a
77 Spinbox, to be used in conjunction with -to and -increment. When
78 all are specified correctly, the Spinbox will use these values to
79 control its contents. This value must be less than the -to option.
80 If -values is specified, it supercedes this option.
81 Option: -invalidcommand
83 Alias: -invcmd
84 Name: invalidCommand
85 Class: InvalidCommand
86 Specifies a script to eval when validateCommand returns 0. Setting
87 it to an empty string disables this feature (the default). The
88 best use of this option is to set it to bell. See Validation below
89 for more information.
90 Option: -increment
92 Name: increment
93 Class: Increment
94 A floating-point value specifying the increment. When used with
95 -from and -to, the value in the widget will be adjusted by
96 -increment when a spin button is pressed (up adds the value, down
97 subtracts the value).
98 Option: -readonlybackground
100 Name: readonlyBackground
101 Class: ReadonlyBackground
102 Specifies the background color to use when the Spinbox is readonly.
103 If this option is the empty string, the normal background color is
104 used.
105 Option: -state
107 Name: state
108 Class: State
109 Specifies one of three states for the Spinbox: normal, disabled,
110 or readonly. If the Spinbox is readonly, then the value may not be
111 changed using methods and no insertion cursor will be displayed,
112 even if the input focus is in the widget; the contents of the
113 widget may still be selected. If the Spinbox is disabled, the
114 value may not be changed, no insertion cursor will be displayed,
115 the contents will not be selectable, and the Spinbox may be
116 displayed in a different color, depending on the values of the
117 -disabledforeground and -disabledbackground options.
118 Option: -to
120 Name: to
121 Class: To
122 A floating-point value corresponding to the highest value for the
123 Spinbox, to be used in conjunction with -from and -increment. When
124 all are specified correctly, the Spinbox will use these values to
125 control its contents. This value must be greater than the -from
126 option. If -values is specified, it supercedes this option.
127 Option: -validate
129 Name: validate
130 Class: Validate
131 Specifies the mode in which validation should operate: none, focus,
132 focusin, focusout, key, or all. It defaults to none. When you
133 want validation, you must explicitly state which mode you wish to
134 use. See Validation below for more.
135 Option: -validatecommand
137 Alias: -vcmd
138 Name: validateCommand
139 Class: ValidateCommand
140 Specifies a script to evaluate when you want to validate the input
141 in the widget. Setting it to an empty string disables this feature
142 (the default). Validation occurs according to the value of
143 -validate. This command must return a valid boolean value. If it
144 returns 0 (or the valid boolean equivalent) then the value of the
145 widget will not change and the invalidCommand will be evaluated if
146 it is set. If it returns 1, then value will be changed. See
147 Validation below for more information.
148 Option: -values
150 Name: values
151 Class: Values
152 Must be a proper list value. If specified, the Spinbox will use
153 these values as to control its contents, starting with the first
154 value. This option has precedence over the -from and -to range.
155 Option: -width
157 Name: width
158 Class: Width
159 Specifies an integer value indicating the desired width of the
160 Spinbox window, in average-size characters of the widget's font.
161 If the value is less than or equal to zero, the widget picks a size
162 just large enough to hold its current text.
163 Option: -wrap
165 Name: wrap
166 Class: Wrap
167 Must be a proper boolean value. If on, the Spinbox will wrap
168 around the values of data in the widget.
169
171 The Spinbox method creates a new window (given by the $spinbox
172 argument) and makes it into a Spinbox widget. Additional options,
173 described above, may be specified on the command line or in the option
174 database to configure aspects of the Spinbox such as its colors, font,
175 and relief.
176 A Spinbox is an extended Entry widget that allows he user to move, or
178 spin, through a fixed set of ascending or descending values such as
179 times or dates in addition to editing the value as in an entry. When
180 first created, a Spinbox's string is empty. A portion of the Spinbox
181 may be selected as described below. If a Spinbox is exporting its
182 selection (see the exportSelection option), then it will observe the
183 standard protocols for handling the selection; Spinbox selections are
184 available as type STRING. Spinboxes also observe the standard Tk rules
185 for dealing with the input focus. When a Spinbox has the input focus
186 it displays an insertion cursor to indicate where new characters will
187 be inserted.
188 Spinboxes are capable of displaying strings that are too long to fit
190 entirely within the widget's window. In this case, only a portion of
191 the string will be displayed; commands described below may be used to
192 change the view in the window. Spinboxes use the standard
193 -xscrollcommand mechanism for interacting with scrollbars (see the
194 description of the -xscrollcommand option for details). They also
195 support scanning, as described below.
196
198 Validation works by setting the validateCommand option to a callback
199 which will be evaluated according to the validate option as follows:
200 none
202 Default. This means no validation will occur.
203 focus
205 validateCommand will be called when the Spinbox receives or loses
206 focus.
207 focusin
209 validateCommand will be called when the Spinbox receives focus.
210 focusout
212 validateCommand will be called when the Spinbox loses focus.
213 key validateCommand will be called when the Spinbox is edited.
215 all validateCommand will be called for all above conditions.
217 The validateCommand and invalidCommand callbacks are invoked with
219 at least 5 positional arguments, which are appended to any already
220 existing callback arguments:
221 • 1
223 The proposed value of the entry. If you are configuring the
225 entry widget to have a new textVariable, this will be the value
226 of that textVariable.
227 • 2
229 The characters to be added (or deleted). This will be "undef"
231 if validation is due to focus, explcit call to validate or if
232 change is due to "-textvariable" changing.
233 • 3
235 The current value of entry i.e. before the proposed change.
237 • 4
239 The index of character string to be added/deleted, if any.
241 Otherwise -1.
242 • 5
244 Type of action. 1 == INSERT, 0 == DELETE, -1 if it's a forced
246 validation or textVariable validation.
247 In general, the textVariable and validateCommand can be dangerous
249 to mix. Any problems have been overcome so that using the
250 validateCommand will not interfere with the traditional behavior of
251 the Spinbox widget. Using the textVariable for read-only purposes
252 will never cause problems. The danger comes when you try set the
253 textVariable to something that the validateCommand would not
254 accept, which causes validate to become none (the invalidCommand
255 will not be triggered). The same happens when an error occurs
256 evaluating the validateCommand.
257 Primarily, an error will occur when the validateCommand or
259 invalidCommand encounters an error in its script while evaluating
260 or validateCommand does not return a valid boolean value. The
261 validate option will also set itself to none when you edit the
262 Spinbox widget from within either the validateCommand or the
263 invalidCommand. Such editions will override the one that was being
264 validated. If you wish to edit the value of the widget during
265 validation and still have the validate option set, you should
266 include the command
267 my $val = $spinbox->cget(-validate);
269 $spinbox->configure(-validate => $val);
270 in the validateCommand or invalidCommand (whichever one you were
272 editing the Spinbox widget from). It is also recommended to not
273 set an associated textVariable during validation, as that can cause
274 the Spinbox widget to become out of sync with the textVariable.
275
277 The Spinbox command creates a widget object whose name is $widget.
278 This command may be used to invoke various operations on the widget.
279 It has the following general form:
280 $widget->method(?arg arg ...?);
282 Many of the methods for Spinboxes take one or more indices as
284 arguments. An index specifies a particular character in the Spinbox's
285 string, in any of the following ways:
286 number
288 Specifies the character as a numerical index, where 0 corresponds
289 to the first character in the string.
290 anchor
292 Indicates the anchor point for the selection, which is set with the
293 select from and select adjust methods.
294 end Indicates the character just after the last one in the Spinbox's
296 string. This is equivalent to specifying a numerical index equal
297 to the length of the Spinbox's string.
298 insert
300 Indicates the character adjacent to and immediately following the
301 insertion cursor.
302 sel.first
304 Indicates the first character in the selection. It is an error to
305 use this form if the selection isn't in the Spinbox window.
306 sel.last
308 Indicates the character just after the last one in the selection.
309 It is an error to use this form if the selection isn't in the
310 Spinbox window.
311 @number
313 In this form, number is treated as an x-coordinate in the Spinbox's
314 window; the character spanning that x-coordinate is used. For
315 example, ``@0'' indicates the left-most character in the window.
316 Abbreviations may be used for any of the forms above, e.g. ``e'' or
318 ``sel.f''. In general, out-of-range indices are automatically rounded
319 to the nearest legal value.
320 The following commands are possible for Spinbox widgets:
322 $widget->bbox(index);
324 Returns a list of four numbers describing the bounding box of the
325 character given by index. The first two elements of the list give
326 the x and y coordinates of the upper-left corner of the screen area
327 covered by the character (in pixels relative to the widget) and the
328 last two elements give the width and height of the character, in
329 pixels. The bounding box may refer to a region outside the visible
330 area of the window.
331 $widget->cget(option);
333 Returns the current value of the configuration option given by
334 option. Option may have any of the values accepted by the Spinbox
335 command.
336 $widget->configure(?option?, ?value, option, value, ...?);
338 Query or modify the configuration options of the widget. If no
339 option is specified, returns a list describing all of the available
340 options for $widget (see Tk::configure for information on the
341 format of this list). If option is specified with no value, then
342 the command returns a list describing the one named option (this
343 list will be identical to the corresponding sublist of the value
344 returned if no option is specified). If one or more option-value
345 pairs are specified, then the command modifies the given widget
346 option(s) to have the given value(s); in this case the command
347 returns an empty string. Option may have any of the values
348 accepted by the Spinbox command.
349 $widget->delete(first, ?last?);
351 Delete one or more elements of the Spinbox. First is the index of
352 the first character to delete, and last is the index of the
353 character just after the last one to delete. If last isn't
354 specified it defaults to first+1, i.e. a single character is
355 deleted. This command returns an empty string.
356 $widget->get;
358 Returns the Spinbox's string.
359 $widget->icursor(index);
361 Arrange for the insertion cursor to be displayed just before the
362 character given by index. Returns an empty string.
363 $widget->identify(x, y);
365 Returns the name of the window element corresponding to coordinates
366 x and y in the Spinbox. Return value is one of: none, buttondown,
367 buttonup, entry.
368 $widget->index(index);
370 Returns the numerical index corresponding to index.
371 $widget->insert(index, string);
373 Insert the characters of string just before the character indicated
374 by index. Returns an empty string.
375 $widget->invoke(element);
377 Causes the specified element, either buttondown or buttonup, to be
378 invoked, triggering the action associated with it.
379 $widget->scan(option, args);
381 This command is used to implement scanning on Spinboxes. It has
382 two forms, depending on option:
383 $widget->scanMark(x);
385 Records x and the current view in the Spinbox window; used in
386 conjunction with later scan dragto commands. Typically this
387 command is associated with a mouse button press in the widget.
388 It returns an empty string.
389 $widget->scanDragto(x);
391 This command computes the difference between its x argument and
392 the x argument to the last scan mark command for the widget.
393 It then adjusts the view left or right by 10 times the
394 difference in x-coordinates. This command is typically
395 associated with mouse motion events in the widget, to produce
396 the effect of dragging the Spinbox at high speed through the
397 window. The return value is an empty string.
398 $widget->selection(option, arg);
400 This command is used to adjust the selection within a Spinbox. It
401 has several forms, depending on option:
402 $widget->selectionAdjust(index);
404 Locate the end of the selection nearest to the character given
405 by index, and adjust that end of the selection to be at index
406 (i.e including but not going beyond index). The other end of
407 the selection is made the anchor point for future select to
408 commands. If the selection isn't currently in the Spinbox,
409 then a new selection is created to include the characters
410 between index and the most recent selection anchor point,
411 inclusive. Returns an empty string.
412 $widget->selectionClear;
414 Clear the selection if it is currently in this widget. If the
415 selection isn't in this widget then the command has no effect.
416 Returns an empty string.
417 $widget->selectionElement(?element?);
419 Sets or gets the currently selected element. If a spinbutton
420 element is specified, it will be displayed depressed.
421 $widget->selectionFrom(index);
423 Set the selection anchor point to just before the character
424 given by index. Doesn't change the selection. Returns an
425 empty string.
426 $widget->selectionPresent;
428 Returns 1 if there is are characters selected in the Spinbox, 0
429 if nothing is selected.
430 $widget->selectionRange(start, end);
432 Sets the selection to include the characters starting with the
433 one indexed by start and ending with the one just before end.
434 If end refers to the same character as start or an earlier one,
435 then the Spinbox's selection is cleared.
436 $widget->selectionTo(index);
438 If index is before the anchor point, set the selection to the
439 characters from index up to but not including the anchor point.
440 If index is the same as the anchor point, do nothing. If index
441 is after the anchor point, set the selection to the characters
442 from the anchor point up to but not including index. The
443 anchor point is determined by the most recent select from or
444 select adjust command in this widget. If the selection isn't
445 in this widget then a new selection is created using the most
446 recent anchor point specified for the widget. Returns an empty
447 string.
448 $widget->set(?string?);
450 If string is specified, the Spinbox will try and set it to this
451 value, otherwise it just returns the Spinbox's string. If
452 validation is on, it will occur when setting the string.
453 $widget->validate;
455 This command is used to force an evaluation of the validateCommand
456 independent of the conditions specified by the validate option.
457 This is done by temporarily setting the validate option to all. It
458 returns 0 or 1.
459 $widget->xview(args);
461 This command is used to query and change the horizontal position of
462 the text in the widget's window. It can take any of the following
463 forms:
464 $widget->xview;
466 Returns a list containing two elements. Each element is a real
467 fraction between 0 and 1; together they describe the
468 horizontal span that is visible in the window. For example, if
469 the first element is .2 and the second element is .6, 20% of
470 the Spinbox's text is off-screen to the left, the middle 40% is
471 visible in the window, and 40% of the text is off-screen to the
472 right. These are the same values passed to scrollbars via the
473 -xscrollcommand option.
474 $widget->xview(index);
476 Adjusts the view in the window so that the character given by
477 index is displayed at the left edge of the window.
478 $widget->xviewMoveto(fraction);
480 Adjusts the view in the window so that the character fraction
481 of the way through the text appears at the left edge of the
482 window. Fraction must be a fraction between 0 and 1.
483 $widget->xviewScroll(number, what);
485 This command shifts the view in the window left or right
486 according to number and what. Number must be an integer. What
487 must be either units or pages or an abbreviation of one of
488 these. If what is units, the view adjusts left or right by
489 number average-width characters on the display; if it is pages
490 then the view adjusts by number screenfuls. If number is
491 negative then characters farther to the left become visible;
492 if it is positive then characters farther to the right become
493 visible.
494
496 Tk automatically creates class bindings for Spinboxes that give them
497 the following default behavior. In the descriptions below, ``word''
498 refers to a contiguous group of letters, digits, or ``_'' characters,
499 or any single character other than these.
500 [1] Clicking mouse button 1 positions the insertion cursor just before
502 the character underneath the mouse cursor, sets the input focus to
503 this widget, and clears any selection in the widget. Dragging with
504 mouse button 1 strokes out a selection between the insertion cursor
505 and the character under the mouse.
506 [2] Double-clicking with mouse button 1 selects the word under the
508 mouse and positions the insertion cursor at the beginning of the
509 word. Dragging after a double click will stroke out a selection
510 consisting of whole words.
511 [3] Triple-clicking with mouse button 1 selects all of the text in the
513 Spinbox and positions the insertion cursor before the first
514 character.
515 [4] The ends of the selection can be adjusted by dragging with mouse
517 button 1 while the Shift key is down; this will adjust the end of
518 the selection that was nearest to the mouse cursor when button 1
519 was pressed. If the button is double-clicked before dragging then
520 the selection will be adjusted in units of whole words.
521 [5] Clicking mouse button 1 with the Control key down will position the
523 insertion cursor in the Spinbox without affecting the selection.
524 [6] If any normal printing characters are typed in a Spinbox, they are
526 inserted at the point of the insertion cursor.
527 [7] The view in the Spinbox can be adjusted by dragging with mouse
529 button 2. If mouse button 2 is clicked without moving the mouse,
530 the selection is copied into the Spinbox at the position of the
531 mouse cursor.
532 [8] If the mouse is dragged out of the Spinbox on the left or right
534 sides while button 1 is pressed, the Spinbox will automatically
535 scroll to make more text visible (if there is more text off-screen
536 on the side where the mouse left the window).
537 [9] The Left and Right keys move the insertion cursor one character to
539 the left or right; they also clear any selection in the Spinbox
540 and set the selection anchor. If Left or Right is typed with the
541 Shift key down, then the insertion cursor moves and the selection
542 is extended to include the new character. Control-Left and
543 Control-Right move the insertion cursor by words, and Control-
544 Shift-Left and Control-Shift-Right move the insertion cursor by
545 words and also extend the selection. Control-b and Control-f
546 behave the same as Left and Right, respectively. Meta-b and Meta-f
547 behave the same as Control-Left and Control-Right, respectively.
548 [10]
550 The Home key, or Control-a, will move the insertion cursor to the
551 beginning of the Spinbox and clear any selection in the Spinbox.
552 Shift-Home moves the insertion cursor to the beginning of the
553 Spinbox and also extends the selection to that point.
554 [11]
556 The End key, or Control-e, will move the insertion cursor to the
557 end of the Spinbox and clear any selection in the Spinbox. Shift-
558 End moves the cursor to the end and extends the selection to that
559 point.
560 [12]
562 The Select key and Control-Space set the selection anchor to the
563 position of the insertion cursor. They don't affect the current
564 selection. Shift-Select and Control-Shift-Space adjust the
565 selection to the current position of the insertion cursor,
566 selecting from the anchor to the insertion cursor if there was not
567 any selection previously.
568 [13]
570 Control-/ selects all the text in the Spinbox.
571 [14]
573 Control-\ clears any selection in the Spinbox.
574 [15]
576 The F16 key (labelled Copy on many Sun workstations) or Meta-w
577 copies the selection in the widget to the clipboard, if there is a
578 selection.
579 [16]
581 The F20 key (labelled Cut on many Sun workstations) or Control-w
582 copies the selection in the widget to the clipboard and deletes the
583 selection. If there is no selection in the widget then these keys
584 have no effect.
585 [17]
587 The F18 key (labelled Paste on many Sun workstations) or Control-y
588 inserts the contents of the clipboard at the position of the
589 insertion cursor.
590 [18]
592 The Delete key deletes the selection, if there is one in the
593 Spinbox. If there is no selection, it deletes the character to the
594 right of the insertion cursor.
595 [19]
597 The BackSpace key and Control-h delete the selection, if there is
598 one in the Spinbox. If there is no selection, it deletes the
599 character to the left of the insertion cursor.
600 [20]
602 Control-d deletes the character to the right of the insertion
603 cursor.
604 [21]
606 Meta-d deletes the word to the right of the insertion cursor.
607 [22]
609 Control-k deletes all the characters to the right of the insertion
610 cursor.
611 [23]
613 Control-t reverses the order of the two characters to the right of
614 the insertion cursor.
615 If the Spinbox is disabled using the -state option, then the
617 Spinbox's view can still be adjusted and text in the Spinbox can
618 still be selected, but no insertion cursor will be displayed and no
619 text modifications will take place.
620 The behavior of Spinboxes can be changed by defining new bindings
622 for individual widgets or by redefining the class bindings.
623
625 Spinbox, Entry, widget
626perl v5.32.1 2021-01-27 Spinbox(3)