From 8ee91ddf641d2de19f85f92f4d04edbf48f554d1 Mon Sep 17 00:00:00 2001 From: dkf Date: Tue, 16 Oct 2007 15:13:17 +0000 Subject: Text widget documentation improvements --- ChangeLog | 5 ++ doc/text.n | 207 +++++++++++++++++++++++++++++++------------------------------ 2 files changed, 110 insertions(+), 102 deletions(-) diff --git a/ChangeLog b/ChangeLog index 2014d3b..1ab57b9 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2007-10-16 Donal K. Fellows + + * doc/text.n: Made it clearer what things are text widget invokations + and what are not. Also some other clarity improvements. + 2007-10-15 Donal K. Fellows * library/demos/widget: Use Ttk widgets for the widget demo core, for diff --git a/doc/text.n b/doc/text.n index f2cc083..e9d6cdd 100644 --- a/doc/text.n +++ b/doc/text.n @@ -4,9 +4,9 @@ '\" '\" 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.43 2006/11/15 13:29:17 dkf Exp $ -'\" +'\" +'\" RCS: @(#) $Id: text.n,v 1.44 2007/10/16 15:13:18 dkf Exp $ +'\" .so man.macros .TH text n 8.5 Tk "Tk Built-In Commands" .BS @@ -36,8 +36,8 @@ inserted in the undo stack. Only meaningful when the \fB\-undo\fR option is true. .OP \-blockcursor blockCursor BlockCursor .VS 8.5 -Specifies a boolean that says whether the blinking insertion cursor -should be drawn as a character-sized rectangular block. If false +Specifies a boolean that says whether the blinking insertion cursor +should be drawn as a character-sized rectangular block. If false (the default) a thin vertical line is used for the insertion cursor. .VE 8.5 .OP \-endline endLine EndLine @@ -114,21 +114,21 @@ following the tab character is positioned at the tab position, and at the tab position; if there is no decimal point then the least significant digit of the number is positioned just to the left of the tab position; if there is no number in the text then the text is -right-justified at the tab position. +right-justified at the tab position. For example, \fB\-tabs {2c left 4c 6c center}\fR creates three tab stops at two-centimeter intervals; the first two use left -justification and the third uses center justification. +justification and the third uses center justification. If the list of tab stops does not have enough elements to cover all of the tabs in a text line, then Tk extrapolates new tab stops using the spacing and alignment from the last tab stop in the list. Tab -distances must be strictly positive, and must always increase from one +distances must be strictly positive, and must always increase from one tab stop to the next (if not, an error is thrown). The value of the \fBtabs\fR option may be overridden by \fB\-tabs\fR options in tags. If no \fB\-tabs\fR option is specified, or if it is specified as an empty list, then Tk uses default tabs spaced every eight (average size) characters. To achieve a different standard spacing, -for example every 4 characters, simply configure the widget with +for example every 4 characters, simply configure the widget with \fB\-tabs "[expr {4 * [font measure $font 0]}] left" -tabstyle wordprocessor\fR. .OP \-tabstyle tabStyle TabStyle Specifies how to interpret the relationship between tab stops on a line @@ -379,8 +379,8 @@ lines are not wrapped, then these two methods of counting are equivalent. .TP ?\fIsubmodifier\fR? \fBlinestart\fR .VS 8.5 -Adjust the index to refer to the first index on the line. If the -\fBdisplay\fR submodifier is given, this is the first index on the +Adjust the index to refer to the first index on the line. If the +\fBdisplay\fR submodifier is given, this is the first index on the display line, otherwise on the logical line. .VE 8.5 .TP @@ -415,8 +415,8 @@ refers to the next-to-last character in the text and ``\fBinsert wordstart \- 1 c\fR'' refers to the character just before the first one in the word containing the insertion cursor. Modifiers are applied one by one in this left to right order, and after each step -the resulting index is constrained to be a valid index in the text -widget. So, for example, the index ``\fB1.0 -1c +1c\fR'' refers to the +the resulting index is constrained to be a valid index in the text +widget. So, for example, the index ``\fB1.0 -1c +1c\fR'' refers to the index ``\fB2.0\fR''. .PP Where modifiers result in index changes by display lines, display chars @@ -452,7 +452,7 @@ widget commands. Tags serve three purposes in text widgets. First, they control the way information is displayed on the screen. By default, characters are displayed as determined by the -\fBbackground\fR, \fBfont\fR, and \fBforeground\fR options for the +\fB\-background\fR, \fB\-font\fR, and \fB\-foreground\fR options for the text widget. However, display options may be associated with individual tags using the ``\fIpathName \fBtag configure\fR'' widget command. @@ -482,7 +482,7 @@ option to give a 3-D appearance to the background for characters; it is ignored unless the \fB\-background\fR option has been set for the tag. .TP -\fB\-elide \fIboolean\fR +\fB\-elide \fIboolean\fR \fIElide\fR specifies whether the data should be elided. Elided data (characters, images, embedded windows, etc) is not displayed and takes no space on screen, but further on behaves just @@ -598,11 +598,11 @@ If this option is specified as an empty string, it cancels the option, leaving it unspecified for the tag (the default). If the option is specified as a non-empty string that is an empty list, such as \fB\-tags\0{\0}\fR, then it requests -default 8-character tabs as described for the \fBtags\fR +default 8-character tabs as described for the \fB\-tags\fR widget option. .TP \fB\-tabstyle \fIstyle\fR -\fIStyle\fR specifies either the \fItabular\fR or +\fIStyle\fR specifies either the \fItabular\fR or \fIwordprocessor\fR style of tabbing to use for the text widget. This option only applies to a display line if it applies to the first non-elided character on that display line. @@ -640,7 +640,7 @@ Tcl command will be executed. Tag bindings can be used to give behaviors to ranges of characters; among other things, this allows hypertext-like features to be implemented. -For details, see the description of the \fBtag bind\fR widget +For details, see the description of the ``\fIpathName \fBtag bind\fR'' widget command below. .VS 8.5 Tag bindings are shared between all peer widgets @@ -702,7 +702,7 @@ until all mouse buttons have been released). Neither of these special marks may be deleted. .VS 8.5 With the exception of -these two special marks, all marks are shared between peer text +these two special marks, all marks are shared between peer text widgets, and may be manipulated on an equal basis from any peer. .VE 8.5 .SH "EMBEDDED WINDOWS" @@ -734,9 +734,9 @@ destroyed. .VE 8.5 .PP When an embedded window is added to a text widget with the -\fBwindow create\fR widget command, several configuration +\fIpathName \fBwindow create\fR widget command, several configuration options may be associated with it. -These options may be modified later with the \fBwindow configure\fR +These options may be modified later with the \fIpathName \fBwindow configure\fR widget command. The following options are currently supported: .TP @@ -812,11 +812,11 @@ 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 \fBimage create\fR. +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 -When an embedded image is added to a text widget with the \fBimage +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 returned. This name may then be used to refer to this image instance. The name is taken to be the value of the \fB\-name\fR option @@ -825,14 +825,14 @@ instance. The name is taken to be the value of the \fB\-name\fR option in use in the text widget, then \fB#\fInn\fR is added to the end of the \fIimageName\fR, where \fInn\fR is an arbitrary integer. This insures the \fIimageName\fR is unique. -Once this name is assigned to this instance of the image, it does not +Once this name is assigned to this instance of the image, it does not change, even though the \fB\-image\fR or \fB\-name\fR values can be changed -with \fBimage configure\fR. +with \fIpathName \fBimage configure\fR. .PP When an embedded image is added to a text widget with the -\fBimage create\fR widget command, several configuration +\fIpathName \fBimage create\fR widget command, several configuration options may be associated with it. -These options may be modified later with the \fBimage configure\fR +These options may be modified later with the \fIpathName \fBimage configure\fR widget command. The following options are currently supported: .TP @@ -883,7 +883,7 @@ If the selection is claimed away by another application or by another window within this application, then the \fBsel\fR tag will be removed from all characters in the text. .IP [4] -Whenever the \fBsel\fR tag range changes a virtual event +Whenever the \fBsel\fR tag range changes a virtual event \fB<>\fR is generated. .PP The \fBsel\fR tag is automatically defined when a text widget is @@ -897,7 +897,7 @@ other. .VS 8.5 Also the \fB\-inactiveselectionbackground\fR option for the text widget is used -instead of \fB-selectbackground\fR when the text widget does not have +instead of \fB\-selectbackground\fR when the text widget does not have the focus. This allows programmatic control over the visualization of the \fBsel\fR tag for foreground and background windows, or to have \fBsel\fR not shown at all (when \fB\-inactiveselectionbackground\fR is @@ -917,8 +917,8 @@ this point whenever the text widget has the input focus. The text widget can keep track of changes to the content of the widget by means of the modified flag. Inserting or deleting text will set this flag. The flag can be queried, set and cleared programmatically -as well. Whenever the flag changes state a \fB<>\fR virtual -event is generated. See the \fBedit modified\fR widget command for +as well. Whenever the flag changes state a \fB<>\fR virtual +event is generated. See the \fIpathName \fBedit modified\fR widget command for more details. .SH "THE UNDO MECHANISM" .PP @@ -947,7 +947,7 @@ automatically to the appropriate state. This automatic coupling does not work when the modified flag has been set by the user, until the flag has been reset again. .PP -See below for the \fBedit\fR widget command that controls the undo +See below for the \fIpathName \fBedit\fR widget command that controls the undo mechanism. .SH "PEER WIDGETS" .PP @@ -970,12 +970,12 @@ the \fBsel\fR tag may be set and configured (in its display style) differently for each peer. Second, each peer has its own \fBinsert\fR and \fBcurrent\fR mark positions (but all other marks are shared). Third, embedded windows, which are arbitrary other widgets, cannot be -shared between peers. This means the \fB-window\fR option of embedded +shared between peers. This means the \fB\-window\fR option of embedded windows is independently set for each peer (it is advisable to use -the \fB-create\fR script capabilities to allow each peer to create its +the \fB\-create\fR script capabilities to allow each peer to create its own embedded windows as needed). Fourth, all of the configuration -options of each peer (e.g. \fB-font\fR, etc) can be set independently, -with the exception of \fB-undo\fR, \fB-maxUndo\fR, \fB-autoSeparators\fR +options of each peer (e.g. \fB\-font\fR, etc) can be set independently, +with the exception of \fB\-undo\fR, \fB\-maxUndo\fR, \fB\-autoSeparators\fR (i.e. all undo, redo and modified state issues are shared). .PP Finally any single peer need not contain all lines from the underlying @@ -993,18 +993,18 @@ end lines). Note that a peer which does not contain all of the underlying data store still has indices numbered from "1.0" to "end". It is simply that those indices reflect a subset of the total data, and data outside the contained range is not accessible to the peer. This -means that the command \fB$peer index end\fR may return quite different -values in different peers. Similarly, commands like \fB$peer tag +means that the command \fIpeerName \fBindex end\fR may return quite different +values in different peers. Similarly, commands like \fIpeerName \fBtag ranges\fR will not return index ranges outside that which is meaningful -to the peer. The configuration options \fB-startline\fR and -\fB-endline\fR may be used to control how much of the underlying data is +to the peer. The configuration options \fB\-startline\fR and +\fB\-endline\fR may be used to control how much of the underlying data is contained in any given text widget. .PP Note that peers are really peers. Deleting the 'original' text widget will not cause any other peers to be deleted, or otherwise affected. .PP -See below for the \fBpeer\fR widget command that controls the creation -of peer widgets. +See below for the \fIpathName \fBpeer\fR widget command that controls the +creation of peer widgets. .VE 8.5 .SH "WIDGET COMMAND" .PP @@ -1065,7 +1065,7 @@ command. .TP \fIpathName \fBcount\fR \fI?options\fR? \fIindex1 index2\fR Counts the number of relevant things between the two indices. -If \fIindex1\fR is after \fIindex2\fR, the result will be a negative number +If \fIindex1\fR is after \fIindex2\fR, 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 @@ -1080,37 +1080,37 @@ information is recalculated. This currently only has any effect for the widget's current cached value for each line). The count options are interpreted as follows: .RS -.IP \fB\-chars\fR +.IP \fB\-chars\fR count all characters, whether elided or not. Do not count embedded windows or images. -.IP \fB\-displaychars\fR +.IP \fB\-displaychars\fR count all non-elided characters. -.IP \fB\-displayindices\fR +.IP \fB\-displayindices\fR count all non-elided characters, windows and images. -.IP \fB\-displaylines\fR +.IP \fB\-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. -.IP \fB\-indices\fR +.IP \fB\-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. -.IP \fB\-lines\fR +.IP \fB\-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. -.IP \fB\-xpixels\fR +.IP \fB\-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"'. -.IP \fB\-ypixels\fR +.IP \fB\-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 @@ -1118,9 +1118,9 @@ 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'. .PP -The command returns a positive or negative integer corresponding to the +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 +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. @@ -1141,11 +1141,13 @@ There is a single debugging switch shared by all text widgets: turning debugging on or off in any widget turns it on or off for all widgets. For widgets with large amounts of text, the consistency checks may cause a noticeable slow-down. +.RS .PP When debugging is turned on, the drawing routines of the text widget set the global variables \fBtk_textRedraw\fR and \fBtk_textRelayout\fR to the lists of indices that are redrawn. The values of these variables are tested by Tk's test suite. +.RE .TP \fIpathName \fBdelete \fIindex1 \fR?\fIindex2 ...\fR? Delete a range of characters from the text. @@ -1294,10 +1296,10 @@ If the specified range contains embedded windows, no information about them is included in the returned string. If multiple index pairs are given, multiple ranges of text will be returned in a list. Invalid ranges will not be represented with empty strings in -the list. The ranges are returned in the order passed to \fBget\fR. +the list. The ranges are returned in the order passed to \fIpathName \fBget\fR. .VS 8.5 If the \fB\-displaychars\fR option is given, then, within each range, -only those characters which are not elided will be returned. This may +only those characters which are not elided will be returned. This may have the effect that some of the returned ranges are empty strings. .VE 8.5 .TP @@ -1366,7 +1368,7 @@ tag names; the new characters will receive all of the tags in this list and no others, regardless of the tags present around the insertion point. If multiple \fIchars\fR\-\fItagList\fR argument pairs are present, -they produce the same effect as if a separate \fBinsert\fR widget +they produce the same effect as if a separate \fIpathName \fBinsert\fR widget command had been issued for each pair, in order. The last \fItagList\fR argument may be omitted. .TP @@ -1398,9 +1400,9 @@ This can still return a mark at the same position if there are multiple marks at the same index. These semantics mean that the \fBmark next\fR operation can be used to step through all the marks in a text widget in the same order -as the mark information returned by the \fBdump\fR operation. +as the mark information returned by the \fIpathName \fBdump\fR operation. If a mark has been set to the special \fBend\fR index, -then it appears to be \fIafter\fR \fBend\fR with respect to the \fBmark next\fR operation. +then it appears to be \fIafter\fR \fBend\fR with respect to the \fIpathName \fBmark next\fR operation. An empty string is returned if there are no marks after \fIindex\fR. .TP \fIpathName \fBmark previous \fIindex\fR @@ -1411,9 +1413,9 @@ If \fIindex\fR is the name of a mark, then the search for the next mark begins immediately before that mark. This can still return a mark at the same position if there are multiple marks at the same index. -These semantics mean that the \fBmark previous\fR operation can be used to +These semantics mean that the \fIpathName \fBmark previous\fR operation can be used to step through all the marks in a text widget in the reverse order -as the mark information returned by the \fBdump\fR operation. +as the mark information returned by the \fIpathName \fBdump\fR operation. An empty string is returned if there are no marks before \fIindex\fR. .TP \fIpathName \fBmark set \fImarkName index\fR @@ -1449,7 +1451,7 @@ itself). The order within this list is undefined. .RE .TP \fIpathName \fBreplace\fR \fIindex1 index2 chars\fR ?\fItagList chars tagList ...\fR? -Replaces the range of characters between \fIindex1\fR and \fIindex2\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 @@ -1470,14 +1472,14 @@ two forms, depending on \fIoption\fR: .TP \fIpathName \fBscan mark \fIx y\fR Records \fIx\fR and \fIy\fR and the current view in the text window, -for use in conjunction with later \fBscan dragto\fR commands. +for use in conjunction with later \fIpathName \fBscan dragto\fR commands. Typically this command is associated with a mouse button press in the widget. It returns an empty string. .TP \fIpathName \fBscan dragto \fIx y\fR This command computes the difference between its \fIx\fR and \fIy\fR arguments and the \fIx\fR and \fIy\fR arguments to the last -\fBscan mark\fR command for the widget. +\fIpathName \fBscan mark\fR command for the widget. It then adjusts the view by 10 times the difference in coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of @@ -1521,17 +1523,17 @@ the text using the rules for regular expressions (see the \fBregexp\fR command for details). .VS 8.5 The default matching automatically passes -both the \fB\-lineanchor\fR and \fB\-linestop\fR options +both the \fB\-lineanchor\fR and \fB\-linestop\fR options to the regexp engine (unless \fB\-nolinestop\fR is used), so that -\fI^$\fR match beginning and end of line, and \fI.\fR, \fI[^\fR +\fI^$\fR match beginning and end of line, and \fI.\fR, \fI[^\fR sequences will never match the newline character \fI\en\fR. .VE 8.5 .TP \fB\-nolinestop\fR .VS 8.5 -This allows \fI.\fR and \fI[^\fR sequences to match the newline +This allows \fI.\fR and \fI[^\fR sequences to match the newline character \fI\en\fR, which they will otherwise not do (see the \fBregexp\fR -command for details). This option is only meaningful if \fB\-regexp\fR +command for details). This option is only meaningful if \fB\-regexp\fR is also given, and an error will be thrown otherwise. For example, to match the entire text, use 'search \-nolinestop \-regexp ".*" 1.0'. .VE 8.5 @@ -1551,20 +1553,20 @@ number of characters matched. In either case, the range \fImatchIdx\fR to \fB\-all\fR .VS 8.5 Find all matches in the given range and return a list of the indices of -the first character of each match. If a \fB\-count\fI varName\fR switch is -given, then \fBvarName\fR is also set to a list containing one element +the first character of each match. If a \fB\-count\fI varName\fR switch is +given, then \fIvarName\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 \fBregexp \-all\fR, in that overlapping matches are not normally returned. For example, applying an -\fB\-all\fR search +\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 match once. .VE 8.5 .TP -\fB\-overlap\fR +\fB\-overlap\fR .VS 8.5 When performing \fB\-all\fR searches, the normal behaviour is that matches which overlap an already-found match will not be returned. This @@ -1572,11 +1574,11 @@ 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. +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. .VE 8.5 .TP -\fB\-strictlimits\fR +\fB\-strictlimits\fR .VS 8.5 When performing any search, the normal behaviour is that the start and stop limits are checked with respect to the @@ -1593,7 +1595,7 @@ searched. This switch has no effect except to terminate the list of switches: the next argument will be treated as \fIpattern\fR even if it starts with \fB\-\fR. -.LP +.PP .VS 8.5 The matching range may be within a single line of text, or run across multiple lines (if parts of the pattern can match a new-line). For @@ -1609,10 +1611,10 @@ If \fIstopIndex\fR is omitted, the entire text will be searched: when the beginning or end of the text is reached, the search continues at the other end until the starting location is reached again; if \fIstopIndex\fR is specified, no wrap-around will occur. -This means that, for example, if the search is \fB\-forwards\fR -but \fIstopIndex\fR is earlier in the text than \fIstartIndex\fR, +This means that, for example, if the search is \fB\-forwards\fR +but \fIstopIndex\fR is earlier in the text than \fIstartIndex\fR, nothing will ever be found. See \fBKNOWN BUGS\fR below for a number of -minor limitations of the \fBsearch\fR command. +minor limitations of the \fIpathName \fBsearch\fR command. .RE .TP \fIpathName \fBsee \fIindex\fR @@ -1669,7 +1671,7 @@ defined for \fItagName\fR. .RS .PP The only events for which bindings may be specified are those related -to the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, +to the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, \fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR) or virtual events. Event bindings for a text widget use the \fBcurrent\fR mark described under \fBMARKS\fR above. An \fBEnter\fR event triggers for a tag when the tag @@ -1705,11 +1707,11 @@ for the window as a whole. \fIpathName \fBtag cget\fR \fItagName option\fR This command returns the current value of the option named \fIoption\fR associated with the tag given by \fItagName\fR. -\fIOption\fR may have any of the values accepted by the \fBtag configure\fR -widget command. +\fIOption\fR may have any of the values accepted by the \fIpathName \fBtag +configure\fR widget command. .TP \fIpathName \fBtag configure \fItagName\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR? -This command is similar to the \fBconfigure\fR widget command except +This command is similar to the \fIpathName \fBconfigure\fR widget command except that it modifies options associated with the tag given by \fItagName\fR instead of modifying options for the overall text widget. If no \fIoption\fR is specified, the command returns a list describing @@ -1927,7 +1929,7 @@ appears at the top of the top line of the window. pixel of the first character in the text, 0.33 indicates the pixel that is one-third the way through the text; and so on. .VS 8.5 -Values close to 1 will +Values close to 1 will indicate values close to the last pixel in the text (1 actually refers to one pixel beyond the last pixel), but in such cases the widget will never scroll beyond the last pixel, and so a value of 1 will effectively @@ -1972,9 +1974,9 @@ it will be positioned at the bottom of the window. .IP [4] Otherwise, \fIindex\fR will be centered in the window. .LP -The \fB\-pickplace\fR option has been obsoleted by the \fBsee\fR widget -command (\fBsee\fR handles both x- and y-motion to make a location -visible, whereas \fB\-pickplace\fR only handles motion in y). +The \fB\-pickplace\fR option has been obsoleted by the \fIpathName \fBsee\fR widget +command (\fIpathName \fBsee\fR handles both x- and y-motion to make a location +visible, whereas the \fB\-pickplace\fR mode only handles motion in y). .RE .TP \fIpathName \fByview \fInumber\fR @@ -2067,7 +2069,7 @@ and also extends the selection to that point. .IP [14] End and Control-e move the insertion cursor to the end of the display line and clear any selection in the widget. -Shift-End moves the cursor to the end of the display line and extends +Shift-End moves the cursor to the end of the display line and extends the selection to that point. .IP [15] Control-Home and Meta-< move the insertion cursor to the beginning of @@ -2132,7 +2134,7 @@ Control-x deletes whatever is selected in the text widget after copying it to the clipboard. .IP [31] Control-t reverses the order of the two characters to the right of -the insertion cursor. +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. @@ -2148,7 +2150,8 @@ take place. .PP The behavior of texts can be changed by defining new bindings for individual widgets or by redefining the class bindings. -.SH "ISSUES CONCERNING CHARS AND INDICES" +.SH "KNOWN ISSUES" +.SS "ISSUES CONCERNING CHARS AND INDICES" .VS 8.5 .PP Before Tk 8.5, the widget used the string "chars" to refer to index @@ -2159,9 +2162,9 @@ index modifiers "+N chars" and "\-N chars" continue to refer to indices. One must use any of the full forms "+N any chars" or "\-N any chars" etc to refer to actual character indices. This confusion may be fixed in a future release by making the widget correctly interpret "+N chars" as a -synonym for "+N any chars". +synonym for "+N any chars". .VE 8.5 -.SH "PERFORMANCE ISSUES" +.SS "PERFORMANCE ISSUES" .PP Text widgets should run efficiently under a variety of conditions. The text widget uses about 2-3 bytes of @@ -2194,10 +2197,10 @@ especially if they have many marks and tags within them. The display line with the insert cursor is redrawn each time the cursor blinks, which causes a steady stream of graphics traffic. Set the \fBinsertOffTime\fR attribute to 0 avoid this. -.SH "KNOWN BUGS" +.SS "KNOWN BUGS" .VS 8.5 .PP -The \fBsearch \-regexp\fR sub-command attempts to perform sophisticated +The \fIpathName \fBsearch \-regexp\fR sub-command attempts to perform sophisticated regexp matching across multiple lines in an efficient fashion (since Tk 8.5), examining each line individually, and then in small groups of lines, whether searching forwards or backwards. Under certain conditions the @@ -2214,9 +2217,9 @@ 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: .CS - pack [text .t] - .t insert 1.0 "aaaa\\nbbbb\\ncccc\\nbbbb\\naaaa\\n" - .t search \-regexp \-\- {(a+|b+\\nc+\\nb+)+\\na+} 1.0 +pack [text .t] +\.t insert 1.0 "aaaa\\nbbbb\\ncccc\\nbbbb\\naaaa\\n" +\.t search \-regexp \-\- {(a+|b+\\nc+\\nb+)+\\na+} 1.0 .CE will not find a match when one exists of 19 characters starting from the first 'b'. @@ -2224,20 +2227,20 @@ characters starting from the first 'b'. 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 -will not always achieve this, in the case where a match is preceded by +will not always achieve this, in the case where a match is preceded by 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: .CS - pack [text .t] - .t insert 1.0 "aaaa\\nbbbb\\nbbbb\\nbbbb\\nbbbb\\n" - .t search \-regexp \-backward \-\- {b+\\n|a+\\n(b+\\n)+} end +pack [text .t] +\.t insert 1.0 "aaaa\\nbbbb\\nbbbb\\nbbbb\\nbbbb\\n" +\.t search \-regexp \-backward \-\- {b+\\n|a+\\n(b+\\n)+} end .CE -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', +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. .VE 8.5 -- cgit v0.12