diff options
Diffstat (limited to 'doc/text.n')
| -rw-r--r-- | doc/text.n | 92 |
1 files changed, 47 insertions, 45 deletions
@@ -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 |