diff options
Diffstat (limited to 'doc/spinbox.n')
| -rw-r--r-- | doc/spinbox.n | 582 |
1 files changed, 582 insertions, 0 deletions
diff --git a/doc/spinbox.n b/doc/spinbox.n new file mode 100644 index 0000000..5cf39e6 --- /dev/null +++ b/doc/spinbox.n @@ -0,0 +1,582 @@ +'\" +'\" Copyright (c) 2000 Jeffrey Hobbs. +'\" Copyright (c) 2000 Ajuba Solutions. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: spinbox.n,v 1.1 2000/05/29 01:43:13 hobbs Exp $ +'\" +.so man.macros +.TH spinbox n 8.4 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +spinbox \- Create and manipulate spinbox widgets +.SH SYNOPSIS +\fBspinbox\fR \fIpathName \fR?\fIoptions\fR? +.SO +\-activebackground \-background \-borderwidth +\-cursor \-exportselection \-font +\-foreground \-highlightbackground \-highlightcolor +\-highlightthickness \-insertbackground \-insertborderwidth +\-insertontime \-insertwidth \-insertofftime +\-justify \-relief \-repeatdelay +\-repeatinterval \-selectbackground \-selectborderwidth +\-selectforeground \-takefocus \-textvariable +\-xscrollcommand +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-buttonbackground buttonBackground Background +The background color to be used for the spin buttons. +.OP \-buttoncursor buttonCursor Cursor +The cursor to be used when over the spin buttons. If this is empty +(the default), a default cursor will be used. +.OP \-buttondownrelief buttonDownRelief Relief +The relief to be used for the upper spin button. +.OP \-buttonuprelief buttonUpRelief Relief +The relief to be used for the lower spin button. +.OP \-command command Command +Specifies a Tcl command to invoke whenever a spinbutton is invoked. +The command recognizes several percent substitutions: \fB%W\fR for +the widget path, \fB%s\fR for the current value of the widget, and +\fB%d\fR for the direction of the button pressed (\fBup\fR or \fBdown\fR). +.OP \-disabledbackground disabledBackground DisabledBackground +Specifies the background color to use when the spinbox is disabled. If +this option is the empty string, the normal background color is used. +.OP \-disabledforeground disabledForeground DisabledForeground +Specifies the foreground color to use when the spinbox is disabled. If +this option is the empty string, the normal foreground color is used. +.OP \-format format Format +Specifies an alternate format to use when setting the string value +when using the \fB\-from\fR and \fB\-to\fR range. +This must be a format specifier of the form \fB%<pad>.<pad>f\fR, +as it will format a floating-point number. +.OP \-from from From +A floating-point value corresponding to the lowest value for a spinbox, to +be used in conjunction with \fB\-to\fR and \fB\-increment\fR. When all +are specified correctly, the spinbox will use these values to control its +contents. This value must be less than the \fB\-to\fR option. +If \fB\-values\fR is specified, it supercedes this option. +.OP "\-invalidcommand or \-invcmd" invalidCommand InvalidCommand +Specifies a script to eval when \fBvalidateCommand\fR returns 0. Setting +it to an empty string disables this feature (the default). The best use of +this option is to set it to \fIbell\fR. See \fBValidation\fR below for +more information. +.OP \-increment increment Increment +A floating-point value specifying the increment. When used with +\fB\-from\fR and \fB\-to\fR, the value in the widget will be adjusted by +\fB\-increment\fR when a spin button is pressed (up adds the value, +down subtracts the value). +.OP \-readonlybackground readonlyBackground ReadonlyBackground +Specifies the background color to use when the spinbox is readonly. If +this option is the empty string, the normal background color is used. +.OP \-state state State +Specifies one of three states for the spinbox: \fBnormal\fR, +\fBdisabled\fR, or \fBreadonly\fR. If the spinbox is readonly, then the +value may not be changed using widget commands and no insertion cursor +will be displayed, even if the input focus is in the widget; the +contents of the widget may still be selected. If the spinbox is +disabled, the value may not be changed, no insertion cursor will be +displayed, the contents will not be selectable, and the spinbox may +be displayed in a different color, depending on the values of the +\fB-disabledforeground\fR and \fB-disabledbackground\fR options. +.OP \-to to To +A floating-point value corresponding to the highest value for the spinbox, +to be used in conjunction with \fB\-from\fR and \fB\-increment\fR. When +all are specified correctly, the spinbox will use these values to control +its contents. This value must be greater than the \fB\-from\fR option. +If \fB\-values\fR is specified, it supercedes this option. +.OP \-validate validate Validate +Specifies the mode in which validation should operate: \fBnone\fR, +\fBfocus\fR, \fBfocusin\fR, \fBfocusout\fR, \fBkey\fR, or \fBall\fR. +It defaults to \fBnone\fR. When you want validation, you must explicitly +state which mode you wish to use. See \fBValidation\fR below for more. +.OP "\-validatecommand or \-vcmd" validateCommand ValidateCommand +Specifies a script to evaluate when you want to validate the input in the +widget. Setting it to an empty string disables this feature (the default). +Validation occurs according to the value of \fB\-validate\fR. +This command must return a valid Tcl boolean value. If it returns 0 (or +the valid Tcl boolean equivalent) then the value of the widget will not +change and the \fBinvalidCommand\fR will be evaluated if it is set. If it +returns 1, then value will be changed. +See \fBValidation\fR below for more information. +.OP \-values values Values +Must be a proper list value. If specified, the spinbox will use these +values as to control its contents, starting with the first value. This +option has precedence over the \fB\-from\fR and \fB\-to\fR range. +.OP \-width width Width +Specifies an integer value indicating the desired width of the spinbox window, +in average-size characters of the widget's font. +If the value is less than or equal to zero, the widget picks a +size just large enough to hold its current text. +.OP \-wrap wrap wrap +Must be a proper boolean value. If on, the spinbox will wrap around the +values of data in the widget. +.BE + +.SH DESCRIPTION +.PP +The \fBspinbox\fR command creates a new window (given by the +\fIpathName\fR argument) and makes it into a spinbox widget. +Additional options, described above, may be specified on the +command line or in the option database +to configure aspects of the spinbox such as its colors, font, +and relief. The \fBspinbox\fR command returns its +\fIpathName\fR argument. At the time this command is invoked, +there must not exist a window named \fIpathName\fR, but +\fIpathName\fR's parent must exist. +.PP +A \fBspinbox\fR is an extended \fBentry\fR widget that allows he user +to move, or spin, through a fixed set of ascending or descending values +such as times or dates in addition to editing the value as in an +\fBentry\fR. When first created, a spinbox's string is empty. +A portion of the spinbox may be selected as described below. +If a spinbox is exporting its selection (see the \fBexportSelection\fR +option), then it will observe the standard protocols for handling the +selection; spinbox selections are available as type \fBSTRING\fR. +Spinboxes also observe the standard Tk rules for dealing with the +input focus. When a spinbox has the input focus it displays an +\fIinsertion cursor\fR to indicate where new characters will be +inserted. +.PP +Spinboxes are capable of displaying strings that are too long to +fit entirely within the widget's window. In this case, only a +portion of the string will be displayed; commands described below +may be used to change the view in the window. Spinboxes use +the standard \fBxScrollCommand\fR mechanism for interacting with +scrollbars (see the description of the \fBxScrollCommand\fR option +for details). They also support scanning, as described below. + +.SH VALIDATION +.PP +Validation works by setting the \fBvalidateCommand\fR +option to a script which will be evaluated according to the \fBvalidate\fR +option as follows: +.PP +.IP \fBnone\fR 10 +Default. This means no validation will occur. +.IP \fBfocus\fR 10 +\fBvalidateCommand\fR will be called when the spinbox receives or +loses focus. +.IP \fBfocusin\fR 10 +\fBvalidateCommand\fR will be called when the spinbox receives focus. +.IP \fBfocusout\fR 10 +\fBvalidateCommand\fR will be called when the spinbox loses focus. +.IP \fBkey\fR 10 +\fBvalidateCommand\fR will be called when the spinbox is edited. +.IP \fBall\fR 10 +\fBvalidateCommand\fR will be called for all above conditions. +.PP +It is posible to perform percent substitutions on the \fBvalidateCommand\fR +and \fBinvalidCommand\fR, just as you would in a \fBbind\fR script. The +following substitutions are recognized: +.PP +.IP \fB%d\fR 5 +Type of action: 1 for \fBinsert\fR, 0 for \fBdelete\fR, +or -1 for focus, forced or textvariable validation. +.IP \fB%i\fR 5 +Index of char string to be inserted/deleted, if any, otherwise -1. +.IP \fB%P\fR 5 +The value of the spinbox should edition occur. If you are configuring the +spinbox widget to have a new textvariable, this will be the value of that +textvariable. +.IP \fB%s\fR 5 +The current value of spinbox before edition. +.IP \fB%S\fR 5 +The text string being inserted/deleted, if any. +Otherwise it is an empty string. +.IP \fB%v\fR 5 +The type of validation currently set. +.IP \fB%V\fR 5 +The type of validation that triggered the callback +(key, focusin, focusout, forced). +.IP \fB%W\fR 5 +The name of the spinbox widget. +.PP +In general, the \fBtextVariable\fR and \fBvalidateCommand\fR can be +dangerous to mix. Any problems have been overcome so that using the +\fBvalidateCommand\fR will not interfere with the traditional behavior of +the spinbox widget. Using the \fBtextVariable\fR for read-only purposes will +never cause problems. The danger comes when you try set the +\fBtextVariable\fR to something that the \fBvalidateCommand\fR would not +accept, which causes \fBvalidate\fR to become \fInone\fR (the +\fBinvalidCommand\fR will not be triggered). The same happens +when an error occurs evaluating the \fBvalidateCommand\fR. +.PP +Primarily, an error will occur when the \fBvalidateCommand\fR or +\fBinvalidCommand\fR encounters an error in its script while evaluating or +\fBvalidateCommand\fR does not return a valid Tcl boolean value. The +\fBvalidate\fR option will also set itself to \fBnone\fR when you edit the +spinbox widget from within either the \fBvalidateCommand\fR or the +\fBinvalidCommand\fR. Such editions will override the one that was being +validated. If you wish to edit the value of the widget +during validation and still have the \fBvalidate\fR option set, you should +include the command +.CS + \fI%W config -validate %v\fR +.CE +in the \fBvalidateCommand\fR or \fBinvalidCommand\fR (whichever one you +were editing the spinbox widget from). It is also recommended to not set an +associated \fBtextVariable\fR during validation, as that can cause the +spinbox widget to become out of sync with the \fBtextVariable\fR. + +.SH "WIDGET COMMAND" +.PP +The \fBspinbox\fR command creates a new Tcl command whose +name is \fIpathName\fR. This command may be used to invoke various +operations on the widget. It has the following general form: +.CS +\fIpathName option \fR?\fIarg arg ...\fR? +.CE +\fIOption\fR and the \fIarg\fRs +determine the exact behavior of the command. +.PP +Many of the widget commands for spinboxes take one or more indices as +arguments. An index specifies a particular character in the spinbox's +string, in any of the following ways: +.TP 12 +\fInumber\fR +Specifies the character as a numerical index, where 0 corresponds +to the first character in the string. +.TP 12 +\fBanchor\fR +Indicates the anchor point for the selection, which is set with the +\fBselect from\fR and \fBselect adjust\fR widget commands. +.TP 12 +\fBend\fR +Indicates the character just after the last one in the spinbox's string. +This is equivalent to specifying a numerical index equal to the length +of the spinbox's string. +.TP 12 +\fBinsert\fR +Indicates the character adjacent to and immediately following the +insertion cursor. +.TP 12 +\fBsel.first\fR +Indicates the first character in the selection. It is an error to +use this form if the selection isn't in the spinbox window. +.TP 12 +\fBsel.last\fR +Indicates the character just after the last one in the selection. +It is an error to use this form if the selection isn't in the +spinbox window. +.TP 12 +\fB@\fInumber\fR +In this form, \fInumber\fR is treated as an x-coordinate in the +spinbox's window; the character spanning that x-coordinate is used. +For example, ``\fB@0\fR'' indicates the left-most character in the +window. +.LP +Abbreviations may be used for any of the forms above, e.g. ``\fBe\fR'' +or ``\fBsel.f\fR''. In general, out-of-range indices are automatically +rounded to the nearest legal value. +.PP +The following commands are possible for spinbox widgets: +.TP +\fIpathName \fBbbox \fIindex\fR +Returns a list of four numbers describing the bounding box of the +character given by \fIindex\fR. +The first two elements of the list give the x and y coordinates of +the upper-left corner of the screen area covered by the character +(in pixels relative to the widget) and the last two elements give +the width and height of the character, in pixels. +The bounding box may refer to a region outside the visible area +of the window. +.TP +\fIpathName \fBcget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the \fBspinbox\fR +command. +.TP +\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options of the widget. +If no \fIoption\fR is specified, returns a list describing all of +the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). If +one or more \fIoption\-value\fR pairs are specified, then the command +modifies the given widget option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the \fBspinbox\fR +command. +.TP +\fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? +Delete one or more elements of the spinbox. +\fIFirst\fR is the index of the first character to delete, and +\fIlast\fR is the index of the character just after the last +one to delete. +If \fIlast\fR isn't specified it defaults to \fIfirst\fR+1, +i.e. a single character is deleted. +This command returns an empty string. +.TP +\fIpathName \fBget\fR +Returns the spinbox's string. +.TP +\fIpathName \fBicursor \fIindex\fR +Arrange for the insertion cursor to be displayed just before the character +given by \fIindex\fR. Returns an empty string. +.TP +\fIpathName \fBidentify\fI x y\fR +Returns the name of the window element corresponding to coordinates +\fIx\fR and \fIy\fR in the spinbox. Return value is one of: +\fBnone\fR, \fBspindown\fR, \fBspinup\fR, \fBentry\fR. +.TP +\fIpathName \fBindex\fI index\fR +Returns the numerical index corresponding to \fIindex\fR. +.TP +\fIpathName \fBinsert \fIindex string\fR +Insert the characters of \fIstring\fR just before the character +indicated by \fIindex\fR. Returns an empty string. +.TP +\fIpathName \fBinvoke\fI element\fR +Causes the specified element, either \fBspindown\fR or \fBspinup\fR, +to be invoked, triggering the action associated with it. +.TP +\fIpathName \fBscan\fR \fIoption args\fR +This command is used to implement scanning on spinboxes. It has +two forms, depending on \fIoption\fR: +.RS +.TP +\fIpathName \fBscan mark \fIx\fR +Records \fIx\fR and the current view in the spinbox window; used in +conjunction with later \fBscan dragto\fR commands. Typically this +command is associated with a mouse button press in the widget. It +returns an empty string. +.TP +\fIpathName \fBscan dragto \fIx\fR +This command computes the difference between its \fIx\fR argument +and the \fIx\fR argument to the last \fBscan mark\fR command for +the widget. It then adjusts the view left or right by 10 times the +difference in x-coordinates. This command is typically associated +with mouse motion events in the widget, to produce the effect of +dragging the spinbox at high speed through the window. The return +value is an empty string. +.RE +.TP +\fIpathName \fBselection \fIoption arg\fR +This command is used to adjust the selection within a spinbox. It +has several forms, depending on \fIoption\fR: +.RS +.TP +\fIpathName \fBselection adjust \fIindex\fR +Locate the end of the selection nearest to the character given by +\fIindex\fR, and adjust that end of the selection to be at \fIindex\fR +(i.e including but not going beyond \fIindex\fR). The other +end of the selection is made the anchor point for future +\fBselect to\fR commands. If the selection +isn't currently in the spinbox, then a new selection is created to +include the characters between \fIindex\fR and the most recent +selection anchor point, inclusive. +Returns an empty string. +.TP +\fIpathName \fBselection clear\fR +Clear the selection if it is currently in this widget. If the +selection isn't in this widget then the command has no effect. +Returns an empty string. +.TP +\fIpathName \fBselection element\fR ?\fIelement\fR? +Sets or gets the currently selected element. If a spinbutton element +is specified, it will be displayed depressed. +.TP +\fIpathName \fBselection from \fIindex\fR +Set the selection anchor point to just before the character +given by \fIindex\fR. Doesn't change the selection. +Returns an empty string. +.TP +\fIpathName \fBselection present\fR +Returns 1 if there is are characters selected in the spinbox, +0 if nothing is selected. +.TP +\fIpathName \fBselection range \fIstart\fR \fIend\fR +Sets the selection to include the characters starting with +the one indexed by \fIstart\fR and ending with the one just +before \fIend\fR. +If \fIend\fR refers to the same character as \fIstart\fR or an +earlier one, then the spinbox's selection is cleared. +.TP +\fIpathName \fBselection to \fIindex\fR +If \fIindex\fR is before the anchor point, set the selection +to the characters from \fIindex\fR up to but not including +the anchor point. +If \fIindex\fR is the same as the anchor point, do nothing. +If \fIindex\fR is after the anchor point, set the selection +to the characters from the anchor point up to but not including +\fIindex\fR. +The anchor point is determined by the most recent \fBselect from\fR +or \fBselect adjust\fR command in this widget. +If the selection isn't in this widget then a new selection is +created using the most recent anchor point specified for the widget. +Returns an empty string. +.RE +.TP +\fIpathName \fBset\fR ?\fIstring\fR? +If \fIstring\fR is specified, the spinbox will try and set it to this +value, otherwise it just returns the spinbox's string. +If validation is on, it will occur when setting the string. +.TP +\fIpathName \fBvalidate\fR +This command is used to force an evaluation of the \fBvalidateCommand\fR +independent of the conditions specified by the \fBvalidate\fR option. +This is done by temporarily setting the \fBvalidate\fR option to \fBall\fR. +It returns 0 or 1. +.TP +\fIpathName \fBxview \fIargs\fR +This command is used to query and change the horizontal position of the +text in the widget's window. It can take any of the following +forms: +.RS +.TP +\fIpathName \fBxview\fR +Returns a list containing two elements. +Each element is a real fraction between 0 and 1; together they describe +the horizontal span that is visible in the window. +For example, if the first element is .2 and the second element is .6, +20% of the spinbox's text is off-screen to the left, the middle 40% is visible +in the window, and 40% of the text is off-screen to the right. +These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR +option. +.TP +\fIpathName \fBxview\fR \fIindex\fR +Adjusts the view in the window so that the character given by \fIindex\fR +is displayed at the left edge of the window. +.TP +\fIpathName \fBxview moveto\fI fraction\fR +Adjusts the view in the window so that the character \fIfraction\fR of the +way through the text appears at the left edge of the window. +\fIFraction\fR must be a fraction between 0 and 1. +.TP +\fIpathName \fBxview scroll \fInumber what\fR +This command shifts the view in the window left or right according to +\fInumber\fR and \fIwhat\fR. +\fINumber\fR must be an integer. +\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation +of one of these. +If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by +\fInumber\fR average-width characters on the display; if it is +\fBpages\fR then the view adjusts by \fInumber\fR screenfuls. +If \fInumber\fR is negative then characters farther to the left +become visible; if it is positive then characters farther to the right +become visible. +.RE + +.SH "DEFAULT BINDINGS" +.PP +Tk automatically creates class bindings for spinboxes that give them +the following default behavior. +In the descriptions below, ``word'' refers to a contiguous group +of letters, digits, or ``_'' characters, or any single character +other than these. +.IP [1] +Clicking mouse button 1 positions the insertion cursor +just before the character underneath the mouse cursor, sets the +input focus to this widget, and clears any selection in the widget. +Dragging with mouse button 1 strokes out a selection between +the insertion cursor and the character under the mouse. +.IP [2] +Double-clicking with mouse button 1 selects the word under the mouse +and positions the insertion cursor at the beginning of the word. +Dragging after a double click will stroke out a selection consisting +of whole words. +.IP [3] +Triple-clicking with mouse button 1 selects all of the text in the +spinbox and positions the insertion cursor before the first character. +.IP [4] +The ends of the selection can be adjusted by dragging with mouse +button 1 while the Shift key is down; this will adjust the end +of the selection that was nearest to the mouse cursor when button +1 was pressed. +If the button is double-clicked before dragging then the selection +will be adjusted in units of whole words. +.IP [5] +Clicking mouse button 1 with the Control key down will position the +insertion cursor in the spinbox without affecting the selection. +.IP [6] +If any normal printing characters are typed in a spinbox, they are +inserted at the point of the insertion cursor. +.IP [7] +The view in the spinbox can be adjusted by dragging with mouse button 2. +If mouse button 2 is clicked without moving the mouse, the selection +is copied into the spinbox at the position of the mouse cursor. +.IP [8] +If the mouse is dragged out of the spinbox on the left or right sides +while button 1 is pressed, the spinbox will automatically scroll to +make more text visible (if there is more text off-screen on the side +where the mouse left the window). +.IP [9] +The Left and Right keys move the insertion cursor one character to the +left or right; they also clear any selection in the spinbox and set +the selection anchor. +If Left or Right is typed with the Shift key down, then the insertion +cursor moves and the selection is extended to include the new character. +Control-Left and Control-Right move the insertion cursor by words, and +Control-Shift-Left and Control-Shift-Right move the insertion cursor +by words and also extend the selection. +Control-b and Control-f behave the same as Left and Right, respectively. +Meta-b and Meta-f behave the same as Control-Left and Control-Right, +respectively. +.IP [10] +The Home key, or Control-a, will move the insertion cursor to the +beginning of the spinbox and clear any selection in the spinbox. +Shift-Home moves the insertion cursor to the beginning of the spinbox +and also extends the selection to that point. +.IP [11] +The End key, or Control-e, will move the insertion cursor to the +end of the spinbox and clear any selection in the spinbox. +Shift-End moves the cursor to the end and extends the selection +to that point. +.IP [12] +The Select key and Control-Space set the selection anchor to the position +of the insertion cursor. They don't affect the current selection. +Shift-Select and Control-Shift-Space adjust the selection to the +current position of the insertion cursor, selecting from the anchor +to the insertion cursor if there was not any selection previously. +.IP [13] +Control-/ selects all the text in the spinbox. +.IP [14] +Control-\e clears any selection in the spinbox. +.IP [15] +The F16 key (labelled Copy on many Sun workstations) or Meta-w +copies the selection in the widget to the clipboard, if there is a selection. +.IP [16] +The F20 key (labelled Cut on many Sun workstations) or Control-w +copies the selection in the widget to the clipboard and deletes +the selection. +If there is no selection in the widget then these keys have no effect. +.IP [17] +The F18 key (labelled Paste on many Sun workstations) or Control-y +inserts the contents of the clipboard at the position of the +insertion cursor. +.IP [18] +The Delete key deletes the selection, if there is one in the spinbox. +If there is no selection, it deletes the character to the right of +the insertion cursor. +.IP [19] +The BackSpace key and Control-h delete the selection, if there is one +in the spinbox. +If there is no selection, it deletes the character to the left of +the insertion cursor. +.IP [20] +Control-d deletes the character to the right of the insertion cursor. +.IP [21] +Meta-d deletes the word to the right of the insertion cursor. +.IP [22] +Control-k deletes all the characters to the right of the insertion +cursor. +.IP [23] +Control-t reverses the order of the two characters to the right of +the insertion cursor. +.PP +If the spinbox is disabled using the \fB\-state\fR option, then the spinbox's +view can still be adjusted and text in the spinbox can still be selected, +but no insertion cursor will be displayed and no text modifications will +take place. +.PP +The behavior of spinboxes can be changed by defining new bindings for +individual widgets or by redefining the class bindings. + +.SH KEYWORDS +spinbox, entry, widget |