diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/SetOptions.3 | 50 | ||||
| -rw-r--r-- | doc/canvas.n | 6 | ||||
| -rw-r--r-- | doc/colors.n | 26 | ||||
| -rw-r--r-- | doc/event.n | 2 | ||||
| -rw-r--r-- | doc/listbox.n | 18 | ||||
| -rw-r--r-- | doc/option.n | 6 | ||||
| -rw-r--r-- | doc/spinbox.n | 16 | ||||
| -rw-r--r-- | doc/text.n | 120 |
8 files changed, 186 insertions, 58 deletions
diff --git a/doc/SetOptions.3 b/doc/SetOptions.3 index ebd6f6a..b5f0782 100644 --- a/doc/SetOptions.3 +++ b/doc/SetOptions.3 @@ -129,19 +129,21 @@ option table is no longer needed \fBTk_DeleteOptionTable\fR should be called to free all of its resources. All of the option tables for a Tcl interpreter are freed automatically if the interpreter is deleted. .PP -\fBTk_InitOptions\fR is invoked when a new widget is created to set -the default values for all of the widget's configuration options. -\fBTk_InitOptions\fR is passed a token for an option table (\fIoptionTable\fR) -and a pointer to a widget record (\fIrecordPtr\fR), which is the C -structure that holds information about this widget. \fBTk_InitOptions\fR -uses the information in the option table to -choose an appropriate default for each option, then it stores the default -value directly into the widget record, overwriting any information that -was already present in the widget record. \fBTk_InitOptions\fR normally -returns \fBTCL_OK\fR. If an error occurred while setting the default values -(e.g., because a default value was erroneous) then \fBTCL_ERROR\fR is returned -and an error message is left in \fIinterp\fR's result if \fIinterp\fR -is not NULL. +\fBTk_InitOptions\fR is invoked when a new widget is created to set the +default values for all of the widget's configuration options that do not +have \fBTK_OPTION_DONT_SET_DEFAULT\fR set in their \fIflags\fR field. +\fBTk_InitOptions\fR is passed a token for an option table +(\fIoptionTable\fR) and a pointer to a widget record (\fIrecordPtr\fR), +which is the C structure that holds information about this widget. +\fBTk_InitOptions\fR uses the information in the option table to choose an +appropriate default for each option, except those having +\fBTK_OPTION_DONT_SET_DEFAULT\fR set, then it stores the default value +directly into the widget record, overwriting any information that was +already present in the widget record. \fBTk_InitOptions\fR normally +returns \fBTCL_OK\fR. If an error occurred while setting the default +values (e.g., because a default value was erroneous) then \fBTCL_ERROR\fR +is returned and an error message is left in \fIinterp\fR's result if +\fIinterp\fR is not NULL. .PP \fBTk_SetOptions\fR is invoked to modify configuration options based on information specified in a Tcl command. The command might be one that @@ -306,19 +308,27 @@ given by \fIinternalOffset\fR. For example, if the option's type is value is not stored in that form. At least one of the offsets must be greater than or equal to zero. .PP -The \fIflags\fR field consists of one or more bits ORed together. At -present only a single flag is supported: \fBTK_OPTION_NULL_OK\fR. If -this bit is set for an option then an empty string will be accepted as -the value for the option and the resulting internal form will be a -NULL pointer, a zero value, or \fBNone\fR, depending on the type of -the option. If the flag is not set then empty strings will result -in errors. +The \fIflags\fR field consists of one or more bits ORed together. The +following flags are supported: +.TP +\fBTK_OPTION_NULL_OK\fR +If this bit is set for an option then an empty string will be accepted as +the value for the option and the resulting internal form will be a NULL +pointer, a zero value, or \fBNone\fR, depending on the type of the option. +If the flag is not set then empty strings will result in errors. \fBTK_OPTION_NULL_OK\fR is typically used to allow a feature to be turned off entirely, e.g. set a cursor value to \fBNone\fR so that a window simply inherits its parent's cursor. Not all option types support the \fBTK_OPTION_NULL_OK\fR flag; for those that do, there is an explicit indication of that fact in the descriptions below. +.TP +\fBTK_OPTION_DONT_SET_DEFAULT\fR +If this bit is set for an option then no default value will be set in +\fBTk_InitOptions\fR for this option. Neither the option database, nor any +system default value, nor \fIoptionTable\fR are used to give a default +value to this option. Instead it is assumed that the caller has already +supplied a default value in the widget code. .PP The \fItype\fR field of each Tk_OptionSpec structure determines how to parse the value of that configuration option. The diff --git a/doc/canvas.n b/doc/canvas.n index bc29cc3..38697cd 100644 --- a/doc/canvas.n +++ b/doc/canvas.n @@ -263,7 +263,7 @@ automatically decremented by one. A number less than 0 is treated as if it were zero, and a number greater than the length of the text item is treated as if it were equal to the length of the text item. For -polygons, numbers less than 0 or greater then the length +polygons, numbers less than 0 or greater than the length of the coordinate list will be adjusted by adding or subtracting the length until the result is between zero and the length, inclusive. @@ -405,7 +405,7 @@ behaves as if the \fIstart\fR argument had not been specified. . Selects all the items completely enclosed within the rectangular region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. -\fIX1\fR must be no greater then \fIx2\fR and \fIy1\fR must be +\fIX1\fR must be no greater than \fIx2\fR and \fIy1\fR must be no greater than \fIy2\fR. .TP \fBoverlapping\fR \fIx1\fR \fIy1\fR \fIx2\fR \fIy2\fR @@ -413,7 +413,7 @@ no greater than \fIy2\fR. Selects all the items that overlap or are enclosed within the rectangular region given by \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. -\fIX1\fR must be no greater then \fIx2\fR and \fIy1\fR must be +\fIX1\fR must be no greater than \fIx2\fR and \fIy1\fR must be no greater than \fIy2\fR. .TP \fBwithtag \fItagOrId\fR diff --git a/doc/colors.n b/doc/colors.n index d121248..dc7007b 100644 --- a/doc/colors.n +++ b/doc/colors.n @@ -933,19 +933,19 @@ On Windows, the following additional system colors are available .RS .DS .ta 6c -3dDarkShadow Highlight -3dLight HighlightText -ActiveBorder InactiveBorder -ActiveCaption InactiveCaption -AppWorkspace InactiveCaptionText -Background InfoBackground -ButtonFace InfoText -ButtonHighlight Menu -ButtonShadow MenuText -ButtonText Scrollbar -CaptionText Window -DisabledText WindowFrame -GrayText WindowText +system3dDarkShadow systemHighlight +system3dLight systemHighlightText +systemActiveBorder systemInactiveBorder +systemActiveCaption systemInactiveCaption +systemAppWorkspace systemInactiveCaptionText +systemBackground systemInfoBackground +systemButtonFace systemInfoText +systemButtonHighlight systemMenu +systemButtonShadow systemMenuText +systemButtonText systemScrollbar +systemCaptionText systemWindow +systemDisabledText systemWindowFrame +systemGrayText systemWindowText .DE .RE .SH "SEE ALSO" diff --git a/doc/event.n b/doc/event.n index 11782dd..7a3cfca 100644 --- a/doc/event.n +++ b/doc/event.n @@ -546,7 +546,7 @@ the physical event. .PP Bindings on a virtual event may be created before the virtual event exists. Indeed, the virtual event never actually needs to be defined, for instance, -on platforms where the specific virtual event would meaningless or +on platforms where the specific virtual event would be meaningless or ungeneratable. .PP When a definition of a virtual event changes at run time, all windows diff --git a/doc/listbox.n b/doc/listbox.n index 4264823..0f263b4 100644 --- a/doc/listbox.n +++ b/doc/listbox.n @@ -17,9 +17,10 @@ listbox \- Create and manipulate 'listbox' item list widgets \-background \-borderwidth \-cursor \-disabledforeground \-exportselection \-font \-foreground \-highlightbackground \-highlightcolor -\-highlightthickness \-relief \-selectbackground -\-selectborderwidth \-selectforeground \-setgrid -\-takefocus \-xscrollcommand \-yscrollcommand +\-highlightthickness \-justify \-relief +\-selectbackground \-selectborderwidth \-selectforeground +\-setgrid \-takefocus \-xscrollcommand +\-yscrollcommand .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-activestyle activeStyle ActiveStyle @@ -452,7 +453,7 @@ it and deselects any other selected item. In \fBbrowse\fR mode it is also possible to drag the selection with button 1. On button 1, the listbox will also take focus if it has a \fBnormal\fR -state and \fB\-takefocus\fR is true. +state. .PP If the selection mode is \fBmultiple\fR or \fBextended\fR, any number of elements may be selected at once, including discontiguous @@ -468,9 +469,12 @@ Most people will probably want to use \fBbrowse\fR mode for single selections and \fBextended\fR mode for multiple selections; the other modes appear to be useful only in special situations. .PP -Any time the selection changes in the listbox, the virtual event -\fB<<ListboxSelect>>\fR will be generated. It is easiest to bind -to this event to be made aware of any changes to listbox selection. +Any time the set of selected item(s) in the listbox is updated by the +user through the keyboard or mouse, the virtual event +\fB<<ListboxSelect>>\fR will be generated. This virtual event will not +be generated when adjusting the selection with the \fIpathName +\fBselection\fR command. It is easiest to bind to this event to be +made aware of any user changes to listbox selection. .PP In addition to the above behavior, the following additional behavior is defined by the default bindings: diff --git a/doc/option.n b/doc/option.n index 8699c0d..2763d64 100644 --- a/doc/option.n +++ b/doc/option.n @@ -59,6 +59,12 @@ options specified in that file to the option database. If \fIpriority\fR is specified, it indicates the priority level at which to enter the options; \fIpriority\fR defaults to \fBinteractive\fR. .PP +The file is read through a channel which is in "utf-8" encoding, +invalid byte sequences are automatically converted to valid ones. +This means that encodings like ISO 8859-1 or cp1252 with high +probability will work as well, but this cannot be guaranteed. +This cannot be changed, setting the [encoding system] has no effect. +.PP The \fIpriority\fR arguments to the \fBoption\fR command are normally specified symbolically using one of the following values: .TP diff --git a/doc/spinbox.n b/doc/spinbox.n index 1e8cb3a..330bb17 100644 --- a/doc/spinbox.n +++ b/doc/spinbox.n @@ -55,7 +55,7 @@ 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. +If \fB\-values\fR is specified, it supersedes this option. .OP "\-invalidcommand or \-invcmd" invalidCommand InvalidCommand Specifies a script to eval when \fB\-validatecommand\fR returns 0. Setting it to an empty string disables this feature (the default). The best use of @@ -84,7 +84,7 @@ 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. +If \fB\-values\fR is specified, it supersedes 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. @@ -196,7 +196,7 @@ dangerous to mix. Any problems have been overcome so that using the the spinbox widget. Using the \fB\-textvariable\fR for read-only purposes will never cause problems. The danger comes when you try set the \fB\-textvariable\fR to something that the \fB\-validatecommand\fR would not -accept, which causes \fB\-validate\fR to become \fInone\fR (the +accept, which causes \fB\-validate\fR to become \fBnone\fR (the \fB\-invalidcommand\fR will not be triggered). The same happens when an error occurs evaluating the \fB\-validatecommand\fR. .PP @@ -216,6 +216,16 @@ in the \fB\-validatecommand\fR or \fB\-invalidcommand\fR (whichever one you were editing the spinbox widget from). It is also recommended to not set an associated \fB\-textvariable\fR during validation, as that can cause the spinbox widget to become out of sync with the \fB\-textvariable\fR. +.PP +Also, the \fBvalidate\fR option will set itself to \fBnone\fR when the +spinbox value gets changed because of adjustment of \fBfrom\fR or \fBto\fR +and the \fBvalidateCommand\fR returns false. For instance +.CS + \fIspinbox pathName \-from 1 \-to 10 \-validate all \-vcmd {return 0}\fR +.CE +will in fact set the \fBvalidate\fR option to \fBnone\fR because the default +value for the spinbox gets changed (due to the \fBfrom\fR and \fBto\fR +options) to a value not accepted by the validation script. .SH "WIDGET COMMAND" .PP The \fBspinbox\fR command creates a new Tcl command whose @@ -917,6 +917,83 @@ affected. .PP See below for the \fIpathName \fBpeer\fR widget command that controls the creation of peer widgets. +.SH "ASYNCHRONOUS UPDATE OF LINE HEIGHTS" +.PP +In order to maintain a responsive user-experience, the text widget calculates +lines metrics (line heights in pixels) asynchronously. Because of this, some +commands of the text widget may return wrong results if the asynchronous +calculations are not finished at the time of calling. This applies to +\fIpathName \fBcount -ypixels\fR and \fIpathName \fByview\fR. +.PP +Again for performance reasons, it would not be appropriate to let these +commands always wait for the end of the update calculation each time they are +called. In most use cases of these commands a more or less inaccurate result +does not really matter compared to execution speed. +.PP +In case accurate result is needed (and if the text widget is managed by a +geometry manager), one can resort to \fIpathName \fBsync\fR and \fIpathName +\fBpendingsync\fR to control the synchronization of the view of text widgets. +.PP +The \fB<<WidgetViewSync>>\fR virtual event fires when the line heights of the +text widget becomes obsolete (due to some editing command or configuration +change), and again when the internal data of the text widget are back in sync +with the widget view. The detail field (%d substitution) is either true (when +the widget is in sync) or false (when it is not). +.PP +\fIpathName \fBsync\fR, \fIpathName \fBpendingsync\fR and +\fB<<WidgetViewSync>>\fR apply to each text widget independently of its peers. +.PP +Examples of use: +.CS +## Example 1: +# immediately complete line metrics at any cost (GUI unresponsive) +$w sync +$w yview moveto $fraction + +## Example 2: +# synchronously wait for up-to-date line metrics (GUI responsive) +# before executing the scheduled command, but don't block execution flow +$w sync -command [list $w yview moveto $fraction] + +## Example 3: +# init +set yud($w) 0 +proc updateaction w { +\&set ::yud($w) 1 +\&# any other update action here... +} +# runtime, synchronously wait for up-to-date line metrics (GUI responsive) +$w sync -command [list updateaction $w] +vwait yud($w) +$w yview moveto $fraction + +## Example 4: +# init +set todo($w) {} +proc updateaction w { +\&foreach cmd $::todo($w) {uplevel #0 $cmd} +\&set todo($w) {} +} +# runtime +lappend todo($w) [list $w yview moveto $fraction] +$w sync -command [list updateaction $w] + +## Example 5: +# init +set todo($w) {} +bind $w <<WidgetViewSync>> { +\&if {%d} { +\&\&foreach cmd $todo(%W) {eval $cmd} +\&\&set todo(%W) {} +\&} +} +# runtime +if {![$w pendingsync]} { +\&$w yview moveto $fraction +} else { +\&lappend todo($w) [list $w yview moveto $fraction] +} +.CE .SH "WIDGET COMMAND" .PP The \fBtext\fR command creates a new Tcl command whose name is the same as the @@ -981,7 +1058,9 @@ if the text widget is managed by a geometry manager), then all subsequent options ensure that any possible out of date information is recalculated. This currently only has any effect for the \fB\-ypixels\fR count (which, if \fB\-update\fR is not given, will use the text widget's current cached value -for each line). The count options are interpreted as follows: +for each line). This \fB\-update\fR option is obsoleted by \fIpathName +\fBsync\fR, \fIpathName \fBpendingsync\fR and \fB<<WidgetViewSync>>\fR. The +count options are interpreted as follows: .RS .IP \fB\-chars\fR count all characters, whether elided or not. Do not count embedded windows or @@ -1344,13 +1423,16 @@ Returns a list of peers of this widget (this does not include the widget itself). The order within this list is undefined. .RE .TP -\fIpathName \fBreplace \fIindex1 index2 chars\fR ?\fItagList chars tagList ...\fR? -. -Replaces the range of characters between \fIindex1\fR and \fIindex2\fR with -the given characters and tags. See the section on \fIpathName \fBinsert\fR for -an explanation of the handling of the \fItagList...\fR arguments, and the -section on \fIpathName \fBdelete\fR for an explanation of the handling of the -indices. If \fIindex2\fR corresponds to an index earlier in the text than +\fIpathName \fBpendingsync\fR +Returns 1 if the line heights calculations are not up-to-date, 0 otherwise. +.TP +\fIpathName \fBreplace\fR \fIindex1 index2 chars\fR ?\fItagList chars tagList ...\fR? +Replaces the range of characters between \fIindex1\fR and \fIindex2\fR +with the given characters and tags. See the section on \fIpathName +\fBinsert\fR for an explanation of the handling of the \fItagList...\fR +arguments, and the section on \fIpathName +\fBdelete\fR for an explanation of the handling of the indices. If +\fIindex2\fR corresponds to an index earlier in the text than \fIindex1\fR, an error will be generated. .RS .PP @@ -1523,6 +1605,23 @@ the view just enough to make \fIindex\fR visible at the edge of the window. If \fIindex\fR is far out of view, then the command centers \fIindex\fR in the window. .TP +\fIpathName \fBsync\fR ?\fB-command \fIcommand\fR? +Controls the synchronization of the view of the text widget. +.RS +.TP +\fIpathName \fBsync\fR +Immediately brings the line metrics up-to-date by forcing computation of any +outdated line heights. The command returns immediately if there is no such +outdated line heights, otherwise it returns only at the end of the computation. +The command returns an empty string. +.TP +\fIpathName \fBsync -command \fIcommand\fR +Schedules \fIcommand\fR to be executed (by the event loop) exactly once as soon +as all line heights are up-to-date. If there are no pending line metrics +calculations, the scheduling is immediate. The command returns the empty +string. \fBbgerror\fR is called on \fIcommand\fR failure. +.RE +.TP \fIpathName \fBtag \fIoption \fR?\fIarg arg ...\fR? . This command is used to manipulate tags. The exact behavior of the command @@ -1992,9 +2091,8 @@ the clipboard. Control-t reverses the order of the two characters to the right of the insertion cursor. .IP [32] -Control-z (and Control-underscore on UNIX when \fBtk_strictMotif\fR is true) -undoes the last edit action if the \fB\-undo\fR option is true. Does nothing -otherwise. +Control-z undoes the last edit action if the \fB\-undo\fR option is true. +Does nothing otherwise. .IP [33] Control-Z (or Control-y on Windows) reapplies the last undone edit action if the \fB\-undo\fR option is true. Does nothing otherwise. |