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

MARKS

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

EMBEDDED WINDOWS

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

EMBEDDED IMAGES

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

THE SELECTION

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

THE INSERTION CURSOR

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

THE MODIFIED FLAG

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

THE UNDO MECHANISM

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

PEER WIDGETS

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

ASYNCHRONOUS UPDATE OF LINE HEIGHTS

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

WIDGET COMMAND

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

BINDINGS

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

KNOWN ISSUES

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

SEE ALSO

2284       entry(n), scrollbar(n)
2285

KEYWORDS

2287       text, widget, tkvars
2288
2289
2290
2291Tk                                    8.5                              text(n)
Impressum