Pulling changes from trunkcore_zip_vfs

1 files changed, 240 insertions, 54 deletions

diff --git a/doc/text.n b/doc/text.n
index e55c4a0..860fa30 100644
--- a/doc/text.n
+++ b/doc/text.n
@@ -4,7 +4,7 @@
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
+'\"
 .TH text n 8.5 Tk "Tk Built-In Commands"
 .so man.macros
 .BS
@@ -486,6 +486,16 @@ much the line should be indented from the left edge of the window.
 option is only used when wrapping is enabled, and it only applies to the
 second and later display lines for a text line.
 .TP
+\fB\-lmargincolor \fIcolor\fR
+.
+\fIColor\fR specifies the background color to use in regions that do not
+contain characters because they are indented by \fB\-lmargin1\fR or
+\fB\-lmargin2\fR. It may have any of the forms accepted by
+\fBTk_GetColor\fR. If \fIcolor\fR has not been specified, or if it is
+specified as an empty string, then the color used is specified by the
+\fB-background\fR tag option (or, if this is also unspecified, by the
+\fB-background\fR widget option).
+.TP
 \fB\-offset \fIpixels\fR
 .
 \fIPixels\fR specifies an amount by which the text's baseline should be offset
@@ -500,6 +510,13 @@ Specifies whether or not to draw a horizontal rule through the middle of
 characters. \fIBoolean\fR may have any of the forms accepted by
 \fBTcl_GetBoolean\fR.
 .TP
+\fB\-overstrikefg \fIcolor\fR
+.
+\fIColor\fR specifies the color to use when displaying the overstrike. It may
+have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not
+been specified, or if it is specified as an empty string, then the color
+specified by the \fB\-foreground\fR tag option is used.
+.TP
 \fB\-relief \fIrelief\fR
 .
 \fIRelief\fR specifies the relief style to use for drawing the border, in any
@@ -517,6 +534,29 @@ option is only used when wrapping is enabled. If a text line wraps, the right
 margin for each line on the display is determined by the first non-elided
 character of that display line.
 .TP
+\fB\-rmargincolor \fIcolor\fR
+.
+\fIColor\fR specifies the background color to use in regions that do not
+contain characters because they are indented by \fB\-rmargin1\fR. It may
+have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not
+been specified, or if it is specified as an empty string, then the color
+used is specified by the \fB-background\fR tag option (or, if this is also
+unspecified, by the \fB-background\fR widget option).
+.TP
+\fB\-selectbackground \fIcolor\fR
+\fIColor\fR specifies the background color to use when displaying selected
+items. It may have any of the forms accepted by \fBTk_GetColor\fR. If
+\fIcolor\fR has not been specified, or if it is specified as an empty
+string, then the color specified by the \fB\-background\fR tag option is
+used.
+.TP
+\fB\-selectforeground \fIcolor\fR
+\fIColor\fR specifies the foreground color to use when displaying selected
+items. It may have any of the forms accepted by \fBTk_GetColor\fR. If
+\fIcolor\fR has not been specified, or if it is specified as an empty
+string, then the color specified by the \fB\-foreground\fR tag option is
+used.
+.TP
 \fB\-spacing1 \fIpixels\fR
 .
 \fIPixels\fR specifies how much additional space should be left above each
@@ -559,6 +599,13 @@ unspecified for the tag (the default).
 \fIBoolean\fR specifies whether or not to draw an underline underneath
 characters. It may have any of the forms accepted by \fBTcl_GetBoolean\fR.
 .TP
+\fB\-underlinefg \fIcolor\fR
+.
+\fIColor\fR specifies the color to use when displaying the underline. It may
+have any of the forms accepted by \fBTk_GetColor\fR. If \fIcolor\fR has not
+been specified, or if it is specified as an empty string, then the color
+specified by the \fB\-foreground\fR tag option is used.
+.TP
 \fB\-wrap \fImode\fR
 .
 \fIMode\fR specifies how to handle lines that are wider than the text's
