summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/text.n92
1 files changed, 47 insertions, 45 deletions
diff --git a/doc/text.n b/doc/text.n
index 5718c7e..9ec3b5e 100644
--- a/doc/text.n
+++ b/doc/text.n
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: text.n,v 1.20 2003/11/07 15:36:26 vincentdarley Exp $
+'\" RCS: @(#) $Id: text.n,v 1.21 2003/11/15 02:41:41 jenglish Exp $
'\"
.so man.macros
.TH text n 8.4 Tk "Tk Built-In Commands"
@@ -283,7 +283,7 @@ to the last index position in the text. Spaces on either side of
\fIcount\fR are optional. Note that an index position is either a single
character or a single embedded image or embedded window. If the
\fIdisplay\fB submodifier is given, elided indices are skipped over
-without being counted. If \fIany\fB is given, then all indices are
+without being counted. If \fIany\fR is given, then all indices are
counted, which is also the default behaviour if no modifier is given.
.TP
\fB\- \fIcount\fB \fI?submodifier?\fB indices\fR
@@ -293,7 +293,7 @@ earlier lines in the text if necessary. If there are fewer than
set the index to the first index position (1.0) in the text. Spaces on
either side of \fIcount\fR are optional. If the \fIdisplay\fB
submodifier is given, elided indices are skipped over without being
-counted. If \fIany\fB is given, then all indices are counted, which is
+counted. If \fIany\fR is given, then all indices are counted, which is
also the default behaviour if no modifier is given.
.TP
\fB+ \fIcount\fB \fI?modifier?\fB lines\fR
@@ -306,7 +306,7 @@ character position, adjust the character position to refer to the last
character of the line (the newline). Spaces on either side of
\fIcount\fR are optional. If the \fIdisplay\fB submodifier is given,
then each visual display line is counted separately. Otherwise, if
-\fIany\fB (or no modifier) is given, then each logical line (no matter
+\fIany\fR (or no modifier) is given, then each logical line (no matter
how many times it is visually wrapped) counts just once. If the relevant
lines are not wrapped, then these two methods of counting are equivalent.
.TP
@@ -320,32 +320,32 @@ the indicated character position, adjust the character position to refer
to the last character of the line (the newline). Spaces on either side
of \fIcount\fR are optional. If the \fIdisplay\fB submodifier is given,
then each visual display line is counted separately. Otherwise, if
-\fIany\fB (or no modifier) is given, then each logical line (no matter
+\fIany\fR (or no modifier) is given, then each logical line (no matter
how many times it is visually wrapped) counts just once. If the relevant
lines are not wrapped, then these two methods of counting are equivalent.
.TP
\fB?submodifier? linestart\fR
Adjust the index to refer to the first character on the line. If the
-\fIdisplay\fB submodifier is given, this is the first character on the
+\fIdisplay\fR submodifier is given, this is the first character on the
display line, otherwise on the logical line.
.TP
\fB?submodifier? lineend\fR
Adjust the index to refer to the last character on the line (the
-newline). If the \fIdisplay\fB submodifier is given, this is the last
+newline). If the \fIdisplay\fR submodifier is given, this is the last
character on the display line, otherwise on the logical line.
.TP
\fB?submodifier? wordstart\fR
Adjust the index to refer to the first character of the word containing
the current index. A word consists of any number of adjacent characters
that are letters, digits, or underscores, or a single character that is
-not one of these. If the \fIdisplay\fB submodifier is given, this only
+not one of these. If the \fIdisplay\fR submodifier is given, this only
examines non-elided characters, otherwise all characters (elided or not)
are examined.
.TP
\fB?submodifier? wordend\fR
Adjust the index to refer to the character just after the last one of the
word containing the current index. If the current index refers to the
-last character of the text then it is not modified. If the \fIdisplay\fB
+last character of the text then it is not modified. If the \fIdisplay\fR
submodifier is given, this only examines non-elided characters, otherwise
all characters (elided or not) are examined.
.PP
@@ -889,10 +889,11 @@ this case the command returns an empty string.
\fIOption\fR may have any of the values accepted by the \fBtext\fR
command.
.TP
-\fIpathName \fBcount \fI?options\fI? \fIindex1 \fIindex2\fR Counts the
-number of relevant things between the two indices. If index1 is after
-index2, the result will be a negative number (and this holds for each of
-the possible options). The actual items which are counted depend on the
+\fIpathName \fBcount \fI?options\fI? \fIindex1 \fIindex2\fR
+Counts the number of relevant things between the two indices.
+If \fIindex1\fP is after \fIindex2\fP, the result will be a negative number
+(and this holds for each of the possible options).
+The actual items which are counted depend on the
options given. The result is a list of integers, one for the result of
each counting option given. Valid counting options are \fI-chars\fR,
\fI-displaychars\fR, \fI-displayindices\fR, \fI-displaylines\fR,
@@ -904,51 +905,52 @@ information is recalculated. This currently only has any effect for the
\fI-ypixels\fR count (which, if 'update' is not given, will use the text
widget's current cached value for each line). The count options are
interpreted as follows:
-.TP
-\fI-chars\fR - count all characters, whether elided or not. Do not count
+.RS
+.IP \fI-chars\fR
+count all characters, whether elided or not. Do not count
embedded windows or images.
-.TP
-\fI-displaychars\fR - count all non-elided characters.
-.TP
-\fI-displayindices\fR - count all non-elided characters, windows and
-images.
-.TP
-\fI-displaylines\fR - count all display lines (i.e. counting one for each
+.IP \fI-displaychars\fR
+count all non-elided characters.
+.IP \fI-displayindices\fR
+count all non-elided characters, windows and images.
+.IP \fI-displaylines\fR
+count all display lines (i.e. counting one for each
time a line wraps) from the line of the first index up to, but not
including the display line of the second index. Therefore if they are
both on the same display line, zero will be returned. By definition
displaylines are visible and therefore this only counts portions of
actual visible lines.
-.TP
-\fI-indices\fR - count all characters and embedded windows or images (i.e.
+.IP \fI-indices\fR
+count all characters and embedded windows or images (i.e.
everything which counts in text-widget index space), whether they are
elided or not.
-.TP
-\fI-lines\fR - count all logical lines (irrespective of wrapping) from
+.IP \fI-lines\fR
+count all logical lines (irrespective of wrapping) from
the line of the first index up to, but not including the line of the
second index. Therefore if they are both on the same line, zero will be
returned. Logical lines are counted whether they are currently visible
(non-elided) or not.
-.TP
-\fI-xpixels\fR - count the number of horizontal pixels from the first
+.IP \fI-xpixels\fR
+count the number of horizontal pixels from the first
pixel of the first index to (but not including) the first pixel of the
second index. To count the total desired width of the text widget
(assuming wrapping is not enabled), first find the longest line and then
use '.text count -xpixels "${line}.0" "${line}.0 lineend"'.
-.TP
-\fI-ypixels\fR - count the number of vertical pixels from the first pixel
+.IP \fI-ypixels\fR
+count the number of vertical pixels from the first pixel
of the first index to (but not including) the first pixel of the second
index. If both indices are on the same display line, zero will be
returned. To count the total number of vertical pixels in the text
widget, use '.text count -ypixels 1.0 end', and to ensure this is up to
date, use '.text count -update -ypixels 1.0 end'.
-.TP
+.PP
The command returns a positive or negative integer corresponding to the
number of items counted between the two indices. One such integer is
returned for each counting option given, so a list is returned if more
than one option was supplied. For example '.text count -xpixels
-ypixels 1.3 4.5' is perfectly valid and will return a list of two
elements.
+.RE
.TP
\fIpathName \fBdebug \fR?\fIboolean\fR?
If \fIboolean\fR is specified, then it must have one of the true or
@@ -1269,7 +1271,7 @@ 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.
-.TP
+.br
The deletion and insertion are arranged so that no unnecessary
scrolling of the window or movement of insertion cursor occurs. In
addition the undo/redo stack are correctly modified, if undo operations
@@ -1359,7 +1361,7 @@ given, then \fBvarName\fR is also set to a list containing one element
for each successful match. Note that, even for exact searches, the
elements of this list may be different, if there are embedded images,
windows or hidden text. Searches with \fB\-all\fR behave very
-similarly to the Tcl command \fB\regexp -all\fR, in that overlapping
+similarly to the Tcl command \fBregexp -all\fR, in that overlapping
matches are not normally returned. For example, applying an \fB\-all\fR search
of the pattern '\\w+' against 'hello there' will just match twice, once
for each word, and matching 'Z[a-z]+Z' against 'ZooZooZoo' will just
@@ -1371,8 +1373,8 @@ matches which overlap an already-found match will not be returned. This
switch changes that behaviour so that all matches which are not totally
enclosed within another match are returned. For example, applying an
\fB\-overlap\fR search of the pattern '\\w+' against 'hello there' will
-just match twice (i.e. no different to just \fB\-all\fR), but matching
-'Z[a-z]+Z' against 'ZooZooZoo' will now match twice.
+just match twice (i.e. no different to just \fB\-all\fR),
+but matching 'Z[a-z]+Z' against 'ZooZooZoo' will now match twice.
An error will be thrown if this switch is used without \fB\-all\fR.
.TP
\fB\-elide\fR
@@ -1988,7 +1990,7 @@ limitation is that while a single logical line can result in multiple
display lines, a single display line cannot be derived from multiple
logical lines. This does mean, however, that logical lines which are
completely elided have no problems.
-
+.PP
The \fBsearch -regexp\fR sub-command attempts to perform sophisticated
regexp matching across multiple lines in an efficient fashion (since Tk
8.5), examing each line individually, and then in small groups of lines,
@@ -2005,10 +2007,10 @@ first extra line added results in no match and Tcl's regexp system
returns the incorrect code and adding a second extra line would actually
match, the text widget will return the wrong result. In practice this is
a rare problem, but it can occur, for example: \fBpack [text .t] ; .t
-insert 1.0 "aaaa\nbbbb\ncccc\nbbbb\naaaa\n" ; .t search -regexp --
-{(a+|b+\nc+\nb+)+\na+} 1.0\fR will not find a match when one exists of 19
+insert 1.0 "aaaa\\nbbbb\\ncccc\\nbbbb\\naaaa\\n" ; .t search -regexp --
+{(a+|b+\\nc+\\nb+)+\\na+} 1.0\fR will not find a match when one exists of 19
characters starting from the first 'b'.
-
+.PP
Whenever one possible match is fully enclosed in another, the search
command will attempt to ensure only the larger match is returned.
When performing backwards regexp searches it is possible that Tcl
@@ -2017,13 +2019,13 @@ one or more short, non-overlapping matches, all of which are preceded
by a large match which actually encompasses all of them. The search
algorithm used by the widget does not look back arbitrarily far for a
possible match which might cover large portions of the widget. For
-example: \fBpack [text .t] ; .t insert 1.0 "aaaa\nbbbb\nbbbb\nbbbb\nbbbb\n"
-; .t search -regexp -backward -- {b+\n|a+\n(b+\n)+} end\fR matches at
-'5.0' when a true greedy match would match at '1.0'. Similarly if we
-add \fB-all\fR to this case, it matches at all of '5.0', '4.0', '3.0'
-and '1.0', when really it should only match at '1.0' since that match
+example: \fBpack [text .t] ; .t insert 1.0 "aaaa\\nbbbb\\nbbbb\\nbbbb\\nbbbb\\n"
+; .t search -regexp -backward -- {b+\\n|a+\\n(b+\\n)+} end\fR
+matches at '5.0' when a true greedy match would match at '1.0'.
+Similarly if we add \fB-all\fR to this case, it matches at
+all of '5.0', '4.0', '3.0' and '1.0',
+when really it should only match at '1.0' since that match
encloses all the others.
-
.SH KEYWORDS
text, widget, tkvars