1spinbox(n)                   Tk Built-In Commands                   spinbox(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       spinbox - Create and manipulate spinbox widgets
9

SYNOPSIS

11       spinbox pathName ?options?
12

STANDARD OPTIONS

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
24       See the options manual entry for details on the standard options.
25

WIDGET-SPECIFIC OPTIONS

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

DESCRIPTION

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
105       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
117       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

VALIDATION

126       Validation  works  by  setting  the  validateCommand option to a script
127       which will be evaluated according to the validate option as follows:
128
129       none      Default.  This means no validation will occur.
130
131       focus     validateCommand will be called when the spinbox  receives  or
132                 loses focus.
133
134       focusin   validateCommand  will  be  called  when  the spinbox receives
135                 focus.
136
137       focusout  validateCommand will be called when the spinbox loses focus.
138
139       key       validateCommand will be called when the spinbox is edited.
140
141       all       validateCommand will be called for all above conditions.
142
143       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
147       %d   Type of action: 1 for insert, 0  for  delete,  or  -1  for  focus,
148            forced or textvariable validation.
149
150       %i   Index of char string to be inserted/deleted, if any, otherwise -1.
151
152       %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
156       %s   The current value of spinbox before edition.
157
158       %S   The  text  string being inserted/deleted, if any.  Otherwise it is
159            an empty string.
160
161       %v   The type of validation currently set.
162
163       %V   The type of validation that triggered the callback (key,  focusin,
164            focusout, forced).
165
166       %W   The name of the spinbox widget.
167
168       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
177       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

WIDGET COMMAND

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
198   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
203       number      Specifies the character as a numerical index, where 0  cor‐
204                   responds to the first character in the string.
205
206       anchor      Indicates  the anchor point for the selection, which is set
207                   with the select from and select adjust widget commands.
208
209       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
214       insert      Indicates the character adjacent to and immediately follow‐
215                   ing the insertion cursor.
216
217       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
221       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
225       @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
230       Abbreviations  may  be  used  for  any of the forms above, e.g.  “e” or
231sel.f”.  In general, out-of-range indices are automatically rounded to
232       the nearest legal value.
233
234   SUBCOMMANDS
235       The following commands are possible for spinbox widgets:
236
237       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
246       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
251       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
264       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
271       pathName get
272              Returns the spinbox's string.
273
274       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
278       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
283       pathName index index
284              Returns the numerical index corresponding to index.
285
286       pathName insert index string
287              Insert the characters of string just before the character  indi‐
288              cated by index.  Returns an empty string.
289
290       pathName invoke element
291              Causes  the specified element, either buttondown or buttonup, to
292              be invoked, triggering the action associated with it.
293
294       pathName scan option args
295              This command is used to implement scanning on spinboxes.  It has
296              two forms, depending on option:
297
298              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
304              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
314       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
318              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
329              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
334              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
339              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
344              pathName selection present
345                     Returns 1 if there is  are  characters  selected  in  the
346                     spinbox, 0 if nothing is selected.
347
348              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
355              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
368       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
373       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
379       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
384              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
395              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
400              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
406              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
417

DEFAULT BINDINGS

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
424       [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
430       [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
435       [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
439       [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
446       [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
450       [6]    If any normal printing characters are typed in a  spinbox,  they
451              are inserted at the point of the insertion cursor.
452
453       [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
458       [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
463       [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
475       [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
480       [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
485       [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
492       [13]   Control-/ selects all the text in the spinbox.
493
494       [14]   Control-\ clears any selection in the spinbox.
495
496       [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
500       [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
505       [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
509       [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
513       [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
517       [20]   Control-d  deletes  the  character to the right of the insertion
518              cursor.
519
520       [21]   Meta-d deletes the word to the right of the insertion cursor.
521
522       [22]   Control-k deletes all the characters to the right of the  inser‐
523              tion cursor.
524
525       [23]   Control-t  reverses the order of the two characters to the right
526              of the insertion cursor.
527
528       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
533       The  behavior  of spinboxes can be changed by defining new bindings for
534       individual widgets or by redefining the class bindings.
535
536

KEYWORDS

538       spinbox, entry, widget
539
540
541
542Tk                                    8.4                           spinbox(n)
Impressum