@@ -634,15 +681,23 @@ embedded window annotation causes a window to be displayed at a particular
 point in the text. There may be any number of embedded windows in a text
 widget, and any widget may be used as an embedded window (subject to the usual
 rules for geometry management, which require the text window to be the parent
-of the embedded window or a descendant of its parent). The embedded window's
-position on the screen will be updated as the text is modified or scrolled,
-and it will be mapped and unmapped as it moves into and out of the visible
-area of the text widget. Each embedded window occupies one unit's worth of
-index space in the text widget, and it may be referred to either by the name
-of its embedded window or by its position in the widget's index space. If the
-range of text containing the embedded window is deleted then the window is
-destroyed. Similarly if the text widget as a whole is deleted, then the window
-is destroyed.
+of the embedded window or a descendant of its parent).
+.PP
+The embedded window's position on the screen will be updated as the text is
+modified or scrolled, and it will be mapped and unmapped as it moves into and
+out of the visible area of the text widget. Each embedded window occupies one
+unit's worth of index space in the text widget, and it may be referred to
+either by the name of its embedded window or by its position in the widget's
+index space. If the range of text containing the embedded window is deleted
+then the window is destroyed. Similarly if the text widget as a whole is
+deleted, then the window is destroyed.
+.PP
+Eliding an embedded window immediately after scheduling it for creation via
+\fIpathName \fBwindow create \fIindex \fB-create\fR will prevent it from being
+effectively created. Uneliding an elided embedded window scheduled for creation
+via \fIpathName \fBwindow create \fIindex \fB-create\fR will automatically
+trigger the associated creation script. After destroying an elided embedded
+window, the latter won't get automatically recreated.
 .PP
 When an embedded window is added to a text widget with the \fIpathName
 \fBwindow create\fR widget command, several configuration options may be
@@ -706,13 +761,22 @@ The final form of annotation in text widgets is an embedded image. Each
 embedded image annotation causes an image to be displayed at a particular
 point in the text. There may be any number of embedded images in a text
 widget, and a particular image may be embedded in multiple places in the same
-text widget. The embedded image's position on the screen will be updated as
-the text is modified or scrolled. Each embedded image occupies one unit's
-worth of index space in the text widget, and it may be referred to either by
-its position in the widget's index space, or the name it is assigned when the
-image is inserted into the text widget with \fIpathName \fBimage create\fR. If
-the range of text containing the embedded image is deleted then that copy of
-the image is removed from the screen.
+text widget.
+.PP
+The embedded image's position on the screen will be updated as the text is
+modified or scrolled. Each embedded image occupies one unit's worth of index
+space in the text widget, and it may be referred to either by its position in
+the widget's index space, or the name it is assigned when the image is inserted
+into the text widget with \fIpathName \fBimage create\fR. If the range of text
+containing the embedded image is deleted then that copy of the image is removed
+from the screen.
+.PP
+Eliding an embedded image immediately after scheduling it for creation via
+\fIpathName \fBimage create \fIindex \fB-create\fR will prevent it from being
+effectively created. Uneliding an elided embedded image scheduled for creation
+via \fIpathName \fBimage create \fIindex \fB-create\fR will automatically
+trigger the associated creation script. After destroying an elided embedded
+image, the latter won't get automatically recreated.
 .PP
 When an embedded image is added to a text widget with the \fIpathName \fBimage
 create\fR widget command, a name unique to this instance of the image is
@@ -835,6 +899,9 @@ separator is already present at the top of the undo stack no other will be
 inserted. That means that two separators on the undo stack are always
 separated by at least one insert or delete action.
 .PP
+The \fB<<UndoStack>>\fR virtual event is generated every time the undo stack
+or the redo stack becomes empty or unempty.
+.PP
 The undo mechanism is also linked to the modified flag. This means that
 undoing or redoing changes can take a modified text widget back to the
 unmodified state or vice versa. The modified flag will be set automatically to
@@ -900,6 +967,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 become 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
@@ -959,11 +1103,14 @@ each counting option given. Valid counting options are \fB\-chars\fR,
 \fB\-displaychars\fR, \fB\-displayindices\fR, \fB\-displaylines\fR,
 \fB\-indices\fR, \fB\-lines\fR, \fB\-xpixels\fR and \fB\-ypixels\fR. The
 default value, if no option is specified, is \fB\-indices\fR. There is an
-additional possible option \fB\-update\fR which is a modifier. If given, 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:
+additional possible option \fB\-update\fR which is a modifier. If given (and
+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). 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
@@ -1031,22 +1178,30 @@ test suite.
 .TP
 \fIpathName \fBdelete \fIindex1 \fR?\fIindex2 ...\fR?
 .
