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 speci‐
70 fier of the form %<pad>.<pad>f, as it will format a floating-point
71 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 -incre‐
96 ment when a spin button is pressed (up adds the value, down sub‐
97 tracts 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 wid‐
113 get may still be selected. If the Spinbox is disabled, the value
114 may not be changed, no insertion cursor will be displayed, the con‐
115 tents will not be selectable, and the Spinbox may be displayed in a
116 different color, depending on the values of the -disabledforeground
117 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 -vali‐
143 date. 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 Vali‐
147 dation 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 argu‐
172 ment) 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 -xscrollcom‐
193 mand mechanism for interacting with scrollbars (see the description of
194 the -xscrollcommand option for details). They also support scanning,
195 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 The proposed value of the entry. If you are configuring the
223 entry widget to have a new textVariable, this will be the value
224 of that textVariable.
225 * 2 The characters to be added (or deleted). This will be "undef"
227 if validation is due to focus, explcit call to validate or if
228 change is due to "-textvariable" changing.
229 * 3 The current value of entry i.e. before the proposed change.
231 * 4 The index of character string to be added/deleted, if any. Oth‐
233 erwise -1.
234 * 5 Type of action. 1 == INSERT, 0 == DELETE, -1 if it's a forced
236 validation or textVariable validation.
237 In general, the textVariable and validateCommand can be dangerous
239 to mix. Any problems have been overcome so that using the vali‐
240 dateCommand will not interfere with the traditional behavior of the
241 Spinbox widget. Using the textVariable for read-only purposes will
242 never cause problems. The danger comes when you try set the
243 textVariable to something that the validateCommand would not
244 accept, which causes validate to become none (the invalidCommand
245 will not be triggered). The same happens when an error occurs
246 evaluating the validateCommand.
247 Primarily, an error will occur when the validateCommand or invalid‐
249 Command encounters an error in its script while evaluating or vali‐
250 dateCommand does not return a valid boolean value. The validate
251 option will also set itself to none when you edit the Spinbox wid‐
252 get from within either the validateCommand or the invalidCommand.
253 Such editions will override the one that was being validated. If
254 you wish to edit the value of the widget during validation and
255 still have the validate option set, you should include the command
256 my $val = $spinbox->cget(-validate);
258 $spinbox->configure(-validate => $val);
259 in the validateCommand or invalidCommand (whichever one you were
261 editing the Spinbox widget from). It is also recommended to not
262 set an associated textVariable during validation, as that can cause
263 the Spinbox widget to become out of sync with the textVariable.
264
266 The Spinbox command creates a widget object whose name is $widget.
267 This command may be used to invoke various operations on the widget.
268 It has the following general form:
269 $widget->method(?arg arg ...?);
271 Many of the methods for Spinboxes take one or more indices as argu‐
273 ments. An index specifies a particular character in the Spinbox's
274 string, in any of the following ways:
275 number
277 Specifies the character as a numerical index, where 0 corresponds
278 to the first character in the string.
279 anchor
281 Indicates the anchor point for the selection, which is set with the
282 select from and select adjust methods.
283 end Indicates the character just after the last one in the Spinbox's
285 string. This is equivalent to specifying a numerical index equal
286 to the length of the Spinbox's string.
287 insert
289 Indicates the character adjacent to and immediately following the
290 insertion cursor.
291 sel.first
293 Indicates the first character in the selection. It is an error to
294 use this form if the selection isn't in the Spinbox window.
295 sel.last
297 Indicates the character just after the last one in the selection.
298 It is an error to use this form if the selection isn't in the Spin‐
299 box window.
300 @number
302 In this form, number is treated as an x-coordinate in the Spinbox's
303 window; the character spanning that x-coordinate is used. For
304 example, ``@0'' indicates the left-most character in the window.
305 Abbreviations may be used for any of the forms above, e.g. ``e'' or
307 ``sel.f''. In general, out-of-range indices are automatically rounded
308 to the nearest legal value.
309 The following commands are possible for Spinbox widgets:
311 $widget->bbox(index);
313 Returns a list of four numbers describing the bounding box of the
314 character given by index. The first two elements of the list give
315 the x and y coordinates of the upper-left corner of the screen area
316 covered by the character (in pixels relative to the widget) and the
317 last two elements give the width and height of the character, in
318 pixels. The bounding box may refer to a region outside the visible
319 area of the window.
320 $widget->cget(option);
322 Returns the current value of the configuration option given by
323 option. Option may have any of the values accepted by the Spinbox
324 command.
325 $widget->configure(?option?, ?value, option, value, ...?);
327 Query or modify the configuration options of the widget. If no
328 option is specified, returns a list describing all of the available
329 options for $widget (see Tk::configure for information on the for‐
330 mat of this list). If option is specified with no value, then the
331 command returns a list describing the one named option (this list
332 will be identical to the corresponding sublist of the value
333 returned if no option is specified). If one or more option-value
334 pairs are specified, then the command modifies the given widget
335 option(s) to have the given value(s); in this case the command
336 returns an empty string. Option may have any of the values
337 accepted by the Spinbox command.
338 $widget->delete(first, ?last?);
340 Delete one or more elements of the Spinbox. First is the index of
341 the first character to delete, and last is the index of the charac‐
342 ter just after the last one to delete. If last isn't specified it
343 defaults to first+1, i.e. a single character is deleted. This com‐
344 mand returns an empty string.
345 $widget->get;
347 Returns the Spinbox's string.
348 $widget->icursor(index);
350 Arrange for the insertion cursor to be displayed just before the
351 character given by index. Returns an empty string.
352 $widget->identify(x, y);
354 Returns the name of the window element corresponding to coordinates
355 x and y in the Spinbox. Return value is one of: none, buttondown,
356 buttonup, entry.
357 $widget->index(index);
359 Returns the numerical index corresponding to index.
360 $widget->insert(index, string);
362 Insert the characters of string just before the character indicated
363 by index. Returns an empty string.
364 $widget->invoke(element);
366 Causes the specified element, either buttondown or buttonup, to be
367 invoked, triggering the action associated with it.
368 $widget->scan(option, args);
370 This command is used to implement scanning on Spinboxes. It has
371 two forms, depending on option:
372 $widget->scanMark(x);
374 Records x and the current view in the Spinbox window; used in
375 conjunction with later scan dragto commands. Typically this
376 command is associated with a mouse button press in the widget.
377 It returns an empty string.
378 $widget->scanDragto(x);
380 This command computes the difference between its x argument and
381 the x argument to the last scan mark command for the widget.
382 It then adjusts the view left or right by 10 times the differ‐
383 ence in x-coordinates. This command is typically associated
384 with mouse motion events in the widget, to produce the effect
385 of dragging the Spinbox at high speed through the window. The
386 return value is an empty string.
387 $widget->selection(option, arg);
389 This command is used to adjust the selection within a Spinbox. It
390 has several forms, depending on option:
391 $widget->selectionAdjust(index);
393 Locate the end of the selection nearest to the character given
394 by index, and adjust that end of the selection to be at index
395 (i.e including but not going beyond index). The other end of
396 the selection is made the anchor point for future select to
397 commands. If the selection isn't currently in the Spinbox,
398 then a new selection is created to include the characters
399 between index and the most recent selection anchor point,
400 inclusive. Returns an empty string.
401 $widget->selectionClear;
403 Clear the selection if it is currently in this widget. If the
404 selection isn't in this widget then the command has no effect.
405 Returns an empty string.
406 $widget->selectionElement(?element?);
408 Sets or gets the currently selected element. If a spinbutton
409 element is specified, it will be displayed depressed.
410 $widget->selectionFrom(index);
412 Set the selection anchor point to just before the character
413 given by index. Doesn't change the selection. Returns an
414 empty string.
415 $widget->selectionPresent;
417 Returns 1 if there is are characters selected in the Spinbox, 0
418 if nothing is selected.
419 $widget->selectionRange(start, end);
421 Sets the selection to include the characters starting with the
422 one indexed by start and ending with the one just before end.
423 If end refers to the same character as start or an earlier one,
424 then the Spinbox's selection is cleared.
425 $widget->selectionTo(index);
427 If index is before the anchor point, set the selection to the
428 characters from index up to but not including the anchor point.
429 If index is the same as the anchor point, do nothing. If index
430 is after the anchor point, set the selection to the characters
431 from the anchor point up to but not including index. The
432 anchor point is determined by the most recent select from or
433 select adjust command in this widget. If the selection isn't
434 in this widget then a new selection is created using the most
435 recent anchor point specified for the widget. Returns an empty
436 string.
437 $widget->set(?string?);
439 If string is specified, the Spinbox will try and set it to this
440 value, otherwise it just returns the Spinbox's string. If valida‐
441 tion is on, it will occur when setting the string.
442 $widget->validate;
444 This command is used to force an evaluation of the validateCommand
445 independent of the conditions specified by the validate option.
446 This is done by temporarily setting the validate option to all. It
447 returns 0 or 1.
448 $widget->xview(args);
450 This command is used to query and change the horizontal position of
451 the text in the widget's window. It can take any of the following
452 forms:
453 $widget->xview;
455 Returns a list containing two elements. Each element is a real
456 fraction between 0 and 1; together they describe the horizon‐
457 tal span that is visible in the window. For example, if the
458 first element is .2 and the second element is .6, 20% of the
459 Spinbox's text is off-screen to the left, the middle 40% is
460 visible in the window, and 40% of the text is off-screen to the
461 right. These are the same values passed to scrollbars via the
462 -xscrollcommand option.
463 $widget->xview(index);
465 Adjusts the view in the window so that the character given by
466 index is displayed at the left edge of the window.
467 $widget->xviewMoveto(fraction);
469 Adjusts the view in the window so that the character fraction
470 of the way through the text appears at the left edge of the
471 window. Fraction must be a fraction between 0 and 1.
472 $widget->xviewScroll(number, what);
474 This command shifts the view in the window left or right
475 according to number and what. Number must be an integer. What
476 must be either units or pages or an abbreviation of one of
477 these. If what is units, the view adjusts left or right by
478 number average-width characters on the display; if it is pages
479 then the view adjusts by number screenfuls. If number is nega‐
480 tive then characters farther to the left become visible; if it
481 is positive then characters farther to the right become visi‐
482 ble.
483
485 Tk automatically creates class bindings for Spinboxes that give them
486 the following default behavior. In the descriptions below, ``word''
487 refers to a contiguous group of letters, digits, or ``_'' characters,
488 or any single character other than these.
489 [1] Clicking mouse button 1 positions the insertion cursor just before
491 the character underneath the mouse cursor, sets the input focus to
492 this widget, and clears any selection in the widget. Dragging with
493 mouse button 1 strokes out a selection between the insertion cursor
494 and the character under the mouse.
495 [2] Double-clicking with mouse button 1 selects the word under the
497 mouse and positions the insertion cursor at the beginning of the
498 word. Dragging after a double click will stroke out a selection
499 consisting of whole words.
500 [3] Triple-clicking with mouse button 1 selects all of the text in the
502 Spinbox and positions the insertion cursor before the first charac‐
503 ter.
504 [4] The ends of the selection can be adjusted by dragging with mouse
506 button 1 while the Shift key is down; this will adjust the end of
507 the selection that was nearest to the mouse cursor when button 1
508 was pressed. If the button is double-clicked before dragging then
509 the selection will be adjusted in units of whole words.
510 [5] Clicking mouse button 1 with the Control key down will position the
512 insertion cursor in the Spinbox without affecting the selection.
513 [6] If any normal printing characters are typed in a Spinbox, they are
515 inserted at the point of the insertion cursor.
516 [7] The view in the Spinbox can be adjusted by dragging with mouse but‐
518 ton 2. If mouse button 2 is clicked without moving the mouse, the
519 selection is copied into the Spinbox at the position of the mouse
520 cursor.
521 [8] If the mouse is dragged out of the Spinbox on the left or right
523 sides while button 1 is pressed, the Spinbox will automatically
524 scroll to make more text visible (if there is more text off-screen
525 on the side where the mouse left the window).
526 [9] The Left and Right keys move the insertion cursor one character to
528 the left or right; they also clear any selection in the Spinbox
529 and set the selection anchor. If Left or Right is typed with the
530 Shift key down, then the insertion cursor moves and the selection
531 is extended to include the new character. Control-Left and Con‐
532 trol-Right move the insertion cursor by words, and Control-Shift-
533 Left and Control-Shift-Right move the insertion cursor by words and
534 also extend the selection. Control-b and Control-f behave the same
535 as Left and Right, respectively. Meta-b and Meta-f behave the same
536 as Control-Left and Control-Right, respectively.
537 [10]
539 The Home key, or Control-a, will move the insertion cursor to the
540 beginning of the Spinbox and clear any selection in the Spinbox.
541 Shift-Home moves the insertion cursor to the beginning of the Spin‐
542 box and also extends the selection to that point.
543 [11]
545 The End key, or Control-e, will move the insertion cursor to the
546 end of the Spinbox and clear any selection in the Spinbox. Shift-
547 End moves the cursor to the end and extends the selection to that
548 point.
549 [12]
551 The Select key and Control-Space set the selection anchor to the
552 position of the insertion cursor. They don't affect the current
553 selection. Shift-Select and Control-Shift-Space adjust the selec‐
554 tion to the current position of the insertion cursor, selecting
555 from the anchor to the insertion cursor if there was not any selec‐
556 tion previously.
557 [13]
559 Control-/ selects all the text in the Spinbox.
560 [14]
562 Control-\ clears any selection in the Spinbox.
563 [15]
565 The F16 key (labelled Copy on many Sun workstations) or Meta-w
566 copies the selection in the widget to the clipboard, if there is a
567 selection.
568 [16]
570 The F20 key (labelled Cut on many Sun workstations) or Control-w
571 copies the selection in the widget to the clipboard and deletes the
572 selection. If there is no selection in the widget then these keys
573 have no effect.
574 [17]
576 The F18 key (labelled Paste on many Sun workstations) or Control-y
577 inserts the contents of the clipboard at the position of the inser‐
578 tion cursor.
579 [18]
581 The Delete key deletes the selection, if there is one in the Spin‐
582 box. If there is no selection, it deletes the character to the
583 right of the insertion cursor.
584 [19]
586 The BackSpace key and Control-h delete the selection, if there is
587 one in the Spinbox. If there is no selection, it deletes the char‐
588 acter to the left of the insertion cursor.
589 [20]
591 Control-d deletes the character to the right of the insertion cur‐
592 sor.
593 [21]
595 Meta-d deletes the word to the right of the insertion cursor.
596 [22]
598 Control-k deletes all the characters to the right of the insertion
599 cursor.
600 [23]
602 Control-t reverses the order of the two characters to the right of
603 the insertion cursor.
604 If the Spinbox is disabled using the -state option, then the Spin‐
606 box's view can still be adjusted and text in the Spinbox can still
607 be selected, but no insertion cursor will be displayed and no text
608 modifications will take place.
609 The behavior of Spinboxes can be changed by defining new bindings
611 for individual widgets or by redefining the class bindings.
612
614 Spinbox, Entry, widget
615perl v5.8.8 2008-02-05 Spinbox(3)