Text widget documentation updated according to TIP #438

1 files changed, 92 insertions, 1 deletions

diff --git a/doc/text.n b/doc/text.n
index d2f0c82..f7cb143 100644
--- a/doc/text.n
+++ b/doc/text.n
@@ -1060,6 +1060,82 @@ affected.
 See below for the \fIpathName \fBpeer\fR widget command that controls the
 creation of peer widgets.
 .VE 8.5
+.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:
+# runtime, immediately complete line metrics at any cost (GUI unresponsive)
+$w sync
+$w yview moveto $fraction
+
+## Example 2:
+# runtime, synchronously wait for up-to-date line metrics (GUI responsive)
+$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
@@ -1132,7 +1208,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 \fI\-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
@@ -1508,6 +1586,9 @@ 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 \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
@@ -1701,6 +1782,16 @@ 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?
+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. If \fB-command \fIcommand\fR is specified,
+schedule \fIcommand\fR to be executed exactly once as soon as all line
+calculations are up-to-date. If there are no pending line metrics calculations,
+\fIcommand\fR is executed immediately. \fIpathName \fBsync -command
+\fIcommand\fR returns the return value of \fIcommand\fR.
+.TP
 \fIpathName \fBtag \fIoption \fR?\fIarg arg ...\fR?
 This command is used to manipulate tags.  The exact behavior of the
 command depends on the \fIoption\fR argument that follows the