-Delete a range of characters from the text. If both \fIindex1\fR and
-\fIindex2\fR are specified, then delete all the characters starting with the
-one given by \fIindex1\fR and stopping just before \fIindex2\fR (i.e. the
-character at \fIindex2\fR is not deleted). If \fIindex2\fR does not specify a
-position later in the text than \fIindex1\fR then no characters are deleted.
-If \fIindex2\fR is not specified then the single character at \fIindex1\fR is
-deleted. It is not allowable to delete characters in a way that would leave
-the text without a newline as the last character. The command returns an empty
-string. If more indices are given, multiple ranges of text will be deleted.
-All indices are first checked for validity before any deletions are made. They
-are sorted and the text is removed from the last range to the first range so
-deleted text does not cause an undesired index shifting side-effects. If
-multiple ranges with the same start index are given, then the longest range is
-used. If overlapping ranges are given, then they will be merged into spans
-that do not cause deletion of text outside the given ranges due to text
-shifted during deletion.
+Delete a range of characters from the text.
+If both \fIindex1\fR and \fIindex2\fR are specified, then delete
+all the characters starting with the one given by \fIindex1\fR
+and stopping just before \fIindex2\fR (i.e. the character at
+\fIindex2\fR is not deleted).
+If \fIindex2\fR does not specify a position later in the text
+than \fIindex1\fR then no characters are deleted.
+If \fIindex2\fR is not specified then the single character at
+\fIindex1\fR is deleted.
+Attempts to delete characters in a way that would leave
+the text without a newline as the last character will be tweaked by the
+text widget to avoid this. In particular, deletion of complete lines of
+text up to the end of the text will also delete the newline character just
+before the deleted block so that it is replaced by the new final newline
+of the text widget.
+The command returns an empty string.
+If more indices are given, multiple ranges of text will be deleted.
+All indices are first checked for validity before any deletions are made.
+They are sorted and the text is removed from the last range to the
+first range so deleted text does not cause an undesired index shifting
+side-effects.  If multiple ranges with the same start index are given,
+then the longest range is used.  If overlapping ranges are given, then
+they will be merged into spans that do not cause deletion of text
+outside the given ranges due to text shifted during deletion.
 .TP
 \fIpathName \fBdlineinfo \fIindex\fR
 .
@@ -1071,8 +1226,8 @@ including \fIindex2\fR, including the text and information about marks, tags,
 and embedded windows. If \fIindex2\fR is not specified, then it defaults to
 one character past \fIindex1\fR. The information is returned in the following
 format:
-.LP
 .RS
+.LP
 \fIkey1 value1 index1 key2 value2 index2\fR ...
 .LP
 The possible \fIkey\fR values are \fBtext\fR, \fBmark\fR, \fBtagon\fR,
@@ -1132,6 +1287,16 @@ behavior of the command depends on the \fIoption\fR argument that follows the
 supported:
 .RS
 .TP
+\fIpathName \fBedit canredo\fR
+.
+Returns a boolean true if redo is possible, i.e. when the redo stack is not
+empty. Otherwise returns false.
+.TP
+\fIpathName \fBedit canundo\fR
+.
+Returns a boolean true if undo is possible, i.e. when the undo stack is not
+empty. Otherwise returns false.
+.TP
 \fIpathName \fBedit modified \fR?\fIboolean\fR?
 .
 If \fIboolean\fR is not specified, returns the modified flag of the widget.
@@ -1142,8 +1307,9 @@ of the widget to \fIboolean\fR.
 \fIpathName \fBedit redo\fR
 .
 When the \fB\-undo\fR option is true, reapplies the last undone edits provided
-no other edits were done since then. Generates an error when the redo stack is
-empty. Does nothing when the \fB\-undo\fR option is false.
+no other edits were done since then, and returns a list of indices indicating
+what ranges were changed by the redo operation. Generates an error when the
+redo stack is empty. Does nothing when the \fB\-undo\fR option is false.
 .TP
 \fIpathName \fBedit reset\fR
 .
@@ -1156,9 +1322,10 @@ Inserts a separator (boundary) on the undo stack. Does nothing when the
 .TP
 \fIpathName \fBedit undo\fR
 .
-Undoes the last edit action when the \fB\-undo\fR option is true. An edit
-action is defined as all the insert and delete commands that are recorded on
-the undo stack in between two separators. Generates an error when the undo
+Undoes the last edit action when the \fB\-undo\fR option is true, and returns a
+list of indices indicating what ranges were changed by the undo operation. An
+edit action is defined as all the insert and delete commands that are recorded
+on the undo stack in between two separators. Generates an error when the undo
 stack is empty. Does nothing when the \fB\-undo\fR option is false.
 .RE
 .TP
@@ -1326,13 +1493,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
@@ -1505,6 +1675,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
@@ -1974,9 +2161,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.