1text(n)                      Tk Built-In Commands                      text(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       text,  tk_textCopy,  tk_textCut,  tk_textPaste  - Create and manipulate
9       'text' hypertext editing widgets
10

SYNOPSIS

12       text pathName ?options?
13       tk_textCopy pathName
14       tk_textCut pathName
15       tk_textPaste pathName
16

STANDARD OPTIONS

18       -background           -highlightthickness  -relief
19       -borderwidth          -insertbackground    -selectbackground
20       -cursor               -insertborderwidth   -selectborderwidth
21       -exportselection      -insertofftime       -selectforeground
22       -font                 -insertontime        -setgrid
23       -foreground           -insertwidth         -takefocus
24       -highlightbackground  -padx                -xscrollcommand
25       -highlightcolor       -pady                -yscrollcommand
26
27       See the options manual entry for details on the standard options.
28

WIDGET-SPECIFIC OPTIONS

30       Command-Line Name:-autoseparators
31       Database Name:  autoSeparators
32       Database Class: AutoSeparators
33
34              Specifies a boolean that says whether separators  are  automati‐
35              cally inserted in the undo stack. Only meaningful when the -undo
36              option is true.
37
38       Command-Line Name:-blockcursor
39       Database Name:  blockCursor
40       Database Class: BlockCursor
41
42              Specifies a boolean that says  whether  the  blinking  insertion
43              cursor  should  be drawn as a character-sized rectangular block.
44              If false (the default) a thin vertical line is used for the  in‐
45              sertion cursor.
46
47       Command-Line Name:-endline
48       Database Name:  endLine
49       Database Class: EndLine
50
51              Specifies an integer line index representing the line of the un‐
52              derlying textual data store that should be just after  the  last
53              line  contained  in the widget. This allows a text widget to re‐
54              flect only a portion of a larger piece of text.  Instead  of  an
55              integer,  the empty string can be provided to this configuration
56              option, which will configure the widget to end at the very  last
57              line in the textual data store.
58
59       Command-Line Name:-height
60       Database Name:  height
61       Database Class: Height
62
63              Specifies the desired height for the window, in units of charac‐
64              ters in the font given by the -font option.  Must  be  at  least
65              one.
66
67       Command-Line Name:-inactiveselectbackground
68       Database Name:  inactiveSelectBackground
69       Database Class: Foreground
70
71              Specifies the colour to use for the selection (the sel tag) when
72              the window does not have the input focus. If empty, {}, then  no
73              selection is shown when the window does not have the focus.
74
75       Command-Line Name:-insertunfocussed
76       Database Name:  insertUnfocussed
77       Database Class: InsertUnfocussed
78
79              Specifies  how  to  display the insertion cursor when the widget │
80              does not have the focus. Must be none (the default) which  means │
81              to  not display the cursor, hollow which means to display a hol‐ │
82              low box, or solid which means to display a solid box. Note  that │
83              hollow  and solid will appear very similar when the -blockcursor 
84              option is false.
85
86       Command-Line Name:-maxundo
87       Database Name:  maxUndo
88       Database Class: MaxUndo
89
90              Specifies the maximum number of compound  undo  actions  on  the
91              undo  stack.  A zero or a negative value imply an unlimited undo
92              stack.
93
94       Command-Line Name:-spacing1
95       Database Name:  spacing1
96       Database Class: Spacing1
97
98              Requests additional space above each text line  in  the  widget,
99              using  any of the standard forms for screen distances. If a line
100              wraps, this option only applies to the first line  on  the  dis‐
101              play.  This  option  may be overridden with -spacing1 options in
102              tags.
103
104       Command-Line Name:-spacing2
105       Database Name:  spacing2
106       Database Class: Spacing2
107
108              For lines that wrap (so that they cover more than  one  line  on
109              the  display)  this option specifies additional space to provide
110              between the display lines that represent a single line of  text.
111              The  value  may  have  any of the standard forms for screen dis‐
112              tances. This option may be overridden with -spacing2 options  in
113              tags.
114
115       Command-Line Name:-spacing3
116       Database Name:  spacing3
117       Database Class: Spacing3
118
119              Requests  additional  space  below each text line in the widget,
120              using any of the standard forms for screen distances. If a  line
121              wraps, this option only applies to the last line on the display.
122              This option may be overridden with -spacing3 options in tags.
123
124       Command-Line Name:-startline
125       Database Name:  startLine
126       Database Class: StartLine
127
128              Specifies an integer line index representing the first  line  of
129              the  underlying  textual  data store that should be contained in
130              the widget. This allows a text widget to reflect only a  portion
131              of  a  larger  piece  of  text. Instead of an integer, the empty
132              string can be provided to this configuration option, which  will
133              configure the widget to start at the very first line in the tex‐
134              tual data store.
135
136       Command-Line Name:-state
137       Database Name:  state
138       Database Class: State
139
140              Specifies one of two states for the text: normal or disabled. If
141              the  text  is  disabled  then  characters may not be inserted or
142              deleted and no insertion cursor will be displayed, even  if  the
143              input focus is in the widget.
144
145       Command-Line Name:-tabs
146       Database Name:  tabs
147       Database Class: Tabs
148
149              Specifies  a set of tab stops for the window. The option's value
150              consists of a list of screen distances giving the  positions  of
151              the  tab stops, each of which is a distance relative to the left
152              edge of the widget (excluding borders, padding, etc). Each posi‐
153              tion  may optionally be followed in the next list element by one
154              of the keywords left, right, center, or numeric, which specifies
155              how  to  justify text relative to the tab stop.  Left is the de‐
156              fault; it causes the text following the tab character to be  po‐
157              sitioned  with  its  left  edge at the tab position. Right means
158              that the right edge of the text following the tab  character  is
159              positioned  at  the tab position, and center means that the text
160              is centered at the tab position. Numeric means that the  decimal
161              point in the text is positioned at the tab position; if there is
162              no decimal point then the least significant digit of the  number
163              is  positioned just to the left of the tab position; if there is
164              no number in the text then the text is  right-justified  at  the
165              tab  position.  For example, “-tabs {2c left 4c 6c center}” cre‐
166              ates three tab stops at two-centimeter intervals; the first  two
167              use left justification and the third uses center justification.
168
169              If  the list of tab stops does not have enough elements to cover
170              all of the tabs in a text line, then  Tk  extrapolates  new  tab
171              stops  using the spacing and alignment from the last tab stop in
172              the list. Tab distances must be strictly positive, and must  al‐
173              ways increase from one tab stop to the next (if not, an error is
174              thrown). The value of the -tabs  option  may  be  overridden  by
175              -tabs options in tags.
176
177              If  no  -tabs  option  is specified, or if it is specified as an
178              empty list, then Tk uses default tabs spaced every eight  (aver‐
179              age  size) characters.  To achieve a different standard spacing,
180              for example every 4 characters, simply configure the widget with
181-tabs  "[expr  {4  *  [font  measure $font 0]}] left" -tabstyle
182              wordprocessor”.
183
184       Command-Line Name:-tabstyle
185       Database Name:  tabStyle
186       Database Class: TabStyle
187
188              Specifies how to interpret the relationship between tab stops on
189              a line and tabs in the text of that line. The value must be tab‐
190              ular (the default) or wordprocessor. Note that tabs  are  inter‐
191              preted  as they are encountered in the text. If the tab style is
192              tabular then the n'th tab character in the line's text  will  be
193              associated  with the n'th tab stop defined for that line. If the
194              tab character's x coordinate falls to the right of the n'th  tab
195              stop,  then  a gap of a single space will be inserted as a fall‐
196              back. If the tab style is wordprocessor then any  tab  character
197              being  laid  out will use (and be defined by) the first tab stop
198              to the right of the preceding characters  already  laid  out  on
199              that  line.  The value of the -tabstyle option may be overridden
200              by -tabstyle options in tags.
201
202       Command-Line Name:-undo
203       Database Name:  undo
204       Database Class: Undo
205
206              Specifies a boolean that says whether the undo mechanism is  ac‐
207              tive or not.
208
209       Command-Line Name:-width
210       Database Name:  width
211       Database Class: Width
212
213              Specifies  the  desired width for the window in units of charac‐
214              ters in the font given by the -font option. If the font does not
215              have a uniform width then the width of the character “0” is used
216              in translating from character units to screen units.
217
218       Command-Line Name:-wrap
219       Database Name:  wrap
220       Database Class: Wrap
221
222              Specifies how to handle lines in the text that are too  long  to
223              be  displayed  in  a single line of the text's window. The value
224              must be none or char or word. A wrap mode  of  none  means  that
225              each line of text appears as exactly one line on the screen; ex‐
226              tra characters that do not fit on the screen are not  displayed.
227              In the other modes each line of text will be broken up into sev‐
228              eral screen lines if necessary to keep all the characters  visi‐
229              ble.  In char mode a screen line break may occur after any char‐
230              acter; in word mode a line break  will  only  be  made  at  word
231              boundaries.
232______________________________________________________________________________
233

DESCRIPTION

235       The  text command creates a new window (given by the pathName argument)
236       and makes it into a text widget. Additional options,  described  above,
237       may  be specified on the command line or in the option database to con‐
238       figure aspects of the text such as its default background color and re‐
239       lief.  The text command returns the path name of the new window.
240
241       A  text  widget displays one or more lines of text and allows that text
242       to be edited. Text widgets support four different kinds of  annotations
243       on  the  text, called tags, marks, embedded windows or embedded images.
244       Tags allow different portions of the text to be displayed with  differ‐
245       ent  fonts and colors. In addition, Tcl commands can be associated with
246       tags so that scripts are invoked when particular actions such  as  key‐
247       strokes  and  mouse  button  presses  occur in particular ranges of the
248       text. See TAGS below for more details.
249
250       The second form of annotation consists of floating markers in the  text
251       called  “marks”.   Marks  are used to keep track of various interesting
252       positions in the text as it is edited. See MARKS  below  for  more  de‐
253       tails.
254
255       The third form of annotation allows arbitrary windows to be embedded in
256       a text widget. See EMBEDDED WINDOWS below for more details.
257
258       The fourth form of annotation allows Tk images to be embedded in a text
259       widget. See EMBEDDED IMAGES below for more details.
260
261       The  text  widget also has a built-in undo/redo mechanism. See THE UNDO
262       MECHANISM below for more details.
263
264       The text widget allows for the creation  of  peer  widgets.  These  are
265       other  text  widgets which share the same underlying data (text, marks,
266       tags, images, etc).  See PEER WIDGETS below for more details.
267

INDICES

269       Many of the widget commands for texts take one or more indices as argu‐
270       ments.  An index is a string used to indicate a particular place within
271       a text, such as a place to insert characters or one endpoint of a range
272       of characters to delete. Indices have the syntax
273              base modifier modifier modifier ...
274       Where  base  gives  a starting point and the modifiers adjust the index
275       from the starting point (e.g. move forward or backward one  character).
276       Every  index must contain a base, but the modifiers are optional.  Most
277       modifiers (as documented below) allow an  optional  submodifier.  Valid
278       submodifiers  are  any  and display. If the submodifier is abbreviated,
279       then it must be followed by whitespace, but otherwise there need be  no
280       space  between  the  submodifier and the following modifier.  Typically
281       the display submodifier adjusts the meaning of the  following  modifier
282       to  make  it  refer  to  visual or non-elided units rather than logical
283       units, but this is explained for  each  relevant  case  below.  Lastly,
284       where  count is used as part of a modifier, it can be positive or nega‐
285       tive, so “base - -3 lines” is perfectly valid (and equivalent to  “base
286       +3lines”).
287
288       The base for an index must have one of the following forms:
289
290       line.char   Indicates  char'th  character  on line line. Lines are num‐
291                   bered from 1 for consistency with other UNIX programs  that
292                   use  this  numbering scheme.  Within a line, characters are
293                   numbered from 0. If char is end then it refers to the  new‐
294                   line character that ends the line.
295
296       @x,y        Indicates the character that covers the pixel whose x and y
297                   coordinates within the text's window are x and y.
298
299       end         Indicates the end of the text (the character just after the
300                   last newline).
301
302       mark        Indicates  the  character just after the mark whose name is
303                   mark.
304
305       tag.first   Indicates the first character in the  text  that  has  been
306                   tagged  with tag.  This form generates an error if no char‐
307                   acters are currently tagged with tag.
308
309       tag.last    Indicates the character just after the last one in the text
310                   that has been tagged with tag. This form generates an error
311                   if no characters are currently tagged with tag.
312
313       pathName    Indicates the position of the embedded window whose name is
314                   pathName.   This form generates an error if there is no em‐
315                   bedded window by the given name.
316
317       imageName   Indicates the position of the embedded image whose name  is
318                   imageName.  This form generates an error if there is no em‐
319                   bedded image by the given name.
320
321       If the base could match more than one of the above  forms,  such  as  a
322       mark and imageName both having the same value, then the form earlier in
323       the above list takes precedence. If modifiers follow  the  base  index,
324       each one of them must have one of the forms listed below. Keywords such
325       as chars and wordend may be abbreviated as long as the abbreviation  is
326       unambiguous.
327
328       + count ?submodifier? chars
329              Adjust  the  index  forward by count characters, moving to later
330              lines in the text if necessary. If there are  fewer  than  count
331              characters in the text after the current index, then set the in‐
332              dex to the last index in the text.  Spaces  on  either  side  of
333              count  are optional. If the display submodifier is given, elided
334              characters are skipped over without being  counted.  If  any  is
335              given,  then all characters are counted. For historical reasons,
336              if neither modifier is given then the count actually takes place
337              in  units of index positions (see INDICES for details). This be‐
338              haviour may be changed in a future major release, so if you need
339              an  index count, you are encouraged to use indices instead wher‐
340              ever possible.
341
342       - count ?submodifier? chars
343              Adjust the index backward by count characters, moving to earlier
344              lines  in  the  text if necessary. If there are fewer than count
345              characters in the text before the current index,  then  set  the
346              index  to  the  first  index in the text (1.0). Spaces on either
347              side of count are optional. If the display submodifier is given,
348              elided characters are skipped over without being counted. If any
349              is given, then all characters are counted. For  historical  rea‐
350              sons, if neither modifier is given then the count actually takes
351              place in units of index positions  (see  INDICES  for  details).
352              This  behavior  may  be changed in a future major release, so if
353              you need an index count, you are encouraged to use  indices  in‐
354              stead wherever possible.
355
356       + count ?submodifier? indices
357              Adjust  the  index  forward  by count index positions, moving to
358              later lines in the text if necessary. If there  are  fewer  than
359              count  index positions in the text after the current index, then
360              set the index to the last index position in the text. Spaces  on
361              either  side  of count are optional. Note that an index position
362              is either a single character or a single embedded image  or  em‐
363              bedded  window.  If the display submodifier is given, elided in‐
364              dices are skipped over without being counted. If any  is  given,
365              then all indices are counted; this is also the default behaviour
366              if no modifier is given.
367
368       - count ?submodifier? indices
369              Adjust the index backward by count index  positions,  moving  to
370              earlier  lines in the text if necessary. If there are fewer than
371              count index positions in the text before the current index, then
372              set  the  index  to  the first index position (1.0) in the text.
373              Spaces on either side of count are optional. If the display sub‐
374              modifier is given, elided indices are skipped over without being
375              counted. If any is given, then all indices are counted; this  is
376              also the default behaviour if no modifier is given.
377
378       + count ?submodifier? lines
379              Adjust  the  index  forward  by  count lines, retaining the same
380              character position within the line.  If  there  are  fewer  than
381              count  lines  after  the line containing the current index, then
382              set the index to refer to the same  character  position  on  the
383              last  line  of the text. Then, if the line is not long enough to
384              contain a character at the indicated character position,  adjust
385              the  character  position  to  refer to the last character of the
386              line (the newline).  Spaces on either  side  of  count  are  op‐
387              tional.  If  the  display submodifier is given, then each visual
388              display line is counted separately.  Otherwise, if  any  (or  no
389              modifier)  is  given, then each logical line (no matter how many
390              times it is visually wrapped) counts just once. If the  relevant
391              lines  are  not  wrapped, then these two methods of counting are
392              equivalent.
393
394       - count ?submodifier? lines
395              Adjust the index backward by count logical lines, retaining  the
396              same character position within the line. If there are fewer than
397              count lines before the line containing the current  index,  then
398              set  the  index  to  refer to the same character position on the
399              first line of the text. Then, if the line is not long enough  to
400              contain  a character at the indicated character position, adjust
401              the character position to refer to the  last  character  of  the
402              line (the newline). Spaces on either side of count are optional.
403              If the display submodifier is given, then  each  visual  display
404              line  is  counted separately. Otherwise, if any (or no modifier)
405              is given, then each logical line (no matter how many times it is
406              visually  wrapped)  counts  just once. If the relevant lines are
407              not wrapped, then these two methods of counting are equivalent.
408
409       ?submodifier? linestart
410              Adjust the index to refer to the first index on the line. If the
411              display  submodifier  is  given,  this is the first index on the
412              display line, otherwise on the logical line.
413
414       ?submodifier? lineend
415              Adjust the index to refer to the last index  on  the  line  (the
416              newline).  If the display submodifier is given, this is the last
417              index on the display line, otherwise on the logical line.
418
419       ?submodifier? wordstart
420              Adjust the index to refer to the first  character  of  the  word
421              containing  the  current index. A word consists of any number of
422              adjacent characters that are letters, digits, or underscores, or
423              a single character that is not one of these. If the display sub‐
424              modifier is given, this  only  examines  non-elided  characters,
425              otherwise all characters (elided or not) are examined.
426
427       ?submodifier? wordend
428              Adjust  the  index to refer to the character just after the last
429              one of the word containing the current index. If the current in‐
430              dex refers to the last character of the text then it is not mod‐
431              ified. If the display submodifier is given, this  only  examines
432              non-elided  characters, otherwise all characters (elided or not)
433              are examined.
434
435       If more than one modifier is present then they are applied in  left-to-
436       right order. For example, the index “end - 1 chars” refers to the next-
437       to-last character in the text and “insert wordstart - 1  c”  refers  to
438       the  character just before the first one in the word containing the in‐
439       sertion cursor. Modifiers are applied one by one in this left to  right
440       order,  and  after each step the resulting index is constrained to be a
441       valid index in the text widget. So, for example,  the  index  “1.0  -1c
442       +1c” refers to the index “2.0”.
443
444       Where modifiers result in index changes by display lines, display chars
445       or display indices, and the base refers to an index  inside  an  elided
446       tag,  that  base index is considered to be equivalent to the first fol‐
447       lowing non-elided index.
448

TAGS

450       The first form of annotation in text widgets is a tag. A tag is a  tex‐
451       tual  string  that is associated with some of the characters in a text.
452       Tags may contain arbitrary characters, but it is probably best to avoid
453       using  the  characters “ ” (space), +, or -: these characters have spe‐
454       cial meaning in indices, so tags containing them cannot be used as  in‐
455       dices.  There may be any number of tags associated with characters in a
456       text. Each tag may refer to a single character, a range of  characters,
457       or  several  ranges of characters. An individual character may have any
458       number of tags associated with it.
459
460       A priority order is defined among tags, and this order is used  in  im‐
461       plementing  some  of  the tag-related functions described below. When a
462       tag is defined (by associating it with characters or setting  its  dis‐
463       play  options or binding commands to it), it is given a priority higher
464       than any existing tag. The priority order of tags may be redefined  us‐
465       ing the “pathName tag raise” and “pathName tag lower” widget commands.
466
467       Tags  serve three purposes in text widgets. First, they control the way
468       information is displayed on the screen. By default, characters are dis‐
469       played as determined by the -background, -font, and -foreground options
470       for the text widget. However, display options may  be  associated  with
471       individual tags using the “pathName tag configure” widget command. If a
472       character has been tagged, then the display options associated with the
473       tag  override the default display style. The following options are cur‐
474       rently supported for tags:
475
476       -background color
477              Color specifies the background color to use for characters asso‐
478              ciated  with  the  tag. It may have any of the forms accepted by
479              Tk_GetColor.
480
481       -bgstipple bitmap
482              Bitmap specifies a bitmap that is used as a stipple pattern  for
483              the background. It may have any of the forms accepted by Tk_Get‐
484              Bitmap. If bitmap has not been specified, or if it is  specified
485              as an empty string, then a solid fill will be used for the back‐
486              ground.
487
488       -borderwidth pixels
489              Pixels specifies the width of a border to draw  around  the  tag
490              using  any  of  the  forms accepted by Tk_GetPixels. This option
491              should be used in conjunction with the -relief option to provide
492              the desired border.
493
494       -elide boolean
495              Elide  specifies  whether the data should be elided. Elided data
496              (characters, images, embedded windows, etc.)  is  not  displayed
497              and  takes  no  space  on screen, but further on behaves just as
498              normal data.
499
500       -fgstipple bitmap
501              Bitmap specifies a bitmap that is used as a stipple pattern when
502              drawing  text  and  other  foreground information such as under‐
503              lines. It may have any of the forms accepted by Tk_GetBitmap. If
504              bitmap has not been specified, or if it is specified as an empty
505              string, then a solid fill will be used.
506
507       -font fontName
508              FontName is the name of a font to use for drawing characters. It
509              may have any of the forms accepted by Tk_GetFont.
510
511       -foreground color
512              Color  specifies  the  color  to use when drawing text and other
513              foreground information such as underlines. It may  have  any  of
514              the forms accepted by Tk_GetColor.
515
516       -justify justify
517              If  the  first  non-elided character of a display line has a tag
518              for which this option has been specified,  then  justify  deter‐
519              mines how to justify the line. It must be one of left, right, or
520              center. If a line wraps, then the justification for each line on
521              the  display  is determined by the first non-elided character of
522              that display line.
523
524       -lmargin1 pixels
525              If the first non-elided character of a text line has a  tag  for
526              which  this option has been specified, then pixels specifies how
527              much the line should be indented from the left edge of the  win‐
528              dow.  Pixels  may have any of the standard forms for screen dis‐
529              tances. If a line of text wraps, this option only applies to the
530              first line on the display; the -lmargin2 option controls the in‐
531              dentation for subsequent lines.
532
533       -lmargin2 pixels
534              If the first non-elided character of a display line  has  a  tag
535              for  which  this  option  has been specified, and if the display
536              line is not the first for its text line (i.e., the text line has
537              wrapped),  then pixels specifies how much the line should be in‐
538              dented from the left edge of the window.  Pixels may have any of
539              the  standard  forms  for  screen distances. This option is only
540              used when wrapping is enabled, and it only applies to the second
541              and later display lines for a text line.
542
543       -lmargincolor color
544              Color  specifies  the background color to use in regions that do
545              not contain characters because they are indented by -lmargin1 or
546              -lmargin2. It may have any of the forms accepted by Tk_GetColor.
547              If color has not been specified, or if it  is  specified  as  an
548              empty  string,  then  the  color used is specified by the -back‐
549              ground tag option (or, if  this  is  also  unspecified,  by  the
550              -background widget option).
551
552       -offset pixels
553              Pixels  specifies  an amount by which the text's baseline should
554              be offset vertically from the baseline of the overall  line,  in
555              pixels.  For  example,  a positive offset can be used for super‐
556              scripts and a negative offset can be used for subscripts. Pixels
557              may have any of the standard forms for screen distances.
558
559       -overstrike boolean
560              Specifies  whether  or not to draw a horizontal rule through the
561              middle of characters. Boolean may have any of the forms accepted
562              by Tcl_GetBoolean.
563
564       -overstrikefg color
565              Color specifies the color to use when displaying the overstrike.
566              It may have any of the forms accepted by Tk_GetColor.  If  color
567              has  not  been  specified,  or  if  it  is specified as an empty
568              string, then the color specified by the -foreground  tag  option
569              is used.
570
571       -relief relief
572              Relief specifies the relief style to use for drawing the border,
573              in any of the forms accepted by  Tk_GetRelief.  This  option  is
574              used  in  conjunction  with the -borderwidth option to enable to
575              the desired border appearance.
576
577       -rmargin pixels
578              If the first non-elided character of a display line  has  a  tag
579              for  which this option has been specified, then pixels specifies
580              how wide a margin to leave between the end of the line  and  the
581              right  edge  of the window.  Pixels may have any of the standard
582              forms for screen distances. This option is only used when  wrap‐
583              ping is enabled. If a text line wraps, the right margin for each
584              line on the display is determined by the first non-elided  char‐
585              acter of that display line.
586
587       -rmargincolor color
588              Color  specifies  the background color to use in regions that do
589              not contain characters because they are indented by -rmargin. It
590              may  have any of the forms accepted by Tk_GetColor. If color has
591              not been specified, or if it is specified as  an  empty  string,
592              then  the  color used is specified by the -background tag option
593              (or, if this is also unspecified, by the -background widget  op‐
594              tion).
595
596       -selectbackground color
597              Color  specifies the background color to use when displaying se‐
598              lected items. It may have any of the forms accepted  by  Tk_Get‐
599              Color. If color has not been specified, or if it is specified as
600              an empty string, then the color specified by the -background tag
601              option is used.
602
603       -selectforeground color
604              Color  specifies the foreground color to use when displaying se‐
605              lected items. It may have any of the forms accepted  by  Tk_Get‐
606              Color. If color has not been specified, or if it is specified as
607              an empty string, then the color specified by the -foreground tag
608              option is used.
609
610       -spacing1 pixels
611              Pixels  specifies how much additional space should be left above
612              each text line, using any of the standard forms for screen  dis‐
613              tances.  If  a line wraps, this option only applies to the first
614              line on the display.
615
616       -spacing2 pixels
617              For lines that wrap, this option specifies how  much  additional
618              space to leave between the display lines for a single text line.
619              Pixels may have any of the standard forms for screen distances.
620
621       -spacing3 pixels
622              Pixels specifies how much additional space should be left  below
623              each  text line, using any of the standard forms for screen dis‐
624              tances. If a line wraps, this option only applies  to  the  last
625              line on the display.
626
627       -tabs tabList
628              TabList specifies a set of tab stops in the same form as for the
629              -tabs option for the text widget. This option only applies to  a
630              display  line if it applies to the first non-elided character on
631              that display line. If this  option  is  specified  as  an  empty
632              string,  it  cancels  the option, leaving it unspecified for the
633              tag (the default). If the option is  specified  as  a  non-empty
634              string  that  is  an  empty list, such as -tags { }, then it re‐
635              quests default 8-character tabs as described for the -tags  wid‐
636              get option.
637
638       -tabstyle style
639              Style  specifies  either  the  tabular or wordprocessor style of
640              tabbing to use for the text widget. This option only applies  to
641              a  display  line if it applies to the first non-elided character
642              on that display line. If this option is specified  as  an  empty
643              string,  it  cancels  the option, leaving it unspecified for the
644              tag (the default).
645
646       -underline boolean
647              Boolean specifies whether or not to draw an underline underneath
648              characters.  It  may  have any of the forms accepted by Tcl_Get‐
649              Boolean.
650
651       -underlinefg color
652              Color specifies the color to use when displaying the  underline.
653              It  may  have any of the forms accepted by Tk_GetColor. If color
654              has not been specified, or  if  it  is  specified  as  an  empty
655              string,  then  the color specified by the -foreground tag option
656              is used.
657
658       -wrap mode
659              Mode specifies how to handle  lines  that  are  wider  than  the
660              text's  window. This option only applies to a display line if it
661              applies to the first non-elided character on that display  line.
662              It  has  the  same legal values as the -wrap option for the text
663              widget: none, char, or word. If this tag option is specified, it
664              overrides the -wrap option for the text widget.
665
666       If  a  character has several tags associated with it, and if their dis‐
667       play options conflict, then the options of the highest priority tag are
668       used.  If a particular display option has not been specified for a par‐
669       ticular tag, or if it is specified as an empty string, then that option
670       will  never  be  used; the next-highest-priority tag's option will used
671       instead. If no tag specifies a particular display option, then the  de‐
672       fault style for the widget will be used.
673
674       The  second purpose for tags is event bindings. You can associate bind‐
675       ings with a tag in much the same way you can associate bindings with  a
676       widget class: whenever particular X events occur on characters with the
677       given tag, a given Tcl command will be executed. Tag  bindings  can  be
678       used  to  give  behaviors  to ranges of characters; among other things,
679       this allows hypertext-like features to be implemented. For details, see
680       the  description  of  the “pathName tag bind” widget command below. Tag
681       bindings are shared between all peer widgets  (including  any  bindings
682       for the special sel tag).
683
684       The  third use for tags is in managing the selection. See THE SELECTION
685       below. With the exception of the special sel tag, all tags  are  shared
686       between  peer  text  widgets,  and may be manipulated on an equal basis
687       from any such widget. The sel tag exists separately  and  independently
688       in each peer text widget (but any tag bindings to sel are shared).
689

MARKS

691       The second form of annotation in text widgets is a mark. Marks are used
692       for remembering particular places in a text. They  are  something  like
693       tags, in that they have names and they refer to places in the file, but
694       a mark is not associated with particular characters. Instead, a mark is
695       associated  with the gap between two characters. Only a single position
696       may be associated with a mark at any  given  time.  If  the  characters
697       around a mark are deleted the mark will still remain; it will just have
698       new neighbor characters. In contrast, if the  characters  containing  a
699       tag  are  deleted  then the tag will no longer have an association with
700       characters in the file. Marks may be  manipulated  with  the  “pathName
701       mark”  widget command, and their current locations may be determined by
702       using the mark name as an index in widget commands.
703
704       Each mark also has a “gravity”, which is  either  left  or  right.  The
705       gravity  for a mark specifies what happens to the mark when text is in‐
706       serted at the point of the mark. If a mark has left gravity,  then  the
707       mark is treated as if it were attached to the character on its left, so
708       the mark will remain to the left of any text inserted at the mark posi‐
709       tion.  If the mark has right gravity, new text inserted at the mark po‐
710       sition will appear to the left of the mark (so that  the  mark  remains
711       rightmost). The gravity for a mark defaults to right.
712
713       The name space for marks is different from that for tags: the same name
714       may be used for both a mark and a tag, but they will refer to different
715       things.
716
717       Two  marks have special significance. First, the mark insert is associ‐
718       ated with the insertion cursor, as described under THE INSERTION CURSOR
719       below.  Second, the mark current is associated with the character clos‐
720       est to the mouse and is adjusted automatically to track the mouse posi‐
721       tion  and any changes to the text in the widget (one exception: current
722       is not updated in response to mouse motions if a mouse button is  down;
723       the  update  will  be  deferred  until  all mouse buttons have been re‐
724       leased).  Neither of these special marks may be deleted. With  the  ex‐
725       ception  of  these two special marks, all marks are shared between peer
726       text widgets, and may be manipulated on an equal basis from any peer.
727

EMBEDDED WINDOWS

729       The third form of annotation in text widgets  is  an  embedded  window.
730       Each  embedded  window  annotation causes a window to be displayed at a
731       particular point in the text. There may be any number of embedded  win‐
732       dows in a text widget, and any widget may be used as an embedded window
733       (subject to the usual rules for geometry management, which require  the
734       text  window to be the parent of the embedded window or a descendant of
735       its parent).
736
737       The embedded window's position on the screen will  be  updated  as  the
738       text  is modified or scrolled, and it will be mapped and unmapped as it
739       moves into and out of the visible area of the text widget. Each  embed‐
740       ded window occupies one unit's worth of index space in the text widget,
741       and it may be referred to either by the name of its embedded window  or
742       by  its position in the widget's index space. If the range of text con‐
743       taining the embedded window is deleted then the  window  is  destroyed.
744       Similarly  if the text widget as a whole is deleted, then the window is
745       destroyed.
746
747       Eliding an embedded window immediately after scheduling it for creation
748       via pathName window create index -create will prevent it from being ef‐
749       fectively created. Uneliding an elided embedded  window  scheduled  for
750       creation  via  pathName  window create index -create will automatically
751       trigger the associated creation script. After destroying an elided  em‐
752       bedded window, the latter won't get automatically recreated.
753
754       When  an  embedded  window  is added to a text widget with the pathName
755       window create widget command, several configuration options may be  as‐
756       sociated with it. These options may be modified later with the pathName
757       window configure widget command. The following  options  are  currently
758       supported:
759
760       -align where
761              If  the  window  is  not as tall as the line in which it is dis‐
762              played, this option determines where the window is displayed  in
763              the  line.  Where must have one of the values top (align the top
764              of the window with the top of the line), center (center the win‐
765              dow  within  the range of the line), bottom (align the bottom of
766              the window with the bottom of  the  line's  area),  or  baseline
767              (align the bottom of the window with the baseline of the line).
768
769       -create script
770              Specifies  a Tcl script that may be evaluated to create the win‐
771              dow for the annotation. If no -window option has been  specified
772              for  the annotation this script will be evaluated when the anno‐
773              tation is about to be displayed on the screen. Script must  cre‐
774              ate a window for the annotation and return the name of that win‐
775              dow as its result. Two substitutions will be performed in script
776              before  evaluation.  %W  will  be substituted by the name of the
777              parent text widget, and %% will be substituted by  a  single  %.
778              If  the  annotation's window should ever be deleted, script will
779              be evaluated again the next time the annotation is displayed.
780
781       -padx pixels
782              Pixels specifies the amount of extra space to leave on each side
783              of  the  embedded window. It may have any of the usual forms de‐
784              fined for a screen distance.
785
786       -pady pixels
787              Pixels specifies the amount of extra space to leave on  the  top
788              and on the bottom of the embedded window. It may have any of the
789              usual forms defined for a screen distance.
790
791       -stretch boolean
792              If the requested height of the embedded window is less than  the
793              height  of the line in which it is displayed, this option can be
794              used to specify whether the window should  be  stretched  verti‐
795              cally  to  fill its line. If the -pady option has been specified
796              as well, then the requested padding will be retained even if the
797              window is stretched.
798
799       -window pathName
800              Specifies  the  name  of  a window to display in the annotation.
801              Note that if a pathName has been set, then later  configuring  a
802              window  to  the  empty  string will not delete the widget corre‐
803              sponding to the old pathName.  Rather it will remove the associ‐
804              ation  between the old pathName and the text widget. If multiple
805              peer widgets are in use, it is usually simpler to use the  -cre‐
806              ate option if embedded windows are desired in each peer.
807

EMBEDDED IMAGES

809       The final form of annotation in text widgets is an embedded image. Each
810       embedded image annotation causes an image to be displayed at a particu‐
811       lar  point in the text. There may be any number of embedded images in a
812       text widget, and a particular image may be embedded in multiple  places
813       in the same text widget.
814
815       The embedded image's position on the screen will be updated as the text
816       is modified or scrolled. Each embedded image occupies one unit's  worth
817       of  index space in the text widget, and it may be referred to either by
818       its position in the widget's index space, or the name  it  is  assigned
819       when  the  image  is  inserted into the text widget with pathName image
820       create. If the range of text containing the embedded image  is  deleted
821       then that copy of the image is removed from the screen.
822
823       Eliding  an embedded image immediately after scheduling it for creation
824       via pathName image create index -create will prevent it from being  ef‐
825       fectively  created.  Uneliding  an  elided embedded image scheduled for
826       creation via pathName image create  index  -create  will  automatically
827       trigger  the associated creation script. After destroying an elided em‐
828       bedded image, the latter won't get automatically recreated.
829
830       When an embedded image is added to a text widget with the pathName  im‐
831       age  create widget command, a name unique to this instance of the image
832       is returned. This name may then be used to  refer  to  this  image  in‐
833       stance.  The  name  is  taken  to be the value of the -name option (de‐
834       scribed below). If the -name option is not provided, the -image name is
835       used  instead.   If the imageName is already in use in the text widget,
836       then #nn is added to the end of the imageName, where nn is an arbitrary
837       integer.  This  insures  the imageName is unique. Once this name is as‐
838       signed to this instance of the image, it does not change,  even  though
839       the  -image  or -name values can be changed with pathName image config‐
840       ure.
841
842       When an embedded image is added to a text widget with the pathName  im‐
843       age create widget command, several configuration options may be associ‐
844       ated with it. These options may be modified later with the pathName im‐
845       age  configure widget command. The following options are currently sup‐
846       ported:
847
848       -align where
849              If the image is not as tall as the line  in  which  it  is  dis‐
850              played,  this  option determines where the image is displayed in
851              the line. Where must have one of the values top (align  the  top
852              of the image with the top of the line), center (center the image
853              within the range of the line), bottom (align the bottom  of  the
854              image  with  the  bottom of the line's area), or baseline (align
855              the bottom of the image with the baseline of the line).
856
857       -image image
858              Specifies the name of the Tk image to display in the annotation.
859              If image is not a valid Tk image, then an error is returned.
860
861       -name ImageName
862              Specifies  the  name  by which this image instance may be refer‐
863              enced in the text widget. If ImageName is not supplied, then the
864              name  of  the  Tk image is used instead. If the imageName is al‐
865              ready in use, #nn is appended to the end  of  the  name  as  de‐
866              scribed above.
867
868       -padx pixels
869              Pixels specifies the amount of extra space to leave on each side
870              of the embedded image. It may have any of the  usual  forms  de‐
871              fined for a screen distance.
872
873       -pady pixels
874              Pixels  specifies  the amount of extra space to leave on the top
875              and on the bottom of the embedded image. It may have any of  the
876              usual forms defined for a screen distance.
877

THE SELECTION

879       Selection  support is implemented via tags. If the -exportselection op‐
880       tion for the text widget is true then the sel tag  will  be  associated
881       with the selection:
882
883       [1]    Whenever  characters  are  tagged  with sel the text widget will
884              claim ownership of the selection.
885
886       [2]    Attempts to retrieve the selection will be serviced by the  text
887              widget, returning all the characters with the sel tag.
888
889       [3]    If  the  selection  is claimed away by another application or by
890              another window within this application, then the sel tag will be
891              removed from all characters in the text.
892
893       [4]    Whenever the sel tag range changes a virtual event <<Selection>>
894              is generated.
895
896       The sel tag is automatically defined when a text widget is created, and
897       it  may  not  be deleted with the “pathName tag delete” widget command.
898       Furthermore, the -selectbackground,  -selectborderwidth,  and  -select‐
899       foreground  options  for  the  text widget are tied to the -background,
900       -borderwidth, and -foreground options for the sel tag: changes  in  ei‐
901       ther will automatically be reflected in the other. Also the -inactives‐
902       electbackground option for the text widget is used instead of  -select‐
903       background  when  the  text widget does not have the focus. This allows
904       programmatic control over the visualization of the sel  tag  for  fore‐
905       ground  and  background  windows, or to have sel not shown at all (when
906       -inactiveselectbackground is empty) for background windows.  Each  peer
907       text  widget has its own sel tag which can be separately configured and
908       set.
909

THE INSERTION CURSOR

911       The mark named insert has special significance in text widgets.  It  is
912       defined  automatically  when a text widget is created and it may not be
913       unset with the “pathName mark unset” widget command.  The  insert  mark
914       represents the position of the insertion cursor, and the insertion cur‐
915       sor will automatically be drawn at this point whenever the text  widget
916       has the input focus.
917

THE MODIFIED FLAG

919       The  text widget can keep track of changes to the content of the widget
920       by means of the modified flag. Inserting or deleting text will set this
921       flag.  The  flag  can  be  queried, set and cleared programmatically as
922       well. Whenever the flag changes state a <<Modified>> virtual  event  is
923       generated.  See  the pathName edit modified widget command for more de‐
924       tails.
925

THE UNDO MECHANISM

927       The text widget has an unlimited undo  and  redo  mechanism  (when  the
928       -undo  widget option is true) which records every insert and delete ac‐
929       tion on a stack.
930
931       Boundaries (called “separators”) are inserted between edit actions. The
932       purpose  of  these separators is to group inserts, deletes and replaces
933       into one compound edit action. When undoing a change everything between
934       two separators will be undone. The undone changes are then moved to the
935       redo stack, so that an undone edit can be redone again.  The redo stack
936       is  cleared  whenever  new edit actions are recorded on the undo stack.
937       The undo and redo stacks can be cleared to keep their depth under  con‐
938       trol.
939
940       Separators  are  inserted automatically when the -autoseparators widget
941       option is true. You can insert separators programmatically as well.  If
942       a  separator  is  already present at the top of the undo stack no other
943       will be inserted. That means that two separators on the undo stack  are
944       always separated by at least one insert or delete action.
945
946       The  <<UndoStack>> virtual event is generated every time the undo stack
947       or the redo stack becomes empty or unempty.
948
949       The undo mechanism is also linked to the modified flag. This means that
950       undoing  or redoing changes can take a modified text widget back to the
951       unmodified state or vice versa. The modified flag will be set automati‐
952       cally  to  the appropriate state. This automatic coupling does not work
953       when the modified flag has been set by the user,  until  the  flag  has
954       been reset again.
955
956       See  below  for the pathName edit widget command that controls the undo
957       mechanism.
958

PEER WIDGETS

960       The text widget has a separate store of all its  data  concerning  each
961       line's  textual contents, marks, tags, images and windows, and the undo
962       stack.
963
964       While this data store cannot be accessed directly (i.e. without a  text
965       widget  as an intermediary), multiple text widgets can be created, each
966       of which present different views on the same underlying data. Such text
967       widgets are known as peer text widgets.
968
969       As  text  is added, deleted, edited and coloured in any one widget, and
970       as images, marks, tags are adjusted, all such changes will be reflected
971       in all peers.
972
973       All  data  and markup is shared, except for a few small details. First,
974       the sel tag may be set and configured (in its  display  style)  differ‐
975       ently  for  each peer. Second, each peer has its own insert and current
976       mark positions (but all other marks are shared). Third,  embedded  win‐
977       dows,  which  are  arbitrary  other  widgets,  cannot be shared between
978       peers. This means the -window option of embedded  windows  is  indepen‐
979       dently set for each peer (it is advisable to use the -create script ca‐
980       pabilities to allow each peer to create its  own  embedded  windows  as
981       needed).  Fourth,  all  of the configuration options of each peer (e.g.
982       -font, etc) can be set independently,  with  the  exception  of  -undo,
983       -maxundo,  -autoseparators  (i.e. all undo, redo and modified state is‐
984       sues are shared).
985
986       Finally any single peer need not contain all lines from the  underlying
987       data  store.  When  creating  a peer, a contiguous range of lines (e.g.
988       only lines 52 through 125) may be specified. This allows a peer to con‐
989       tain  just a small portion of the overall text. The range of lines will
990       expand and contract as text is inserted or deleted. The peer will  only
991       ever  display  complete  lines of text (one cannot share just part of a
992       line). If the peer's contents contracts to nothing (i.e.  all  complete
993       lines  in  the peer widget have been deleted from another widget), then
994       it is impossible for new lines to be inserted. The peer will simply be‐
995       come  an  empty  shell  on  which the background can be configured, but
996       which will never show any content (without  manual  reconfiguration  of
997       the  start  and end lines). Note that a peer which does not contain all
998       of the underlying data store still has indices numbered from  “1.0”  to
999       “end”.   It  is simply that those indices reflect a subset of the total
1000       data, and data outside the contained range is  not  accessible  to  the
1001       peer.  This  means that the command peerName index end may return quite
1002       different values in different peers. Similarly, commands like  peerName
1003       tag  ranges will not return index ranges outside that which is meaning‐
1004       ful to the peer. The configuration options -startline and -endline  may
1005       be  used to control how much of the underlying data is contained in any
1006       given text widget.
1007
1008       Note that peers are really peers. Deleting the “original”  text  widget
1009       will not cause any other peers to be deleted, or otherwise affected.
1010
1011       See  below  for the pathName peer widget command that controls the cre‐
1012       ation of peer widgets.
1013

ASYNCHRONOUS UPDATE OF LINE HEIGHTS

1015       In order to maintain a responsive user-experience, the text widget cal‐
1016       culates  lines metrics (line heights in pixels) asynchronously. Because
1017       of this, some commands of the text widget may return wrong  results  if
1018       the  asynchronous calculations are not finished at the time of calling.
1019       This applies to pathName count -ypixels and pathName yview.
1020
1021       Again for performance reasons, it would not be appropriate to let these
1022       commands  always  wait  for the end of the update calculation each time
1023       they are called. In most use cases of these commands a more or less in‐
1024       accurate result does not really matter compared to execution speed.
1025
1026       In case accurate result is needed (and if the text widget is managed by
1027       a geometry manager), one can resort to pathName sync and pathName pend‐
1028       ingsync to control the synchronization of the view of text widgets.
1029
1030       The <<WidgetViewSync>> virtual event fires when the line heights of the
1031       text widget become obsolete (due to some editing command or  configura‐
1032       tion  change),  and again when the internal data of the text widget are
1033       back in sync with the widget view. The detail field  (%d  substitution)
1034       is either true (when the widget is in sync) or false (when it is not).
1035
1036       pathName  sync,  pathName  pendingsync  and <<WidgetViewSync>> apply to
1037       each text widget independently of its peers.
1038
1039       Examples of use:
1040              ## Example 1:
1041              # immediately complete line metrics at any cost (GUI unresponsive)
1042              $w sync
1043              $w yview moveto $fraction
1044
1045              ## Example 2:
1046              # synchronously wait for up-to-date line metrics (GUI responsive)
1047              # before executing the scheduled command, but don't block execution flow
1048              $w sync -command [list $w yview moveto $fraction]
1049
1050              ## Example 3:
1051              # init
1052              set yud($w) 0
1053              proc updateaction w {
1054              set ::yud($w) 1
1055              # any other update action here...
1056              }
1057              # runtime, synchronously wait for up-to-date line metrics (GUI responsive)
1058              $w sync -command [list updateaction $w]
1059              vwait yud($w)
1060              $w yview moveto $fraction
1061
1062              ## Example 4:
1063              # init
1064              set todo($w) {}
1065              proc updateaction w {
1066              foreach cmd $::todo($w) {uplevel #0 $cmd}
1067              set todo($w) {}
1068              }
1069              # runtime
1070              lappend todo($w) [list $w yview moveto $fraction]
1071              $w sync -command [list updateaction $w]
1072
1073              ## Example 5:
1074              # init
1075              set todo($w) {}
1076              bind $w <<WidgetViewSync>> {
1077              if {%d} {
1078              foreach cmd $todo(%W) {eval $cmd}
1079              set todo(%W) {}
1080              }
1081              }
1082              # runtime
1083              if {![$w pendingsync]} {
1084              $w yview moveto $fraction
1085              } else {
1086              lappend todo($w) [list $w yview moveto $fraction]
1087              }
1088

WIDGET COMMAND

1090       The text command creates a new Tcl command whose name is  the  same  as
1091       the  path name of the text's window. This command may be used to invoke
1092       various operations on the widget. It has the following general form:
1093              pathName option ?arg arg ...?
1094       PathName is the name of the command, which is the same as the text wid‐
1095       get's  path  name.  Option and the args determine the exact behavior of
1096       the command. The following commands are possible for text widgets:
1097
1098       pathName bbox index
1099              Returns a list of four elements describing the  screen  area  of
1100              the character given by index. The first two elements of the list
1101              give the x and y coordinates of the  upper-left  corner  of  the
1102              area  occupied  by the character, and the last two elements give
1103              the width and height of the area. If the character is only  par‐
1104              tially  visible  on  the  screen, then the return value reflects
1105              just the visible part. If the character is not  visible  on  the
1106              screen then the return value is an empty list.
1107
1108       pathName cget option
1109              Returns  the  current value of the configuration option given by
1110              option.  Option may have any of the values accepted by the  text
1111              command.
1112
1113       pathName compare index1 op index2
1114              Compares the indices given by index1 and index2 according to the
1115              relational operator given by op, and returns 1 if the  relation‐
1116              ship  is satisfied and 0 if it is not. Op must be one of the op‐
1117              erators <, <=, ==, >=, >, or !=. If op is == then 1 is  returned
1118              if  the two indices refer to the same character, if op is < then
1119              1 is returned if index1 refers to an earlier  character  in  the
1120              text than index2, and so on.
1121
1122       pathName configure ?option? ?value option value ...?
1123              Query  or  modify the configuration options of the widget. If no
1124              option is specified, returns a list describing all of the avail‐
1125              able  options for pathName (see Tk_ConfigureInfo for information
1126              on the format of this list). If  option  is  specified  with  no
1127              value,  then the command returns a list describing the one named
1128              option (this list will be identical to the corresponding sublist
1129              of the value returned if no option is specified). If one or more
1130              option-value pairs are specified, then the command modifies  the
1131              given  widget option(s) to have the given value(s); in this case
1132              the command returns an empty string. Option may have any of  the
1133              values accepted by the text command.
1134
1135       pathName count ?options? index1 index2
1136              Counts the number of relevant things between the two indices. If
1137              index1 is after index2, the result will  be  a  negative  number
1138              (and  this  holds  for each of the possible options). The actual
1139              items which are counted depend on the options given. The  result
1140              is  a  list of integers, one for the result of each counting op‐
1141              tion given. Valid counting options  are  -chars,  -displaychars,
1142              -displayindices,  -displaylines,  -indices, -lines, -xpixels and
1143              -ypixels. The default value, if no option is specified, is  -in‐
1144              dices. There is an additional possible option -update which is a
1145              modifier. If given (and if the text widget is managed by a geom‐
1146              etry  manager), then all subsequent options ensure that any pos‐
1147              sible out of date information is recalculated.   This  currently
1148              only has any effect for the -ypixels count (which, if -update is
1149              not given, will use the text widget's current cached  value  for
1150              each  line).  This -update option is obsoleted by pathName sync,
1151              pathName pendingsync and <<WidgetViewSync>>.  The count  options
1152              are interpreted as follows:
1153
1154              -chars count all characters, whether elided or not. Do not count
1155                     embedded windows or images.
1156
1157              -displaychars
1158                     count all non-elided characters.
1159
1160              -displayindices
1161                     count all non-elided characters, windows and images.
1162
1163              -displaylines
1164                     count all display lines (i.e. counting one for each  time
1165                     a line wraps) from the line of the first index up to, but
1166                     not including the  display  line  of  the  second  index.
1167                     Therefore if they are both on the same display line, zero
1168                     will be returned. By definition displaylines are  visible
1169                     and therefore this only counts portions of actual visible
1170                     lines.
1171
1172              -indices
1173                     count all characters and embedded windows or images (i.e.
1174                     everything  which  counts  in  text-widget  index space),
1175                     whether they are elided or not.
1176
1177              -lines count all logical lines (irrespective of  wrapping)  from
1178                     the  line of the first index up to, but not including the
1179                     line of the second index. Therefore if they are  both  on
1180                     the  same  line, zero will be returned. Logical lines are
1181                     counted whether they are currently  visible  (non-elided)
1182                     or not.
1183
1184              -xpixels
1185                     count  the  number  of  horizontal  pixels from the first
1186                     pixel of the first index to (but not including) the first
1187                     pixel  of  the  second  index. To count the total desired
1188                     width of the text widget (assuming wrapping  is  not  en‐
1189                     abled),  first  find the longest line and then use “.text
1190                     count -xpixels "${line}.0" "${line}.0 lineend"”.
1191
1192              -ypixels
1193                     count the number of vertical pixels from the first  pixel
1194                     of the first index to (but not including) the first pixel
1195                     of the second index. If both indices are on the same dis‐
1196                     play line, zero will be returned. To count the total num‐
1197                     ber of vertical pixels in the  text  widget,  use  “.text
1198                     count  -ypixels  1.0  end”,  and  to ensure this is up to
1199                     date, use “.text count -update -ypixels 1.0 end”.
1200
1201              The command returns a positive or negative integer corresponding
1202              to the number of items counted between the two indices. One such
1203              integer is returned for each counting option given, so a list is
1204              returned  if  more  than  one  option  was supplied. For example
1205              “.text count -xpixels -ypixels 1.3 4.5” is perfectly  valid  and
1206              will return a list of two elements.
1207
1208       pathName debug ?boolean?
1209              If  boolean  is  specified, then it must have one of the true or
1210              false values accepted by Tcl_GetBoolean. If the value is a  true
1211              one then internal consistency checks will be turned on in the B-
1212              tree code associated with text widgets. If boolean has  a  false
1213              value  then  the  debugging checks will be turned off. In either
1214              case the command returns an empty  string.  If  boolean  is  not
1215              specified then the command returns on or off to indicate whether
1216              or not debugging is turned  on.  There  is  a  single  debugging
1217              switch  shared  by all text widgets: turning debugging on or off
1218              in any widget turns it on or off for all  widgets.  For  widgets
1219              with  large  amounts of text, the consistency checks may cause a
1220              noticeable slow-down.
1221
1222              When debugging is turned on, the drawing routines  of  the  text
1223              widget  set the global variables tk_textRedraw and tk_textRelay‐
1224              out to the lists of indices that  are  redrawn.  The  values  of
1225              these variables are tested by Tk's test suite.
1226
1227       pathName delete index1 ?index2 ...?
1228              Delete  a range of characters from the text.  If both index1 and
1229              index2 are specified, then delete all  the  characters  starting
1230              with  the  one  given  by index1 and stopping just before index2
1231              (i.e. the character at index2 is not deleted).  If  index2  does
1232              not  specify  a  position  later in the text than index1 then no
1233              characters are deleted.  If index2 is  not  specified  then  the
1234              single character at index1 is deleted.  Attempts to delete char‐
1235              acters in a way that would leave the text without a  newline  as
1236              the  last  character will be tweaked by the text widget to avoid
1237              this. In particular, deletion of complete lines of  text  up  to
1238              the  end of the text will also delete the newline character just
1239              before the deleted block so that it is replaced by the new final
1240              newline  of  the  text  widget.   The  command  returns an empty
1241              string.  If more indices are given, multiple ranges of text will
1242              be  deleted.   All indices are first checked for validity before
1243              any deletions are made.  They are sorted and the text is removed
1244              from  the last range to the first range so deleted text does not
1245              cause an undesired index  shifting  side-effects.   If  multiple
1246              ranges  with  the  same  start index are given, then the longest
1247              range is used.  If overlapping ranges are given, then they  will
1248              be  merged into spans that do not cause deletion of text outside
1249              the given ranges due to text shifted during deletion.
1250
1251       pathName dlineinfo index
1252              Returns a list with five elements describing the  area  occupied
1253              by  the display line containing index. The first two elements of
1254              the list give the x and y coordinates of the  upper-left  corner
1255              of  the area occupied by the line, the third and fourth elements
1256              give the width and height of the area,  and  the  fifth  element
1257              gives  the  position of the baseline for the line, measured down
1258              from the top of the area. All of this information is measured in
1259              pixels.  If  the  current wrap mode is none and the line extends
1260              beyond the boundaries of the window, the area returned  reflects
1261              the entire area of the line, including the portions that are out
1262              of the window. If the line is shorter than the full width of the
1263              window  then  the area returned reflects just the portion of the
1264              line that is occupied by characters and embedded windows. If the
1265              display  line containing index is not visible on the screen then
1266              the return value is an empty list.
1267
1268       pathName dump ?switches? index1 ?index2?
1269              Return the contents of the text widget from index1  up  to,  but
1270              not  including  index2, including the text and information about
1271              marks, tags, and embedded windows. If index2 is  not  specified,
1272              then  it  defaults to one character past index1. The information
1273              is returned in the following format:
1274
1275              key1 value1 index1 key2 value2 index2 ...
1276
1277              The possible key values are text, mark,  tagon,  tagoff,  image,
1278              and  window. The corresponding value is the text, mark name, tag
1279              name, image name, or window name. The index information  is  the
1280              index  of  the start of the text, mark, tag transition, image or
1281              window. One or more of the following switches (or  abbreviations
1282              thereof) may be specified to control the dump:
1283
1284              -all   Return information about all elements: text, marks, tags,
1285                     images and windows.  This is the default.
1286
1287              -command command
1288                     Instead of returning the information as the result of the
1289                     dump operation, invoke the command on each element of the
1290                     text widget within the range.  The command has three  ar‐
1291                     guments  appended  to it before it is evaluated: the key,
1292                     value, and index.
1293
1294              -image Include information about images in the dump results.
1295
1296              -mark  Include information about marks in the dump results.
1297
1298              -tag   Include information about tag transitions in the dump re‐
1299                     sults.  Tag  information  is returned as tagon and tagoff
1300                     elements that indicate the begin and end of each range of
1301                     each tag, respectively.
1302
1303              -text  Include  information  about text in the dump results. The
1304                     value is the text up to the next element or  the  end  of
1305                     range  indicated  by index2. A text element does not span
1306                     newlines. A multi-line block of  text  that  contains  no
1307                     marks or tag transitions will still be dumped as a set of
1308                     text segments that each end with a newline.  The  newline
1309                     is part of the value.
1310
1311              -window
1312                     Include  information  about  embedded windows in the dump
1313                     results. The value of a window is its Tk pathname, unless
1314                     the window has not been created yet. (It must have a cre‐
1315                     ate script.) In this case an empty  string  is  returned,
1316                     and  you  must  query the window by its index position to
1317                     get more information.
1318
1319       pathName edit option ?arg arg ...?
1320              This command controls the undo mechanism and the modified  flag.
1321              The exact behavior of the command depends on the option argument
1322              that follows the edit argument. The following forms of the  com‐
1323              mand are currently supported:
1324
1325              pathName edit canredo
1326                     Returns a boolean true if redo is possible, i.e. when the
1327                     redo stack is not empty. Otherwise returns false.
1328
1329              pathName edit canundo
1330                     Returns a boolean true if undo is possible, i.e. when the
1331                     undo stack is not empty. Otherwise returns false.
1332
1333              pathName edit modified ?boolean?
1334                     If boolean is not specified, returns the modified flag of
1335                     the widget.  The insert, delete, edit undo and edit  redo
1336                     commands  or the user can set or clear the modified flag.
1337                     If boolean is specified, sets the modified  flag  of  the
1338                     widget to boolean.
1339
1340              pathName edit redo
1341                     When  the -undo option is true, reapplies the last undone
1342                     edits provided no other edits were done since then.  Gen‐
1343                     erates  an error when the redo stack is empty. Does noth‐
1344                     ing when the -undo option is false.
1345
1346              pathName edit reset
1347                     Clears the undo and redo stacks.
1348
1349              pathName edit separator
1350                     Inserts a separator (boundary) on the  undo  stack.  Does
1351                     nothing when the -undo option is false.
1352
1353              pathName edit undo
1354                     Undoes  the  last  edit  action  when the -undo option is
1355                     true. An edit action is defined as  all  the  insert  and
1356                     delete  commands  that  are recorded on the undo stack in
1357                     between two separators. Generates an error when the  undo
1358                     stack  is  empty.  Does  nothing when the -undo option is
1359                     false.
1360
1361       pathName get ?-displaychars? ?--? index1 ?index2 ...?
1362              Return a range of characters from the  text.  The  return  value
1363              will  be  all  the  characters in the text starting with the one
1364              whose index is index1 and ending just before the one whose index
1365              is index2 (the character at index2 will not be returned). If in‐
1366              dex2 is omitted then the single character at index1 is returned.
1367              If  there  are no characters in the specified range (e.g. index1
1368              is past the end of the file or index2 is less than or  equal  to
1369              index1) then an empty string is returned. If the specified range
1370              contains embedded windows, no information about them is included
1371              in  the returned string. If multiple index pairs are given, mul‐
1372              tiple ranges of text will be returned in a list. Invalid  ranges
1373              will  not  be  represented  with  empty strings in the list. The
1374              ranges are returned in the order passed to pathName get. If  the
1375              -displaychars  option  is  given,  then, within each range, only
1376              those characters which are not elided will be returned. This may
1377              have  the  effect  that  some  of  the returned ranges are empty
1378              strings.
1379
1380       pathName image option ?arg arg ...?
1381              This command is used to manipulate embedded images. The behavior
1382              of  the  command depends on the option argument that follows the
1383              image argument. The following forms of the command are currently
1384              supported:
1385
1386              pathName image cget index option
1387                     Returns the value of a configuration option for an embed‐
1388                     ded image. Index identifies the embedded image,  and  op‐
1389                     tion  specifies  a particular configuration option, which
1390                     must be one of the ones listed in  the  section  EMBEDDED
1391                     IMAGES.
1392
1393              pathName image configure index ?option value ...?
1394                     Query or modify the configuration options for an embedded
1395                     image. If no option is specified, returns a list describ‐
1396                     ing  all  of the available options for the embedded image
1397                     at index (see Tk_ConfigureInfo  for  information  on  the
1398                     format  of  this  list).  If  option is specified with no
1399                     value, then the command returns a list describing the one
1400                     named  option  (this list will be identical to the corre‐
1401                     sponding sublist of the value returned if  no  option  is
1402                     specified).  If one or more option-value pairs are speci‐
1403                     fied, then the command modifies the  given  option(s)  to
1404                     have the given value(s); in this case the command returns
1405                     an empty string. See EMBEDDED IMAGES for  information  on
1406                     the options that are supported.
1407
1408              pathName image create index ?option value ...?
1409                     This  command  creates a new image annotation, which will
1410                     appear in the text at the position given  by  index.  Any
1411                     number  of option-value pairs may be specified to config‐
1412                     ure the annotation. Returns a unique identifier that  may
1413                     be  used as an index to refer to this image. See EMBEDDED
1414                     IMAGES for information on the options that are supported,
1415                     and a description of the identifier returned.
1416
1417              pathName image names
1418                     Returns  a list whose elements are the names of all image
1419                     instances currently embedded in window.
1420
1421       pathName index index
1422              Returns  the  position  corresponding  to  index  in  the   form
1423              line.char  where line is the line number and char is the charac‐
1424              ter number.  Index may have any of the forms described under IN‐
1425              DICES above.
1426
1427       pathName insert index chars ?tagList chars tagList ...?
1428              Inserts  all of the chars arguments just before the character at
1429              index. If index refers to the end of the text (the character af‐
1430              ter  the last newline) then the new text is inserted just before
1431              the last newline instead. If there is a  single  chars  argument
1432              and no tagList, then the new text will receive any tags that are
1433              present on both the character before and the character after the
1434              insertion  point; if a tag is present on only one of these char‐
1435              acters then it will not be applied to the new text.  If  tagList
1436              is  specified  then  it consists of a list of tag names; the new
1437              characters will receive all of the tags in this list and no oth‐
1438              ers,  regardless of the tags present around the insertion point.
1439              If multiple chars-tagList argument pairs are present, they  pro‐
1440              duce  the  same  effect  as if a separate pathName insert widget
1441              command had been issued  for  each  pair,  in  order.  The  last
1442              tagList argument may be omitted.
1443
1444       pathName mark option ?arg arg ...?
1445              This  command is used to manipulate marks. The exact behavior of
1446              the command depends on the option argument that follows the mark
1447              argument.  The following forms of the command are currently sup‐
1448              ported:
1449
1450              pathName mark gravity markName ?direction?
1451                     If direction is not specified, returns left or  right  to
1452                     indicate which of its adjacent characters markName is at‐
1453                     tached to. If direction is specified, it must be left  or
1454                     right; the gravity of markName is set to the given value.
1455
1456              pathName mark names
1457                     Returns  a  list  whose elements are the names of all the
1458                     marks that are currently set.
1459
1460              pathName mark next index
1461                     Returns the name of the next mark at or after  index.  If
1462                     index is specified in numerical form, then the search for
1463                     the next mark begins at that index. If index is the  name
1464                     of a mark, then the search for the next mark begins imme‐
1465                     diately after that mark. This can still return a mark  at
1466                     the same position if there are multiple marks at the same
1467                     index. These semantics mean that the mark next  operation
1468                     can  be used to step through all the marks in a text wid‐
1469                     get in the same order as the mark information returned by
1470                     the  pathName  dump  operation. If a mark has been set to
1471                     the special end index, then it appears to  be  after  end
1472                     with  respect  to  the  pathName  mark next operation. An
1473                     empty string is returned if there are no marks after  in‐
1474                     dex.
1475
1476              pathName mark previous index
1477                     Returns the name of the mark at or before index. If index
1478                     is specified in numerical form, then the search  for  the
1479                     previous  mark begins with the character just before that
1480                     index. If index is the name of a mark,  then  the  search
1481                     for  the  next  mark begins immediately before that mark.
1482                     This can still return a mark  at  the  same  position  if
1483                     there  are multiple marks at the same index. These seman‐
1484                     tics mean that the pathName mark previous  operation  can
1485                     be used to step through all the marks in a text widget in
1486                     the reverse order as the mark information returned by the
1487                     pathName  dump  operation. An empty string is returned if
1488                     there are no marks before index.
1489
1490              pathName mark set markName index
1491                     Sets the mark named markName to a  position  just  before
1492                     the character at index. If markName already exists, it is
1493                     moved from its old position; if it does not exist, a  new
1494                     mark is created. This command returns an empty string.
1495
1496              pathName mark unset markName ?markName markName ...?
1497                     Remove the mark corresponding to each of the markName ar‐
1498                     guments. The removed marks will not be usable in  indices
1499                     and  will  not  be  returned by future calls to “pathName
1500                     mark names”.  This command returns an empty string.
1501
1502       pathName peer option args
1503              This command is used to create and query widget  peers.  It  has
1504              two forms, depending on option:
1505
1506              pathName peer create newPathName ?options?
1507                     Creates  a  peer  text widget with the given newPathName,
1508                     and any optional standard configuration options  (as  for
1509                     the text command). By default the peer will have the same
1510                     start and end line as the parent widget, but these can be
1511                     overridden with the standard configuration options.
1512
1513              pathName peer names
1514                     Returns a list of peers of this widget (this does not in‐
1515                     clude the widget itself). The order within this  list  is
1516                     undefined.
1517
1518       pathName pendingsync
1519              Returns 1 if the line heights calculations are not up-to-date, 0
1520              otherwise.
1521
1522       pathName replace index1 index2 chars ?tagList chars tagList ...?
1523              Replaces the range of characters between index1 and index2  with
1524              the  given characters and tags.  See the section on pathName in‐
1525              sert for an explanation of the handling of the tagList...  argu‐
1526              ments,  and the section on pathName delete for an explanation of
1527              the handling of the indices.  If index2 corresponds to an  index
1528              earlier in the text than index1, an error will be generated.
1529
1530              The  deletion  and insertion are arranged so that no unnecessary
1531              scrolling of the window or movement of insertion cursor  occurs.
1532              In  addition the undo/redo stack are correctly modified, if undo
1533              operations are active in the text widget. The command returns an
1534              empty string.
1535
1536       pathName scan option args
1537              This  command is used to implement scanning on texts. It has two
1538              forms, depending on option:
1539
1540              pathName scan mark x y
1541                     Records x and y and the current view in the text  window,
1542                     for  use  in  conjunction with later pathName scan dragto
1543                     commands. Typically this command  is  associated  with  a
1544                     mouse  button  press  in  the widget. It returns an empty
1545                     string.
1546
1547              pathName scan dragto x y
1548                     This command computes the difference between its x and  y
1549                     arguments  and the x and y arguments to the last pathName
1550                     scan mark command for the widget.  It  then  adjusts  the
1551                     view by 10 times the difference in coordinates. This com‐
1552                     mand is typically associated with mouse motion events  in
1553                     the widget, to produce the effect of dragging the text at
1554                     high speed through the window. The  return  value  is  an
1555                     empty string.
1556
1557       pathName search ?switches? pattern index ?stopIndex?
1558              Searches  the  text in pathName starting at index for a range of
1559              characters that matches pattern. If a match is found, the  index
1560              of  the first character in the match is returned as result; oth‐
1561              erwise an empty string is returned. One or more of the following
1562              switches  (or abbreviations thereof) may be specified to control
1563              the search:
1564
1565              -forwards
1566                     The search will proceed forward through the text, finding
1567                     the  first  matching range starting at or after the posi‐
1568                     tion given by index. This is the default.
1569
1570              -backwards
1571                     The search will proceed backward through the text,  find‐
1572                     ing the matching range closest to index whose first char‐
1573                     acter is before index (it is not allowed to be at index).
1574                     Note  that,  for a variety of reasons, backwards searches
1575                     can be substantially slower than forwards searches  (par‐
1576                     ticularly  when using -regexp), so it is recommended that
1577                     performance-critical code use forward searches.
1578
1579              -exact Use exact matching: the characters in the matching  range
1580                     must  be  identical  to those in pattern. This is the de‐
1581                     fault.
1582
1583              -regexp
1584                     Treat pattern  as  a  regular  expression  and  match  it
1585                     against  the text using the rules for regular expressions
1586                     (see the regexp command and the re_syntax  page  for  de‐
1587                     tails).  The  default  matching automatically passes both
1588                     the -lineanchor and -linestop options to the  regexp  en‐
1589                     gine  (unless  -nolinestop is used), so that ^$ match be‐
1590                     ginning and end of line, and ., [^ sequences  will  never
1591                     match the newline character \n.
1592
1593              -nolinestop
1594                     This allows . and [^ sequences to match the newline char‐
1595                     acter \n, which they will otherwise not do (see the  reg‐
1596                     exp  command for details). This option is only meaningful
1597                     if -regexp is also given, and an  error  will  be  thrown
1598                     otherwise.  For  example,  to  match the entire text, use
1599pathName search -nolinestop -regexp ".*" 1.0”.
1600
1601              -nocase
1602                     Ignore case differences between the pattern and the text.
1603
1604              -count varName
1605                     The argument following -count gives the name of  a  vari‐
1606                     able;  if a match is found, the number of index positions
1607                     between beginning and end of the matching range  will  be
1608                     stored  in  the variable. If there are no embedded images
1609                     or windows in the matching range (and there are no elided
1610                     characters if -elide is not given), this is equivalent to
1611                     the number of characters matched.  In  either  case,  the
1612                     range matchIdx to matchIdx + $count chars will return the
1613                     entire matched text.
1614
1615              -all   Find all matches in the given range and return a list  of
1616                     the  indices  of  the first character of each match. If a
1617                     -count varName switch is given, then varName is also  set
1618                     to  a  list  containing  one  element for each successful
1619                     match. Note that, even for exact searches,  the  elements
1620                     of  this list may be different, if there are embedded im‐
1621                     ages, windows or hidden text.  Searches with -all  behave
1622                     very  similarly  to  the Tcl command regexp -all, in that
1623                     overlapping matches are not normally returned. For  exam‐
1624                     ple, applying an -all search of the pattern “\w+” against
1625                     “hello there” will just match twice, once for each  word,
1626                     and  matching  “Z[a-z]+Z”  against  “ZooZooZoo” will just
1627                     match once.
1628
1629              -overlap
1630                     When performing -all searches, the  normal  behaviour  is
1631                     that  matches  which  overlap an already-found match will
1632                     not be returned. This switch changes  that  behaviour  so
1633                     that  all  matches  which are not totally enclosed within
1634                     another match are  returned.  For  example,  applying  an
1635                     -overlap  search  of  the  pattern  “\w+”  against “hello
1636                     there” will just match twice (i.e. no different  to  just
1637                     -all),  but  matching “Z[a-z]+Z” against “ZooZooZoo” will
1638                     now match twice. An error will be thrown if  this  switch
1639                     is used without -all.
1640
1641              -strictlimits
1642                     When  performing any search, the normal behaviour is that
1643                     the start and stop limits are checked with respect to the
1644                     start  of the matching text. With the -strictlimits flag,
1645                     the entire matching range must lie inside the  start  and
1646                     stop limits specified for the match to be valid.
1647
1648              -elide Find  elided  (hidden) text as well. By default only dis‐
1649                     played text is searched.
1650
1651              --     This switch has no effect except to terminate the list of
1652                     switches:  the  next  argument will be treated as pattern
1653                     even if it starts with -.
1654
1655              The matching range may be within a single line of text,  or  run
1656              across  multiple lines (if parts of the pattern can match a new-
1657              line). For regular expression matching one can use  the  various
1658              newline-matching  features such as $ to match the end of a line,
1659              ^ to match the beginning of a line, and to control whether .  is
1660              allowed  to  match  a  new-line.  If stopIndex is specified, the
1661              search stops at that index: for forward searches, no match at or
1662              after  stopIndex  will  be considered; for backward searches, no
1663              match earlier in the text than stopIndex will be considered.  If
1664              stopIndex is omitted, the entire text will be searched: when the
1665              beginning or end of the text is reached, the search continues at
1666              the  other  end until the starting location is reached again; if
1667              stopIndex is specified, no wrap-around will  occur.  This  means
1668              that,  for  example, if the search is -forwards but stopIndex is
1669              earlier in the text than startIndex, nothing will ever be found.
1670              See  KNOWN  BUGS  below for a number of minor limitations of the
1671              pathName search command.
1672
1673       pathName see index
1674              Adjusts the view in the window so that the  character  given  by
1675              index  is  completely  visible. If index is already visible then
1676              the command does nothing. If index is a short  distance  out  of
1677              view,  the  command  adjusts  the view just enough to make index
1678              visible at the edge of the window.  If index is far out of view,
1679              then the command centers index in the window.
1680
1681       pathName sync ?-command command?
1682              Controls the synchronization of the view of the text widget.
1683
1684              pathName sync
1685                     Immediately brings the line metrics up-to-date by forcing
1686                     computation of any outdated line heights. The command re‐
1687                     turns  immediately  if  there  is  no  such outdated line
1688                     heights, otherwise it returns only at the end of the com‐
1689                     putation.  The command returns an empty string.
1690
1691              pathName sync -command command
1692                     Schedules  command to be executed (by the event loop) ex‐
1693                     actly once as soon as all line heights are up-to-date. If
1694                     there  are  no  pending  line  metrics  calculations, the
1695                     scheduling is immediate. The command  returns  the  empty
1696                     string. bgerror is called on command failure.
1697
1698       pathName tag option ?arg arg ...?
1699              This  command  is used to manipulate tags. The exact behavior of
1700              the command depends on the option argument that follows the  tag
1701              argument.  The following forms of the command are currently sup‐
1702              ported:
1703
1704              pathName tag add tagName index1 ?index2 index1 index2 ...?
1705                     Associate the tag tagName  with  all  of  the  characters
1706                     starting  with  index1 and ending just before index2 (the
1707                     character at index2 is not tagged). A single command  may
1708                     contain  any  number  of index1-index2 pairs. If the last
1709                     index2 is omitted then the single character at index1  is
1710                     tagged. If there are no characters in the specified range
1711                     (e.g. index1 is past the end of the  file  or  index2  is
1712                     less than or equal to index1) then the command has no ef‐
1713                     fect.
1714
1715              pathName tag bind tagName ?sequence? ?script?
1716                     This command associates script with the tag given by tag‐
1717                     Name.   Whenever the event sequence given by sequence oc‐
1718                     curs for a character that has been tagged  with  tagName,
1719                     the  script will be invoked. This widget command is simi‐
1720                     lar to the bind command except that it operates on  char‐
1721                     acters in a text rather than entire widgets. See the bind
1722                     manual entry for complete details on the  syntax  of  se‐
1723                     quence  and  the substitutions performed on script before
1724                     invoking it. If all arguments are specified  then  a  new
1725                     binding  is  created,  replacing any existing binding for
1726                     the same sequence and tagName (if the first character  of
1727                     script  is  “+”  then script augments an existing binding
1728                     rather than replacing it). In this case the return  value
1729                     is an empty string. If script is omitted then the command
1730                     returns the script associated with tagName  and  sequence
1731                     (an  error  occurs  if there is no such binding). If both
1732                     script and sequence are omitted then the command  returns
1733                     a  list of all the sequences for which bindings have been
1734                     defined for tagName.
1735
1736                     The only events for which bindings may be  specified  are
1737                     those  related  to the mouse and keyboard (such as Enter,
1738                     Leave, ButtonPress,  Motion,  and  KeyPress)  or  virtual
1739                     events.  Event bindings for a text widget use the current
1740                     mark described under MARKS above. An Enter event triggers
1741                     for  a tag when the tag first becomes present on the cur‐
1742                     rent character, and a Leave event triggers for a tag when
1743                     it  ceases  to be present on the current character. Enter
1744                     and Leave events can happen either  because  the  current
1745                     mark  moved  or  because  the  character at that position
1746                     changed. Note that these events are different than  Enter
1747                     and  Leave  events for windows. Mouse and keyboard events
1748                     are directed to the current character. If a virtual event
1749                     is  used  in  a binding, that binding can trigger only if
1750                     the virtual event is defined by an  underlying  mouse-re‐
1751                     lated or keyboard-related event.
1752
1753                     It is possible for the current character to have multiple
1754                     tags, and for each of them to have a binding for  a  par‐
1755                     ticular  event sequence. When this occurs, one binding is
1756                     invoked for each tag, in order  from  lowest-priority  to
1757                     highest priority. If there are multiple matching bindings
1758                     for a single tag, then the most specific binding is  cho‐
1759                     sen  (see  the  manual entry for the bind command for de‐
1760                     tails).  continue  and  break  commands  within   binding
1761                     scripts  are  processed  in  the same way as for bindings
1762                     created with the bind command.
1763
1764                     If bindings are created for the widget as a  whole  using
1765                     the bind command, then those bindings will supplement the
1766                     tag bindings. The tag bindings  will  be  invoked  first,
1767                     followed by bindings for the window as a whole.
1768
1769              pathName tag cget tagName option
1770                     This  command  returns  the  current  value of the option
1771                     named option associated with the tag  given  by  tagName.
1772                     Option  may  have any of the values accepted by the path‐
1773                     Name tag configure widget command.
1774
1775              pathName tag configure tagName ?option?  ?value?  ?option  value
1776              ...?
1777                     This  command is similar to the pathName configure widget
1778                     command except that it modifies options  associated  with
1779                     the tag given by tagName instead of modifying options for
1780                     the overall text widget. If no option is  specified,  the
1781                     command  returns  a  list describing all of the available
1782                     options for tagName (see Tk_ConfigureInfo for information
1783                     on  the format of this list). If option is specified with
1784                     no value, then the command returns a list describing  the
1785                     one named option (this list will be identical to the cor‐
1786                     responding sublist of the value returned if no option  is
1787                     specified).  If one or more option-value pairs are speci‐
1788                     fied, then the command modifies the  given  option(s)  to
1789                     have the given value(s) in tagName; in this case the com‐
1790                     mand returns an empty string.  See TAGS above for details
1791                     on the options available for tags.
1792
1793              pathName tag delete tagName ?tagName ...?
1794                     Deletes all tag information for each of the tagName argu‐
1795                     ments. The command removes the tags from  all  characters
1796                     in  the file and also deletes any other information asso‐
1797                     ciated with the tags, such as bindings and display infor‐
1798                     mation. The command returns an empty string.
1799
1800              pathName tag lower tagName ?belowThis?
1801                     Changes  the  priority  of tag tagName so that it is just
1802                     lower in priority than the tag whose name  is  belowThis.
1803                     If  belowThis  is  omitted,  then  tagName's  priority is
1804                     changed to make it lowest priority of all tags.
1805
1806              pathName tag names ?index?
1807                     Returns a list whose elements are the names  of  all  the
1808                     tags  that  are active at the character position given by
1809                     index. If index is omitted, then the  return  value  will
1810                     describe  all  of  the tags that exist for the text (this
1811                     includes all tags that have been  named  in  a  “pathName
1812                     tag” widget command but have not been deleted by a “path‐
1813                     Name tag delete” widget command, even  if  no  characters
1814                     are  currently  marked  with  the  tag). The list will be
1815                     sorted in order from lowest priority to highest priority.
1816
1817              pathName tag nextrange tagName index1 ?index2?
1818                     This command searches the text for a range of  characters
1819                     tagged  with  tagName  where  the  first character of the
1820                     range is no earlier than the character at index1  and  no
1821                     later  than  the  character  just  before index2 (a range
1822                     starting at index2 will not be  considered).  If  several
1823                     matching  ranges exist, the first one is chosen. The com‐
1824                     mand's return value is a list  containing  two  elements,
1825                     which  are  the index of the first character of the range
1826                     and the index of the character just after the last one in
1827                     the  range. If no matching range is found then the return
1828                     value is an empty string. If index2 is not given then  it
1829                     defaults to the end of the text.
1830
1831              pathName tag prevrange tagName index1 ?index2?
1832                     This  command searches the text for a range of characters
1833                     tagged with tagName where  the  first  character  of  the
1834                     range  is  before  the character at index1 and no earlier
1835                     than the character at index2 (a range starting at  index2
1836                     will  be  considered).  If several matching ranges exist,
1837                     the one closest to index1 is chosen. The command's return
1838                     value  is  a  list containing two elements, which are the
1839                     index of the first character of the range and  the  index
1840                     of the character just after the last one in the range. If
1841                     no matching range is found then the return  value  is  an
1842                     empty string.  If index2 is not given then it defaults to
1843                     the beginning of the text.
1844
1845              pathName tag raise tagName ?aboveThis?
1846                     Changes the priority of tag tagName so that  it  is  just
1847                     higher  in priority than the tag whose name is aboveThis.
1848                     If aboveThis  is  omitted,  then  tagName's  priority  is
1849                     changed to make it highest priority of all tags.
1850
1851              pathName tag ranges tagName
1852                     Returns  a list describing all of the ranges of text that
1853                     have been tagged with tagName. The first two elements  of
1854                     the list describe the first tagged range in the text, the
1855                     next two elements describe the second range, and  so  on.
1856                     The  first element of each pair contains the index of the
1857                     first character of the range, and the second  element  of
1858                     the  pair  contains the index of the character just after
1859                     the last one in the range. If  there  are  no  characters
1860                     tagged with tag then an empty string is returned.
1861
1862              pathName tag remove tagName index1 ?index2 index1 index2 ...?
1863                     Remove  the tag tagName from all of the characters start‐
1864                     ing at index1 and ending just before index2 (the  charac‐
1865                     ter at index2 is not affected). A single command may con‐
1866                     tain any number of index1-index2 pairs. If the  last  in‐
1867                     dex2  is  omitted then the tag is removed from the single
1868                     character at index1. If there are no  characters  in  the
1869                     specified  range (e.g. index1 is past the end of the file
1870                     or index2 is less than or equal to index1) then the  com‐
1871                     mand has no effect. This command returns an empty string.
1872
1873       pathName window option ?arg arg ...?
1874              This  command is used to manipulate embedded windows. The behav‐
1875              ior of the command depends on the option argument  that  follows
1876              the window argument. The following forms of the command are cur‐
1877              rently supported:
1878
1879              pathName window cget index option
1880                     Returns the value of a configuration option for an embed‐
1881                     ded  window.   Index  identifies the embedded window, and
1882                     option specifies a particular configuration option, which
1883                     must  be  one  of the ones listed in the section EMBEDDED
1884                     WINDOWS.
1885
1886              pathName window configure index ?option value ...?
1887                     Query or modify the configuration options for an embedded
1888                     window.  If  no  option  is specified, returns a list de‐
1889                     scribing all of the available options  for  the  embedded
1890                     window  at index (see Tk_ConfigureInfo for information on
1891                     the format of this list). If option is specified with  no
1892                     value, then the command returns a list describing the one
1893                     named option (this list will be identical to  the  corre‐
1894                     sponding  sublist  of  the value returned if no option is
1895                     specified). If one or more option-value pairs are  speci‐
1896                     fied,  then  the  command modifies the given option(s) to
1897                     have the given value(s); in this case the command returns
1898                     an  empty string. See EMBEDDED WINDOWS for information on
1899                     the options that are supported.
1900
1901              pathName window create index ?option value ...?
1902                     This command creates a new window annotation, which  will
1903                     appear  in  the  text at the position given by index. Any
1904                     number of option-value pairs may be specified to  config‐
1905                     ure  the annotation. See EMBEDDED WINDOWS for information
1906                     on the options  that  are  supported.  Returns  an  empty
1907                     string.
1908
1909              pathName window names
1910                     Returns  a  list whose elements are the names of all win‐
1911                     dows currently embedded in window.
1912
1913       pathName xview option args
1914              This command is used to query and change the horizontal position
1915              of  the text in the widget's window. It can take any of the fol‐
1916              lowing forms:
1917
1918              pathName xview
1919                     Returns a list containing two elements. Each element is a
1920                     real fraction between 0 and 1; together they describe the
1921                     portion of the document's horizontal span that is visible
1922                     in  the  window.  For example, if the first element is .2
1923                     and the second element is .6, 20% of  the  text  is  off-
1924                     screen to the left, the middle 40% is visible in the win‐
1925                     dow, and 40% of the text is off-screen to the right.  The
1926                     fractions refer only to the lines that are actually visi‐
1927                     ble in the window: if the lines in  the  window  are  all
1928                     very  short,  so  that they are entirely visible, the re‐
1929                     turned fractions will be 0 and 1, even if there are other
1930                     lines  in  the  text that are much wider than the window.
1931                     These are the same values passed to  scrollbars  via  the
1932                     -xscrollcommand option.
1933
1934              pathName xview moveto fraction
1935                     Adjusts  the  view  in the window so that fraction of the
1936                     horizontal span of the text is off-screen  to  the  left.
1937                     Fraction is a fraction between 0 and 1.
1938
1939              pathName xview scroll number what
1940                     This  command shifts the view in the window left or right
1941                     according to number and what. What must be  units,  pages
1942                     or  pixels. If what is units or pages then number must be
1943                     an integer, otherwise number may be specified in  any  of
1944                     the  forms  acceptable to Tk_GetPixels, such as “2.0c” or
1945                     “1i” (the result is rounded to the nearest integer value.
1946                     If  no  units  are given, pixels are assumed). If what is
1947                     units, the view adjusts left or right by number  average-
1948                     width  characters on the display; if it is pages then the
1949                     view adjusts by number screenfuls; if it is  pixels  then
1950                     the  view adjusts by number pixels. If number is negative
1951                     then characters farther to the left become visible; if it
1952                     is  positive  then characters farther to the right become
1953                     visible.
1954
1955       pathName yview ?args?
1956              This command is used to query and change the  vertical  position
1957              of  the text in the widget's window. It can take any of the fol‐
1958              lowing forms:
1959
1960              pathName yview
1961                     Returns a list containing two elements, both of which are
1962                     real  fractions  between 0 and 1. The first element gives
1963                     the position of the first  visible  pixel  of  the  first
1964                     character  (or image, etc) in the top line in the window,
1965                     relative to the text as a whole (0.5 means it is  halfway
1966                     through  the text, for example). The second element gives
1967                     the position of the first pixel just after the last visi‐
1968                     ble one in the bottom line of the window, relative to the
1969                     text as a whole. These are  the  same  values  passed  to
1970                     scrollbars via the -yscrollcommand option.
1971
1972              pathName yview moveto fraction
1973                     Adjusts the view in the window so that the pixel given by
1974                     fraction appears at the top of the top line of  the  win‐
1975                     dow.  Fraction is a fraction between 0 and 1; 0 indicates
1976                     the first pixel of the first character in the text,  0.33
1977                     indicates the pixel that is one-third the way through the
1978                     text; and so on. Values close to 1 will  indicate  values
1979                     close to the last pixel in the text (1 actually refers to
1980                     one pixel beyond the last pixel), but in such  cases  the
1981                     widget  will never scroll beyond the last pixel, and so a
1982                     value of 1 will effectively be rounded back  to  whatever
1983                     fraction  ensures  the last pixel is at the bottom of the
1984                     window, and some other pixel is at the top.
1985
1986              pathName yview scroll number what
1987                     This command adjust the view in the window up or down ac‐
1988                     cording  to number and what. What must be units, pages or
1989                     pixels. If what is units or pages then number must be  an
1990                     integer,  otherwise number may be specified in any of the
1991                     forms acceptable to Tk_GetPixels, such as “2.0c” or  “1i”
1992                     (the  result  is rounded to the nearest integer value. If
1993                     no units are given,  pixels  are  assumed).  If  what  is
1994                     units, the view adjusts up or down by number lines on the
1995                     display; if it is pages then the view adjusts  by  number
1996                     screenfuls; if it is pixels then the view adjusts by num‐
1997                     ber pixels. If number is negative then earlier  positions
1998                     in  the text become visible; if it is positive then later
1999                     positions in the text become visible.
2000
2001              pathName yview ?-pickplace? index
2002                     Changes the view in the widget's  window  to  make  index
2003                     visible.  If  the -pickplace option is not specified then
2004                     index will appear at the top of the window. If -pickplace
2005                     is  specified then the widget chooses where index appears
2006                     in the window:
2007
2008                     [1]    If index is already visible somewhere in the  win‐
2009                            dow then the command does nothing.
2010
2011                     [2]    If  index is only a few lines off-screen above the
2012                            window then it will be positioned at  the  top  of
2013                            the window.
2014
2015                     [3]    If  index is only a few lines off-screen below the
2016                            window then it will be positioned at the bottom of
2017                            the window.
2018
2019                     [4]    Otherwise, index will be centered in the window.
2020
2021                     The  -pickplace option has been obsoleted by the pathName
2022                     see widget command (pathName see handles both x-  and  y-
2023                     motion to make a location visible, whereas the -pickplace
2024                     mode only handles motion in y).
2025
2026              pathName yview number
2027                     This command makes the first character on the line  after
2028                     the one given by number visible at the top of the window.
2029                     Number must be an integer. This command used to  be  used
2030                     for scrolling, but now it is obsolete.
2031

BINDINGS

2033       Tk  automatically  creates  class bindings for texts that give them the
2034       following default behavior.  In the descriptions below, “word”  is  de‐
2035       pendent on the value of the tcl_wordchars variable.  See tclvars(n).
2036
2037       [1]    Clicking  mouse  button  1 positions the insertion cursor at the
2038              closest edge of the character underneath the mouse cursor,  sets
2039              the  input focus to this widget, and clears any selection in the
2040              widget. Dragging with mouse button 1 strokes out a selection be‐
2041              tween the insertion cursor and the character under the mouse.
2042
2043       [2]    Double-clicking  with  mouse button 1 selects the word under the
2044              mouse and positions the insertion cursor at  the  start  of  the
2045              word.  Dragging after a double click will stroke out a selection
2046              consisting of whole words.
2047
2048       [3]    Triple-clicking with mouse button 1 selects the line  under  the
2049              mouse  and  positions  the  insertion cursor at the start of the
2050              line. Dragging after a triple click will stroke out a  selection
2051              consisting of whole lines.
2052
2053       [4]    The ends of the selection can be adjusted by dragging with mouse
2054              button 1 while the Shift key is down; this will adjust  the  end
2055              of  the selection that was nearest to the mouse cursor when but‐
2056              ton 1 was pressed. If the button is double-clicked before  drag‐
2057              ging  then  the  selection  will  be  adjusted in units of whole
2058              words; if it is triple-clicked then the selection  will  be  ad‐
2059              justed in units of whole lines.
2060
2061       [5]    Clicking  mouse  button 1 with the Control key down will reposi‐
2062              tion the insertion cursor without affecting the selection.
2063
2064       [6]    If any normal printing characters are typed, they  are  inserted
2065              at the point of the insertion cursor.
2066
2067       [7]    The view in the widget can be adjusted by dragging with the mid‐
2068              dle mouse button (button 2, or button 3 in TkAqua). If the  mid‐
2069              dle mouse button is clicked without moving the mouse, the selec‐
2070              tion is copied into the text at the position of the  mouse  cur‐
2071              sor. The Insert key also inserts the selection, but at the posi‐
2072              tion of the insertion cursor.
2073
2074       [8]    If the mouse is dragged out of the  widget  while  button  1  is
2075              pressed,  the  entry will automatically scroll to make more text
2076              visible (if there is more text off-screen on the side where  the
2077              mouse left the window).
2078
2079       [9]    The  Left and Right keys move the insertion cursor one character
2080              to the left or right; they also clear any selection in the text.
2081              If  Left or Right is typed with the Shift key down, then the in‐
2082              sertion cursor moves and the selection is  extended  to  include
2083              the  new  character. Control-Left and Control-Right move the in‐
2084              sertion cursor by words,  and  Control-Shift-Left  and  Control-
2085              Shift-Right  move  the insertion cursor by words and also extend
2086              the selection. Control-b and Control-f behave the same  as  Left
2087              and  Right,  respectively.  Meta-b and Meta-f behave the same as
2088              Control-Left and Control-Right, respectively.
2089
2090       [10]   The Up and Down keys move the insertion cursor one  line  up  or
2091              down  and  clear  any  selection  in the text. If Up or Right is
2092              typed with the Shift key down, then the insertion  cursor  moves
2093              and the selection is extended to include the new character. Con‐
2094              trol-Up and Control-Down move the insertion cursor by paragraphs
2095              (groups of lines separated by blank lines), and Control-Shift-Up
2096              and Control-Shift-Down move the insertion cursor  by  paragraphs
2097              and  also  extend  the selection. Control-p and Control-n behave
2098              the same as Up and Down, respectively.
2099
2100       [11]   The Next and Prior keys move the  insertion  cursor  forward  or
2101              backwards  by one screenful and clear any selection in the text.
2102              If the Shift key is held down while Next or Prior is typed, then
2103              the selection is extended to include the new character.
2104
2105       [12]   Control-Next  and Control-Prior scroll the view right or left by
2106              one page without moving the insertion cursor  or  affecting  the
2107              selection.
2108
2109       [13]   Home and Control-a move the insertion cursor to the beginning of
2110              its display line and clear any selection in the  widget.  Shift-
2111              Home  moves the insertion cursor to the beginning of the display
2112              line and also extends the selection to that point.
2113
2114       [14]   End and Control-e move the insertion cursor to the  end  of  the
2115              display  line  and  clear any selection in the widget. Shift-End
2116              moves the cursor to the end of the display line and extends  the
2117              selection to that point.
2118
2119       [15]   Control-Home  and Meta-< move the insertion cursor to the begin‐
2120              ning of the text and clear any selection in the widget. Control-
2121              Shift-Home  moves  the  insertion cursor to the beginning of the
2122              text and also extends the selection to that point.
2123
2124       [16]   Control-End and Meta-> move the insertion cursor to the  end  of
2125              the  text  and clear any selection in the widget. Control-Shift-
2126              End moves the cursor to the end of the text and extends the  se‐
2127              lection to that point.
2128
2129       [17]   The Select key and Control-Space set the selection anchor to the
2130              position of the insertion cursor. They do not affect the current
2131              selection.  Shift-Select  and Control-Shift-Space adjust the se‐
2132              lection to the current position of the insertion cursor, select‐
2133              ing from the anchor to the insertion cursor if there was not any
2134              selection previously.
2135
2136       [18]   Control-/ selects the entire contents of the widget.
2137
2138       [19]   Control-\ clears any selection in the widget.
2139
2140       [20]   The F16 key (labelled Copy on many Sun workstations)  or  Meta-w
2141              copies the selection in the widget to the clipboard, if there is
2142              a  selection.  This  action  is  carried  out  by  the   command
2143              tk_textCopy.
2144
2145       [21]   The F20 key (labelled Cut on many Sun workstations) or Control-w
2146              copies the selection in the widget to the clipboard and  deletes
2147              the  selection.  This  action  is  carried  out  by  the command
2148              tk_textCut. If there is no selection in the  widget  then  these
2149              keys have no effect.
2150
2151       [22]   The  F18  key  (labelled Paste on many Sun workstations) or Con‐
2152              trol-y inserts the contents of the clipboard at the position  of
2153              the  insertion cursor. This action is carried out by the command
2154              tk_textPaste.
2155
2156       [23]   The Delete key deletes the selection, if there  is  one  in  the
2157              widget.  If  there  is no selection, it deletes the character to
2158              the right of the insertion cursor.
2159
2160       [24]   Backspace and Control-h delete the selection, if there is one in
2161              the widget.  If there is no selection, they delete the character
2162              to the left of the insertion cursor.
2163
2164       [25]   Control-d deletes the character to the right  of  the  insertion
2165              cursor.
2166
2167       [26]   Meta-d deletes the word to the right of the insertion cursor.
2168
2169       [27]   Control-k  deletes  from  the insertion cursor to the end of its
2170              line; if the insertion cursor is already at the end of  a  line,
2171              then Control-k deletes the newline character.
2172
2173       [28]   Control-o  opens  a new line by inserting a newline character in
2174              front of the insertion cursor without moving the insertion  cur‐
2175              sor.
2176
2177       [29]   Meta-backspace  and  Meta-Delete  delete the word to the left of
2178              the insertion cursor.
2179
2180       [30]   Control-x deletes whatever is selected in the text widget  after
2181              copying it to the clipboard.
2182
2183       [31]   Control-t  reverses the order of the two characters to the right
2184              of the insertion cursor.
2185
2186       [32]   Control-z undoes the last edit action if  the  -undo  option  is
2187              true.  Does nothing otherwise.
2188
2189       [33]   Control-Z  (or  Control-y  on Windows) reapplies the last undone
2190              edit action if the -undo option is true. Does nothing otherwise.
2191
2192       If the widget is disabled using the -state option, then  its  view  can
2193       still be adjusted and text can still be selected, but no insertion cur‐
2194       sor will be displayed and no text modifications will take place.
2195
2196       The behavior of texts can be changed by defining new bindings for indi‐
2197       vidual widgets or by redefining the class bindings.
2198

KNOWN ISSUES

2200   ISSUES CONCERNING CHARS AND INDICES
2201       Before Tk 8.5, the widget used the string “chars” to refer to index po‐
2202       sitions (which included characters, embedded windows and  embedded  im‐
2203       ages). As of Tk 8.5 the text widget deals separately and correctly with
2204       “chars” and “indices”.  For backwards compatibility, however, the index
2205       modifiers  “+N  chars” and “-N chars” continue to refer to indices. One
2206       must use any of the full forms “+N any chars” or “-N any chars” etc. to
2207       refer to actual character indices. This confusion may be fixed in a fu‐
2208       ture release by making the widget correctly interpret “+N chars”  as  a
2209       synonym for “+N any chars”.
2210
2211   PERFORMANCE ISSUES
2212       Text  widgets should run efficiently under a variety of conditions. The
2213       text widget uses about 2-3 bytes of main memory for each byte of  text,
2214       so  texts  containing  a  megabyte  or more should be practical on most
2215       workstations. Text is represented internally  with  a  modified  B-tree
2216       structure  that  makes  operations relatively efficient even with large
2217       texts. Tags are included in the B-tree structure in a way  that  allows
2218       tags  to span large ranges or have many disjoint smaller ranges without
2219       loss of efficiency. Marks are also implemented in  a  way  that  allows
2220       large  numbers of marks. In most cases it is fine to have large numbers
2221       of unique tags, or a tag that has many distinct ranges.
2222
2223       One performance problem can arise if you have hundreds or thousands  of
2224       different  tags  that all have the following characteristics: the first
2225       and last ranges of each tag are near the beginning and end of the text,
2226       respectively, or a single tag range covers most of the text widget. The
2227       cost of adding and deleting tags like this is proportional to the  num‐
2228       ber  of  other  tags with the same properties. In contrast, there is no
2229       problem with having thousands of distinct tags if their overall  ranges
2230       are localized and spread uniformly throughout the text.
2231
2232       Very  long  text  lines  can be expensive, especially if they have many
2233       marks and tags within them.
2234
2235       The display line with the insert cursor is redrawn each time the cursor
2236       blinks,  which causes a steady stream of graphics traffic. Set the -in‐
2237       sertofftime attribute to 0 avoid this.
2238
2239   KNOWN BUGS
2240       The pathName search -regexp sub-command attempts to  perform  sophisti‐
2241       cated  regexp  matching  across  multiple lines in an efficient fashion
2242       (since Tk 8.5), examining each line individually,  and  then  in  small
2243       groups of lines, whether searching forwards or backwards. Under certain
2244       conditions the search result might differ from that obtained by  apply‐
2245       ing  the  same regexp to the entire text from the widget in one go. For
2246       example, when searching with a greedy regexp, the widget will  continue
2247       to attempt to add extra lines to the match as long as one of two condi‐
2248       tions are true: either Tcl's regexp library returns a code to  indicate
2249       a  longer match is possible (but there are known bugs in Tcl which mean
2250       this code is not always correctly returned);  or  if  each  extra  line
2251       added  results in at least a partial match with the pattern. This means
2252       in the case where the first extra line added results in  no  match  and
2253       Tcl's  regexp system returns the incorrect code and adding a second ex‐
2254       tra line would actually match, the text widget will  return  the  wrong
2255       result. In practice this is a rare problem, but it can occur, for exam‐
2256       ple:
2257              pack [text .t]
2258              .t insert 1.0 "aaaa\nbbbb\ncccc\nbbbb\naaaa\n"
2259              .t search -regexp -- {(a+|b+\nc+\nb+)+\na+} 1.0
2260       will not find a match when one exists of 19  characters  starting  from
2261       the first “b”.
2262
2263       Whenever  one  possible  match is fully enclosed in another, the search
2264       command will attempt to ensure only the larger match is returned.  When
2265       performing  backwards  regexp searches it is possible that Tcl will not
2266       always achieve this, in the case where a match is preceded  by  one  or
2267       more  short,  non-overlapping  matches,  all of which are preceded by a
2268       large match which actually encompasses all of them.  The  search  algo‐
2269       rithm  used by the widget does not look back arbitrarily far for a pos‐
2270       sible match which might cover large portions of the widget.  For  exam‐
2271       ple:
2272              pack [text .t]
2273              .t insert 1.0 "aaaa\nbbbb\nbbbb\nbbbb\nbbbb\n"
2274              .t search -regexp -backward -- {b+\n|a+\n(b+\n)+} end
2275       matches  at “5.0” when a true greedy match would match at “1.0”.  Simi‐
2276       larly if we add -all to this case, it matches at all of  “5.0”,  “4.0”,
2277       “3.0”  and  “1.0”, when really it should only match at “1.0” since that
2278       match encloses all the others.
2279

SEE ALSO

2281       entry(n), scrollbar(n)
2282

KEYWORDS

2284       text, widget, tkvars
2285
2286
2287
2288Tk                                    8.5                              text(n)
Impressum