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 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       [-autoseparators autoSeparators] Specifies a boolean that says  whether
31       separators  are automatically inserted in the undo stack. Only meaning‐
32       ful when the -undo option is true.   [-blockcursor blockCursor]  Speci‐ │
33       fies  a  boolean that says whether the blinking insertion cursor should │
34       be drawn  as  a  character-sized  rectangular  block.   If  false  (the │
35       default) a thin vertical line is used for the insertion cursor.  [-end‐
36       line endLine] Specifies an integer line index representing the line  of │
37       the  underlying  textual  data store that should be just after the last │
38       line contained in the widget.  This allows a  text  widget  to  reflect │
39       only  a portion of a larger piece of text.   Instead of an integer, the │
40       empty string can be provided to this configuration option,  which  will │
41       configure  the  widget to end at the very last line in the textual data │
42       store.  [-height height] Specifies the desired height for  the  window,
43       in  units of characters in the font given by the -font option.  Must be
44       at  least  one.    [-inactiveselectbackground inactiveSelectBackground] │
45       Specifies  the  colour  to use for the selection (the sel tag) when the │
46       window does not have the input focus.  If empty, {}, then no  selection │
47       is  shown  when the window does not have the focus.  [-maxundo maxUndo]
48       Specifies the maximum number of  compound  undo  actions  on  the  undo
49       stack.  A  zero  or  a  negative  value  imply an unlimited undo stack.
50       [-spacing1 spacing1] Requests additional space above each text line  in
51       the widget, using any of the standard forms for screen distances.  If a
52       line wraps, this option only applies to the first line on the  display.
53       This  option may be overridden with -spacing1 options in tags.  [-spac‐
54       ing2 spacing2] For lines that wrap (so that they cover  more  than  one
55       line  on the display) this option specifies additional space to provide
56       between the display lines that represent a single line  of  text.   The
57       value  may  have  any of the standard forms for screen distances.  This
58       option may be overridden  with  -spacing2  options  in  tags.   [-spac‐
59       ing3 spacing3]  Requests  additional  space below each text line in the
60       widget, using any of the standard forms for  screen  distances.   If  a
61       line  wraps,  this option only applies to the last line on the display.
62       This option may be overridden with -spacing3 options in tags.  [-start‐
63       line startLine]  Specifies an integer line index representing the first │
64       line of the underlying textual data store that should be  contained  in │
65       the  widget.   This allows a text widget to reflect only a portion of a │
66       larger piece of text.  Instead of an integer, the empty string  can  be │
67       provided  to this configuration option, which will configure the widget │
68       to  start  at  the  very  first  line  in  the  textual   data   store.
69       [-state state]  Specifies  one  of  two states for the text:  normal or
70       disabled.  If the text is disabled then characters may not be  inserted
71       or deleted and no insertion cursor will be displayed, even if the input
72       focus is in the widget.  [-tabs tabs] Specifies a set of tab stops  for
73       the  window.  The option's value consists of a list of screen distances
74       giving the positions of the tab stops, each of which is a distance rel‐
75       ative to the left edge of the widget (excluding borders, padding, etc).
76       Each position may optionally be followed in the next  list  element  by
77       one  of  the  keywords left, right, center, or numeric, which specifies
78       how to justify text relative to the tab stop.  Left is the default;  it
79       causes  the  text following the tab character to be positioned with its
80       left edge at the tab position.  Right means that the right edge of  the
81       text following the tab character is positioned at the tab position, and
82       center means that the text is centered at the  tab  position.   Numeric
83       means that the decimal point in the text is positioned at the tab posi‐
84       tion;  if there is no decimal point then the least significant digit of
85       the  number  is  positioned  just  to the left of the tab position;  if
86       there is no number in the text then the text is right-justified at  the
87       tab  position.   For  example,  “-tabs  {2c left 4c 6c center}” creates
88       three tab stops at two-centimeter intervals;  the first  two  use  left
89       justification and the third uses center justification.
90
91              If  the list of tab stops does not have enough elements to cover
92              all of the tabs in a text line, then  Tk  extrapolates  new  tab
93              stops  using the spacing and alignment from the last tab stop in
94              the list.  Tab distances must be  strictly  positive,  and  must
95              always  increase from one tab stop to the next (if not, an error
96              is thrown).  The value of the tabs option may be  overridden  by
97              -tabs options in tags.
98
99              If  no  -tabs  option  is specified, or if it is specified as an
100              empty list, then Tk uses default tabs spaced every eight  (aver‐
101              age  size) characters.  To achieve a different standard spacing,
102              for example every 4 characters, simply configure the widget with
103-tabs  "[expr  {4  *  [font  measure $font 0]}] left" -tabstyle
104              wordprocessor”.
105       [-tabstyle tabStyle]  Specifies  how  to  interpret  the   relationship
106       between  tab  stops  on  a line and tabs in the text of that line.  The
107       value must be tabular (the default) or wordprocessor.  Note  that  tabs
108       are  interpreted as they are encountered in the text.  If the tab style
109       is tabular then the n'th tab character in the line's text will be asso‐
110       ciated  with the n'th tab stop defined for that line.  If the tab char‐
111       acter's x coordinate falls to the right of the n'th tab  stop,  then  a
112       gap of a single space will be inserted as a fallback.  If the tab style
113       is wordprocessor then any tab character being laid out will use (and be
114       defined by) the first tab stop to the right of the preceding characters
115       already laid out on that line.  The value of the tabstyle option may be
116       overridden  by  -tabstyle  options  in  tags.  [-undo undo] Specifies a
117       boolean that  says  whether  the  undo  mechanism  is  active  or  not.
118       [-width width]  Specifies  the desired width for the window in units of
119       characters in the font given by the -font option.  If the font does not
120       have  a  uniform  width  then the width of the character “0” is used in
121       translating from character units to screen units.  [-wrap wrap]  Speci‐
122       fies  how to handle lines in the text that are too long to be displayed
123       in a single line of the text's window.  The value must be none or  char
124       or  word.   A wrap mode of none means that each line of text appears as
125       exactly one line on the screen;  extra characters that do  not  fit  on
126       the  screen  are  not  displayed.  In the other modes each line of text
127       will be broken up into several screen lines if necessary  to  keep  all
128       the  characters  visible.   In  char mode a screen line break may occur
129       after any character; in word mode a line break will  only  be  made  at
130       word boundaries.
131_________________________________________________________________
132
133

DESCRIPTION

135       The  text command creates a new window (given by the pathName argument)
136       and makes it into a text widget.  Additional options, described  above,
137       may  be specified on the command line or in the option database to con‐
138       figure aspects of the text such as its  default  background  color  and
139       relief.  The text command returns the path name of the new window.
140
141       A  text  widget displays one or more lines of text and allows that text
142       to be edited.  Text widgets support four different kinds of annotations
143       on  the  text, called tags, marks, embedded windows or embedded images.
144       Tags allow different portions of the text to be displayed with  differ‐
145       ent fonts and colors.  In addition, Tcl commands can be associated with
146       tags so that scripts are invoked when particular actions such  as  key‐
147       strokes  and  mouse  button  presses  occur in particular ranges of the
148       text.  See TAGS below for more details.
149
150       The second form of annotation consists of floating markers in the  text
151       called  “marks”.   Marks  are used to keep track of various interesting
152       positions in the text as it  is  edited.   See  MARKS  below  for  more
153       details.
154
155       The third form of annotation allows arbitrary windows to be embedded in
156       a text widget.  See EMBEDDED WINDOWS below for more details.
157
158       The fourth form of annotation allows Tk images to be embedded in a text
159       widget.  See EMBEDDED IMAGES below for more details.
160
161       The  text widget also has a built-in undo/redo mechanism.  See THE UNDO
162       MECHANISM below for more details.
163
164       The text widget allows for the creation of  peer  widgets.   These  are │
165       other  text  widgets which share the same underlying data (text, marks, │
166       tags, images, etc).  See PEER WIDGETS below for more details.
167

INDICES

169       Many of the widget commands for texts take one or more indices as argu‐
170       ments.  An index is a string used to indicate a particular place within
171       a text, such as a place to insert characters or one endpoint of a range
172       of characters to delete.  Indices have the syntax
173              base modifier modifier modifier ...
174       Where  base  gives  a starting point and the modifiers adjust the index
175       from the starting point (e.g. move forward or backward one  character).
176       Every  index must contain a base, but the modifiers are optional.  Most │
177       modifiers (as documented below) allow an optional  submodifier.   Valid │
178       submodifiers  are  any  and display. If the submodifier is abbreviated, │
179       then it must be followed by whitespace, but otherwise there need be  no │
180       space  between  the  submodifier and the following modifier.  Typically │
181       the display submodifier adjusts the meaning of the  following  modifier
182       to  make  it  refer  to  visual or non-elided units rather than logical │
183       units, but this is explained for each  relevant  case  below.   Lastly, │
184       where  count is used as part of a modifier, it can be positive or nega‐ │
185       tive, so “base - -3 lines” is perfectly valid (and equivalent to  “base
186       +3lines”).
187
188       The base for an index must have one of the following forms:
189
190       line.char   Indicates  char'th  character on line line.  Lines are num‐
191                   bered from 1 for consistency with other UNIX programs  that
192                   use  this  numbering scheme.  Within a line, characters are
193                   numbered from 0.  If char is end then it refers to the new‐
194                   line character that ends the line.
195
196       @x,y        Indicates the character that covers the pixel whose x and y
197                   coordinates within the text's window are x and y.
198
199       end         Indicates the end of the text (the character just after the
200                   last newline).
201
202       mark        Indicates  the  character just after the mark whose name is
203                   mark.
204
205       tag.first   Indicates the first character in the  text  that  has  been
206                   tagged  with tag.  This form generates an error if no char‐
207                   acters are currently tagged with tag.
208
209       tag.last    Indicates the character just after the last one in the text
210                   that  has  been  tagged  with  tag.  This form generates an
211                   error if no characters are currently tagged with tag.
212
213       pathName    Indicates the position of the embedded window whose name is
214                   pathName.   This  form  generates  an  error if there is no
215                   embedded window by the given name.
216
217       imageName   Indicates the position of the embedded image whose name  is
218                   imageName.   This  form  generates  an error if there is no
219                   embedded image by the given name.
220
221       If the base could match more than one of the above  forms,  such  as  a
222       mark and imageName both having the same value, then the form earlier in
223       the above list takes precedence.  If modifiers follow the  base  index,
224       each  one  of  them  must have one of the forms listed below.  Keywords
225       such as chars and wordend may be abbreviated as long as  the  abbrevia‐
226       tion is unambiguous.
227
228       + count ?submodifier? chars
229              Adjust  the  index  forward by count characters, moving to later │
230              lines in the text if necessary.  If there are fewer  than  count
231              characters  in  the  text  after the current index, then set the │
232              index to the last index in the text.  Spaces on either  side  of │
233              count are optional.  If the display submodifier is given, elided │
234              characters are skipped over without being counted.   If  any  is │
235              given, then all characters are counted.  For historical reasons, │
236              if neither modifier is given then the count actually takes place │
237              in units of index positions (see indices for details).  This be‐ │
238              haviour may be changed in a future major release, so if you need │
239              an  index count, you are encouraged to use indices instead wher‐ │
240              ever possible.
241
242       - count ?submodifier? chars
243              Adjust the index backward by count characters, moving to earlier
244              lines  in  the text if necessary.  If there are fewer than count
245              characters in the text before the current index,  then  set  the
246              index  to  the  first index in the text (1.0).  Spaces on either │
247              side of count are  optional.   If  the  display  submodifier  is │
248              given, elided characters are skipped over without being counted. │
249              If any is given, then all characters are counted.  For  histori‐ │
250              cal  reasons,  if neither modifier is given then the count actu‐ │
251              ally takes place in units of index positions  (see  indices  for │
252              details).   This  behaviour  may  be  changed  in a future major │
253              release, so if you need an index count, you  are  encouraged  to │
254              use indices instead wherever possible.
255
256       + count ?submodifier? indices
257              Adjust  the  index  forward  by count index positions, moving to │
258              later lines in the text if necessary.  If there are  fewer  than │
259              count  index positions in the text after the current index, then │
260              set the index to the last index position in the text.  Spaces on │
261              either  side of count are optional.  Note that an index position │
262              is either a single character  or  a  single  embedded  image  or │
263              embedded  window.   If  the display submodifier is given, elided │
264              indices are skipped over  without  being  counted.   If  any  is │
265              given,  then  all  indices are counted; this is also the default │
266              behaviour if no modifier is given.
267
268       - count ?submodifier? indices
269              Adjust the index backward by count index  positions,  moving  to │
270              earlier lines in the text if necessary.  If there are fewer than │
271              count index positions in the text before the current index, then │
272              set  the  index  to  the first index position (1.0) in the text. │
273              Spaces on either side of count are  optional.   If  the  display 
274              submodifier  is  given,  elided indices are skipped over without │
275              being counted.  If any is given, then all indices  are  counted; │
276              this is also the default behaviour if no modifier is given.
277
278       + count ?submodifier? lines
279              Adjust  the  index  forward  by  count lines, retaining the same │
280              character position within the line.  If  there  are  fewer  than │
281              count  lines  after  the line containing the current index, then │
282              set the index to refer to the same  character  position  on  the │
283              last  line of the text.  Then, if the line is not long enough to │
284              contain a character at the indicated character position,  adjust │
285              the  character  position  to  refer to the last character of the │
286              line  (the  newline).   Spaces  on  either  side  of  count  are │
287              optional.  If the display submodifier is given, then each visual │
288              display line is counted separately.  Otherwise, if  any  (or  no │
289              modifier)  is  given, then each logical line (no matter how many │
290              times it is visually wrapped) counts just once.  If the relevant │
291              lines  are  not  wrapped, then these two methods of counting are │
292              equivalent.
293
294       - count ?submodifier? lines
295              Adjust the index backward by count logical lines, retaining  the │
296              same  character  position  within  the line.  If there are fewer │
297              than count lines before the line containing the  current  index, │
298              then  set  the  index to refer to the same character position on │
299              the first line of the text.  Then,  if  the  line  is  not  long │
300              enough  to  contain a character at the indicated character posi‐ │
301              tion, adjust the character position to refer to the last charac‐ │
302              ter  of  the line (the newline).  Spaces on either side of count
303              are optional.  If the display submodifier is  given,  then  each │
304              visual  display  line  is counted separately.  Otherwise, if any 
305              (or no modifier) is given, then each logical line (no matter how │
306              many  times  it  is  visually wrapped) counts just once.  If the │
307              relevant lines are not wrapped, then these two methods of count‐ │
308              ing are equivalent.
309
310       ?submodifier? linestart
311              Adjust  the  index  to refer to the first index on the line.  If │
312              the display submodifier is given, this is the first index on the │
313              display line, otherwise on the logical line.
314
315       ?submodifier? lineend
316              Adjust  the  index  to  refer to the last index on the line (the │
317              newline).  If the display submodifier is given, this is the last │
318              index on the display line, otherwise on the logical line.
319
320       ?submodifier? wordstart
321              Adjust  the  index  to  refer to the first character of the word │
322              containing the current index.  A word consists of any number  of │
323              adjacent characters that are letters, digits, or underscores, or │
324              a single character that is not one of  these.   If  the  display 
325              submodifier  is given, this only examines non-elided characters, │
326              otherwise all characters (elided or not) are examined.
327
328       ?submodifier? wordend
329              Adjust the index to refer to the character just after  the  last │
330              one  of  the  word containing the current index.  If the current │
331              index refers to the last character of the text then  it  is  not │
332              modified.   If the display submodifier is given, this only exam‐ │
333              ines non-elided characters, otherwise all characters (elided  or │
334              not) are examined.                                               │
335
336       If  more than one modifier is present then they are applied in left-to- │
337       right order.  For example, the index “end -  1  chars”  refers  to  the │
338       next-to-last  character in the text and “insert wordstart - 1 c” refers │
339       to the character just before the first one in the word  containing  the │
340       insertion  cursor.   Modifiers  are  applied one by one in this left to │
341       right order, and after each step the resulting index is constrained  to │
342       be  a  valid index in the text widget.  So, for example, the index “1.0 
343       -1c +1c” refers to the index “2.0”.                                     │
344
345       Where modifiers result in index changes by display lines, display chars │
346       or  display  indices,  and the base refers to an index inside an elided │
347       tag, that base index is considered to be equivalent to the  first  fol‐ │
348       lowing non-elided index.
349

TAGS

351       The first form of annotation in text widgets is a tag.  A tag is a tex‐
352       tual string that is associated with some of the characters in  a  text.
353       Tags may contain arbitrary characters, but it is probably best to avoid
354       using the characters “ ” (space), +, or -: these characters  have  spe‐
355       cial  meaning  in  indices,  so  tags containing them cannot be used as
356       indices.  There may be any number of tags associated with characters in
357       a  text.   Each tag may refer to a single character, a range of charac‐
358       ters, or several ranges of characters.   An  individual  character  may
359       have any number of tags associated with it.
360
361       A  priority  order  is  defined  among  tags, and this order is used in
362       implementing some of the tag-related functions described below.  When a
363       tag  is  defined (by associating it with characters or setting its dis‐
364       play options or binding commands to it), it is given a priority  higher
365       than  any  existing  tag.   The priority order of tags may be redefined
366       using the “pathName tag raise” and “pathName  tag  lower”  widget  com‐
367       mands.
368
369       Tags serve three purposes in text widgets.  First, they control the way
370       information is displayed on the screen.   By  default,  characters  are
371       displayed  as  determined  by  the  -background, -font, and -foreground
372       options for the text widget.  However, display options may  be  associ‐
373       ated  with  individual  tags  using the “pathName tag configure” widget
374       command.  If a character has been  tagged,  then  the  display  options
375       associated  with  the tag override the default display style.  The fol‐
376       lowing options are currently supported for tags:
377
378       -background color
379              Color specifies the background color to use for characters asso‐
380              ciated  with  the tag.  It may have any of the forms accepted by
381              Tk_GetColor.
382
383       -bgstipple bitmap
384              Bitmap specifies a bitmap that is used as a stipple pattern  for
385              the  background.   It  may  have  any  of  the forms accepted by
386              Tk_GetBitmap.  If bitmap has not been specified,  or  if  it  is
387              specified as an empty string, then a solid fill will be used for
388              the background.
389
390       -borderwidth pixels
391              Pixels specifies the width of a 3-D border to  draw  around  the
392              background.  It may have any of the forms accepted by Tk_GetPix‐
393              els.  This option is used in conjunction with the -relief option
394              to give a 3-D appearance to the background for characters; it is
395              ignored unless the -background option has been set for the tag.
396
397       -elide boolean
398              Elide specifies whether the data should be elided.  Elided  data
399              (characters, images, embedded windows, etc) is not displayed and
400              takes no space on screen, but further on behaves just as  normal
401              data.
402
403       -fgstipple bitmap
404              Bitmap specifies a bitmap that is used as a stipple pattern when
405              drawing text and other foreground  information  such  as  under‐
406              lines.   It  may have any of the forms accepted by Tk_GetBitmap.
407              If bitmap has not been specified, or if it is  specified  as  an
408              empty string, then a solid fill will be used.
409
410       -font fontName
411              FontName  is  the  name of a font to use for drawing characters.
412              It may have any of the forms accepted by Tk_GetFont.
413
414       -foreground color
415              Color specifies the color to use when  drawing  text  and  other
416              foreground  information  such as underlines.  It may have any of
417              the forms accepted by Tk_GetColor.
418
419       -justify justify
420              If the first non-elided character of a display line  has  a  tag
421              for  which  this  option has been specified, then justify deter‐
422              mines how to justify the line.  It must be one of  left,  right,
423              or  center.   If  a  line wraps, then the justification for each
424              line on the display is determined by the first non-elided  char‐
425              acter of that display line.
426
427       -lmargin1 pixels
428              If  the  first non-elided character of a text line has a tag for
429              which this option has been specified, then pixels specifies  how
430              much  the line should be indented from the left edge of the win‐
431              dow.  Pixels may have any of the standard forms for screen  dis‐
432              tances.   If  a  line of text wraps, this option only applies to
433              the first line on the display;  the  -lmargin2  option  controls
434              the indentation for subsequent lines.
435
436       -lmargin2 pixels
437              If  the  first  non-elided character of a display line has a tag
438              for which this option has been specified,  and  if  the  display
439              line is not the first for its text line (i.e., the text line has
440              wrapped), then pixels specifies how  much  the  line  should  be
441              indented  from the left edge of the window.  Pixels may have any
442              of the standard forms for screen distances.  This option is only
443              used when wrapping is enabled, and it only applies to the second
444              and later display lines for a text line.
445
446       -offset pixels
447              Pixels specifies an amount by which the text's  baseline  should
448              be  offset  vertically from the baseline of the overall line, in
449              pixels.  For example, a positive offset can be used  for  super‐
450              scripts  and a negative offset can be used for subscripts.  Pix‐
451              els may have any of the standard forms for screen distances.
452
453       -overstrike boolean
454              Specifies whether or not to draw a horizontal rule  through  the
455              middle  of  characters.   Boolean  may  have  any  of  the forms
456              accepted by Tcl_GetBoolean.
457
458       -relief relief
459              Relief specifies the 3-D relief to use for drawing  backgrounds,
460              in  any  of  the forms accepted by Tk_GetRelief.  This option is
461              used in conjunction with the -borderwidth option to give  a  3-D
462              appearance  to  the  background  for  characters;  it is ignored
463              unless the -background option has been set for the tag.
464
465       -rmargin pixels
466              If the first non-elided character of a display line  has  a  tag
467              for  which this option has been specified, then pixels specifies
468              how wide a margin to leave between the end of the line  and  the
469              right  edge  of the window.  Pixels may have any of the standard
470              forms for screen distances.  This option is only used when wrap‐
471              ping  is  enabled.   If  a text line wraps, the right margin for
472              each line on the display is determined by the  first  non-elided
473              character of that display line.
474
475       -spacing1 pixels
476              Pixels  specifies how much additional space should be left above
477              each text line, using any of the standard forms for screen  dis‐
478              tances.   If a line wraps, this option only applies to the first
479              line on the display.
480
481       -spacing2 pixels
482              For lines that wrap, this option specifies how  much  additional
483              space to leave between the display lines for a single text line.
484              Pixels may have any of the standard forms for screen distances.
485
486       -spacing3 pixels
487              Pixels specifies how much additional space should be left  below
488              each  text line, using any of the standard forms for screen dis‐
489              tances.  If a line wraps, this option only applies to  the  last
490              line on the display.
491
492       -tabs tabList
493              TabList specifies a set of tab stops in the same form as for the
494              -tabs option for the text widget.  This option only applies to a
495              display  line if it applies to the first non-elided character on
496              that display line.  If this option  is  specified  as  an  empty
497              string,  it  cancels  the option, leaving it unspecified for the
498              tag (the default).  If the option is specified  as  a  non-empty
499              string  that  is  an  empty  list,  such  as  -tags { }, then it
500              requests default 8-character tabs as  described  for  the  -tags
501              widget option.
502
503       -tabstyle style
504              Style  specifies  either  the  tabular or wordprocessor style of
505              tabbing to use for the text widget.  This option only applies to
506              a  display  line if it applies to the first non-elided character
507              on that display line.  If this option is specified as  an  empty
508              string,  it  cancels  the option, leaving it unspecified for the
509              tag (the default).
510
511       -underline boolean
512              Boolean specifies whether or not to draw an underline underneath
513              characters.   It  may have any of the forms accepted by Tcl_Get‐
514              Boolean.
515
516       -wrap mode
517              Mode specifies how to handle  lines  that  are  wider  than  the
518              text's window.  It has the same legal values as the -wrap option
519              for the text widget:  none, char, or word.  If this  tag  option
520              is specified, it overrides the -wrap option for the text widget.
521
522       If  a  character has several tags associated with it, and if their dis‐
523       play options conflict, then the options of the highest priority tag are
524       used.  If a particular display option has not been specified for a par‐
525       ticular tag, or if it is specified as an empty string, then that option
526       will  never  be used;  the next-highest-priority tag's option will used
527       instead.  If no tag specifies a particular  display  option,  then  the
528       default style for the widget will be used.
529
530       The second purpose for tags is event bindings.  You can associate bind‐
531       ings with a tag in much the same way you can associate bindings with  a
532       widget  class:   whenever  particular X events occur on characters with
533       the given tag, a given Tcl command will be executed.  Tag bindings  can
534       be  used to give behaviors to ranges of characters; among other things,
535       this allows hypertext-like features to be  implemented.   For  details,
536       see  the  description  of the “pathName tag bind” widget command below. │
537       Tag bindings are shared between all peer widgets (including  any  bind‐ │
538       ings for the special sel tag).
539
540       The third use for tags is in managing the selection.  See THE SELECTION
541       below.  With the exception of the special sel tag, all tags are  shared │
542       between  peer  text  widgets,  and may be manipulated on an equal basis │
543       from any such widget.  The sel tag exists separately and  independently │
544       in each peer text widget (but any tag bindings to sel are shared).
545

MARKS

547       The  second  form  of  annotation in text widgets is a mark.  Marks are
548       used for remembering particular places in a text.  They  are  something
549       like  tags,  in  that  they  have names and they refer to places in the
550       file,  but  a  mark  is  not  associated  with  particular  characters.
551       Instead,  a  mark  is  associated  with the gap between two characters.
552       Only a single position may be associated with a mark at any given time.
553       If the characters around a mark are deleted the mark will still remain;
554       it will just have new neighbor characters.  In contrast, if the charac‐
555       ters  containing  a tag are deleted then the tag will no longer have an
556       association with characters in the file.  Marks may be manipulated with
557       the  “pathName mark” widget command, and their current locations may be
558       determined by using the mark name as an index in widget commands.
559
560       Each mark also has a “gravity”, which is either  left  or  right.   The
561       gravity  for  a  mark  specifies  what happens to the mark when text is
562       inserted at the point of the mark.  If a mark has  left  gravity,  then
563       the  mark  is  treated  as  if it were attached to the character on its
564       left, so the mark will remain to the left of any text inserted  at  the
565       mark position.  If the mark has right gravity, new text inserted at the
566       mark position will appear to the left of the mark  (so  that  the  mark
567       remains rightmost).  The gravity for a mark defaults to right.
568
569       The  name  space  for  marks is different from that for tags:  the same
570       name may be used for both a mark and a tag, but they will refer to dif‐
571       ferent things.
572
573       Two marks have special significance.  First, the mark insert is associ‐
574       ated with the insertion cursor, as described under THE INSERTION CURSOR
575       below.  Second, the mark current is associated with the character clos‐
576       est to the mouse and is adjusted automatically to track the mouse posi‐
577       tion and any changes to the text in the widget (one exception:  current
578       is not updated in response to mouse motions if a mouse button is  down;
579       the  update  will  be  deferred  until  all  mouse  buttons  have  been
580       released).  Neither of these special marks may be  deleted.   With  the │
581       exception of these two special marks, all marks are shared between peer │
582       text widgets, and may be manipulated on an equal basis from any peer.
583

EMBEDDED WINDOWS

585       The third form of annotation in text widgets  is  an  embedded  window.
586       Each  embedded  window  annotation causes a window to be displayed at a
587       particular point in  the text.  There may be  any  number  of  embedded
588       windows  in  a  text  widget, and any widget may be used as an embedded
589       window (subject to the  usual  rules  for  geometry  management,  which
590       require  the  text  window to be the parent of the embedded window or a
591       descendant of its parent).   The  embedded  window's  position  on  the
592       screen will be updated as the text is modified or scrolled, and it will
593       be mapped and unmapped as it moves into and out of the visible area  of
594       the  text  widget.   Each  embedded window occupies one unit's worth of │
595       index space in the text widget, and it may be referred to either by the
596       name  of  its  embedded window or by its position in the widget's index
597       space.  If the range of text containing the embedded window is  deleted
598       then  the window is destroyed.  Similarly if the text widget as a whole │
599       is deleted, then the window is destroyed.
600
601       When an embedded window is added to a text  widget  with  the  pathName
602       window  create  widget  command,  several  configuration options may be
603       associated with it.  These options may  be   modified  later  with  the
604       pathName  window  configure  widget command.  The following options are
605       currently supported:
606
607       -align where
608              If the window is not as tall as the line in  which  it  is  dis‐
609              played,  this option determines where the window is displayed in
610              the line.  Where must have one of the values top (align the  top
611              of the window with the top of the line), center (center the win‐
612              dow within the range of the line), bottom (align the  bottom  of
613              the  window  with  the  bottom  of the line's area), or baseline
614              (align the bottom of the window with the baseline of the line).
615
616       -create script
617              Specifies a Tcl script that may be evaluated to create the  win‐
618              dow for the annotation.  If no -window option has been specified
619              for the annotation this script will be evaluated when the  anno‐
620              tation is about to be displayed on the screen.  Script must cre‐
621              ate a window for the annotation and return the name of that win‐
622              dow  as  its  result.   Two  substitutions  will be performed in │
623              script before evaluation.  %W will be substituted by the name of │
624              the  parent  text widget, and %% will be substituted by a single │
625              %.  If the annotation's window should ever  be  deleted,  script
626              will  be  evaluated  again  the next time the annotation is dis‐
627              played.
628
629       -padx pixels
630              Pixels specifies the amount of extra space to leave on each side
631              of  the  embedded  window.   It  may have any of the usual forms
632              defined for a screen distance.
633
634       -pady pixels
635              Pixels specifies the amount of extra space to leave on  the  top
636              and  on  the  bottom of the embedded window.  It may have any of
637              the usual forms defined for a screen distance.
638
639       -stretch boolean
640              If the requested height of the embedded window is less than  the
641              height  of the line in which it is displayed, this option can be
642              used to specify whether the window should  be  stretched  verti‐
643              cally  to fill its line.  If the -pady option has been specified
644              as well, then the requested padding will be retained even if the
645              window is stretched.
646
647       -window pathName
648              Specifies  the  name  of  a window to display in the annotation. │
649              Note that if a pathName has been set, then later  configuring  a │
650              window  to  the  empty  string will not delete the widget corre‐ │
651              sponding to the old pathName. Rather it will remove the associa‐ │
652              tion  between the old pathName and the text widget.  If multiple │
653              peer widgets are in use, it is usually simpler to use the  -cre‐ 
654              ate option if embedded windows are desired in each peer.
655

EMBEDDED IMAGES

657       The  final  form  of  annotation  in text widgets is an embedded image.
658       Each embedded image annotation causes an image to  be  displayed  at  a
659       particular  point  in   the  text.  There may be any number of embedded
660       images in a text widget, and a particular image may be embedded in mul‐
661       tiple places in the same text widget.  The embedded image's position on
662       the screen will be updated as the text is modified or  scrolled.   Each
663       embedded  image  occupies  one  unit's worth of index space in the text │
664       widget, and it may be referred to either by its position  in  the  wid‐
665       get's  index  space,  or  the  name  it  is  assigned when the image is
666       inserted into the text widget with pathName image create.  If the range
667       of  text containing the embedded image is deleted then that copy of the
668       image is removed from the screen.
669
670       When an embedded image is added to a  text  widget  with  the  pathName
671       image  create  widget  command,  a  name unique to this instance of the
672       image is returned.  This name may then be used to refer to  this  image
673       instance.   The  name  is  taken  to  be  the value of the -name option
674       (described below).  If the -name option is  not  provided,  the  -image
675       name  is  used instead.  If the imageName is already in use in the text
676       widget, then #nn is added to the end of the imageName, where nn  is  an
677       arbitrary  integer.   This  insures the imageName is unique.  Once this
678       name is assigned to this instance of the image,  it  does  not  change,
679       even  though  the  -image  or -name values can be changed with pathName
680       image configure.
681
682       When an embedded image is added to a  text  widget  with  the  pathName
683       image create widget command, several configuration options may be asso‐
684       ciated with it.  These options may be modified later with the  pathName
685       image  configure  widget  command.  The following options are currently
686       supported:
687
688       -align where
689              If the image is not as tall as the line  in  which  it  is  dis‐
690              played,  this  option determines where the image is displayed in
691              the line.  Where must have one of the values top (align the  top
692              of the image with the top of the line), center (center the image
693              within the range of the line), bottom (align the bottom  of  the
694              image  with  the  bottom of the line's area), or baseline (align
695              the bottom of the image with the baseline of the line).
696
697       -image image
698              Specifies the name of the Tk image to display in the annotation.
699              If image is not a valid Tk image, then an error is returned.
700
701       -name ImageName
702              Specifies  the  name  by which this image instance may be refer‐
703              enced in the text widget. If ImageName is not supplied, then the
704              name  of  the  Tk  image  is  used instead.  If the imageName is
705              already in use, #nn is appended  to  the  end  of  the  name  as
706              described above.
707
708       -padx pixels
709              Pixels specifies the amount of extra space to leave on each side
710              of the embedded image.  It may  have  any  of  the  usual  forms
711              defined for a screen distance.
712
713       -pady pixels
714              Pixels  specifies  the amount of extra space to leave on the top
715              and on the bottom of the embedded image.  It may have any of the
716              usual forms defined for a screen distance.
717

THE SELECTION

719       Selection  support  is  implemented  via  tags.  If the exportSelection
720       option for the text widget is true then the sel tag will be  associated
721       with the selection:
722
723       [1]    Whenever  characters  are  tagged  with sel the text widget will
724              claim ownership of the selection.
725
726       [2]    Attempts to retrieve the selection will be serviced by the  text
727              widget, returning all the characters with the sel tag.
728
729       [3]    If  the  selection  is claimed away by another application or by
730              another window within this application, then the sel tag will be
731              removed from all characters in the text.
732
733       [4]    Whenever the sel tag range changes a virtual event <<Selection>>
734              is generated.
735
736       The sel tag is automatically defined when a text widget is created, and
737       it  may  not  be deleted with the “pathName tag delete” widget command.
738       Furthermore, the selectBackground, selectBorderWidth,  and  selectFore‐
739       ground  options  for the text widget are tied to the -background, -bor‐
740       derwidth, and -foreground options for the sel tag:  changes  in  either
741       will  automatically  be  reflected in the other.  Also the -inactivese‐ 
742       lectbackground option for the text widget is used instead  of  -select‐ 
743       background  when  the text widget does not have the focus.  This allows │
744       programmatic control over the visualization of the sel  tag  for  fore‐ │
745       ground  and  background  windows, or to have sel not shown at all (when │
746       -inactiveselectbackground is empty) for background windows.  Each  peer │
747       text  widget has its own sel tag which can be separately configured and │
748       set.
749

THE INSERTION CURSOR

751       The mark named insert has special significance in text widgets.  It  is
752       defined  automatically  when a text widget is created and it may not be
753       unset with the “pathName mark unset” widget command.  The  insert  mark
754       represents the position of the insertion cursor, and the insertion cur‐
755       sor will automatically be drawn at this point whenever the text  widget
756       has the input focus.
757

THE MODIFIED FLAG

759       The  text widget can keep track of changes to the content of the widget
760       by means of the modified flag. Inserting or deleting text will set this
761       flag.  The  flag  can  be  queried, set and cleared programmatically as
762       well. Whenever the flag changes state a <<Modified>> virtual  event  is
763       generated.  See  the  pathName  edit  modified  widget command for more
764       details.
765

THE UNDO MECHANISM

767       The text widget has an unlimited undo  and  redo  mechanism  (when  the
768       -undo  widget  option  is  true)  which records every insert and delete
769       action on a stack.
770
771       Boundaries (called “separators”) are  inserted  between  edit  actions.
772       The  purpose  of  these  separators  is  to  group inserts, deletes and
773       replaces into one compound edit action.  When undoing a  change  every‐
774       thing  between  two  separators will be undone.  The undone changes are
775       then moved to the redo stack, so that an  undone  edit  can  be  redone
776       again.   The  redo  stack  is  cleared  whenever  new  edit actions are
777       recorded on the undo stack.  The undo and redo stacks can be cleared to
778       keep their depth under control.
779
780       Separators  are  inserted automatically when the -autoseparators widget
781       option is true.  You can insert separators  programmatically  as  well.
782       If a separator is already present at the top of the undo stack no other
783       will be inserted.  That means that two separators on the undo stack are
784       always separated by at least one insert or delete action.
785
786       The  undo  mechanism  is  also linked to the modified flag.  This means
787       that undoing or redoing changes can take a modified text widget back to
788       the  unmodified  state  or  vice  versa.  The modified flag will be set
789       automatically to the appropriate state.  This automatic  coupling  does
790       not  work  when  the  modified flag has been set by the user, until the
791       flag has been reset again.
792
793       See below for the pathName edit widget command that controls  the  undo
794       mechanism.
795

PEER WIDGETS

797       The  text  widget  has a separate store of all its data concerning each │
798       line's textual contents, marks, tags, images and windows, and the  undo │
799       stack.                                                                  │
800
801       While  this data store cannot be accessed directly (i.e. without a text │
802       widget as an intermediary), multiple text widgets can be created,  each │
803       of  which  present  different  views on the same underlying data.  Such │
804       text widgets are known as peer text widgets.                            │
805
806       As text is added, deleted, edited and coloured in any one  widget,  and │
807       as images, marks, tags are adjusted, all such changes will be reflected │
808       in all peers.                                                           │
809
810       All data and markup is shared, except for a few small details.   First, │
811       the  sel  tag  may be set and configured (in its display style) differ‐ │
812       ently for each peer.  Second, each peer has its own insert and  current 
813       mark  positions (but all other marks are shared).  Third, embedded win‐ │
814       dows, which are arbitrary  other  widgets,  cannot  be  shared  between │
815       peers.   This  means the -window option of embedded windows is indepen‐ │
816       dently set for each peer (it is advisable to  use  the  -create  script │
817       capabilities  to  allow each peer to create its own embedded windows as │
818       needed).  Fourth, all of the configuration options of each  peer  (e.g. │
819       -font,  etc)  can  be  set  independently, with the exception of -undo, │
820       -maxUndo, -autoSeparators (i.e.  all  undo,  redo  and  modified  state │
821       issues are shared).                                                     │
822
823       Finally  any single peer need not contain all lines from the underlying │
824       data store.  When creating a peer, a contiguous range  of  lines  (e.g. │
825       only  lines  52  through  125) may be specified.  This allows a peer to │
826       contain just a small portion of the overall text.  The range  of  lines │
827       will expand and contract as text is inserted or deleted.  The peer will │
828       only ever display complete lines of text (one cannot share just part of │
829       a  line).   If  the peer's contents contracts to nothing (i.e. all com‐ │
830       plete lines in the peer widget have been deleted from another  widget), │
831       then it is impossible for new lines to be inserted.  The peer will sim‐ │
832       ply become an empty shell on which the background  can  be  configured, │
833       but  which  will never show any content (without manual reconfiguration │
834       of the start and end lines).  Note that a peer which does  not  contain │
835       all  of the underlying data store still has indices numbered from “1.0” │
836       to “end”.  It is simply that those indices  reflect  a  subset  of  the │
837       total  data,  and data outside the contained range is not accessible to │
838       the peer.  This means that the command peerName index  end  may  return │
839       quite  different  values  in different peers.  Similarly, commands like │
840       peerName tag ranges will not return index ranges outside that which  is │
841       meaningful to the peer.  The configuration options -startline and -end‐ 
842       line may be used to control how much of the  underlying  data  is  con‐ │
843       tained in any given text widget.                                        │
844
845       Note  that peers are really peers.  Deleting the “original” text widget │
846       will not cause any other peers to be deleted, or otherwise affected.    │
847
848       See below for the pathName peer widget command that controls  the  cre‐ │
849       ation of peer widgets.
850

WIDGET COMMAND

852       The  text  command  creates a new Tcl command whose name is the same as
853       the path name of the text's window.  This command may be used to invoke
854       various operations on the widget.  It has the following general form:
855              pathName option ?arg arg ...?
856       PathName is the name of the command, which is the same as the text wid‐
857       get's path name.  Option and the args determine the exact  behavior  of
858       the command.  The following commands are possible for text widgets:
859
860       pathName bbox index
861              Returns  a  list  of four elements describing the screen area of
862              the character given by index.  The first  two  elements  of  the
863              list  give  the  x and y coordinates of the upper-left corner of
864              the area occupied by the character, and the  last  two  elements
865              give the width and height of the area.  If the character is only
866              partially visible on the screen, then the return value  reflects
867              just  the  visible part.  If the character is not visible on the
868              screen then the return value is an empty list.
869
870       pathName cget option
871              Returns the current value of the configuration option  given  by
872              option.   Option may have any of the values accepted by the text
873              command.
874
875       pathName compare index1 op index2
876              Compares the indices given by index1 and index2 according to the
877              relational  operator given by op, and returns 1 if the relation‐
878              ship is satisfied and 0 if it is not.  Op must  be  one  of  the
879              operators  <,  <=,  ==,  >=,  >,  or  !=.  If op is == then 1 is
880              returned if the two indices refer to the same character,  if  op
881              is < then 1 is returned if index1 refers to an earlier character
882              in the text than index2, and so on.
883
884       pathName configure ?option? ?value option value ...?
885              Query or modify the configuration options of the widget.  If  no
886              option is specified, returns a list describing all of the avail‐
887              able options for pathName (see Tk_ConfigureInfo for  information
888              on  the  format  of  this list).  If option is specified with no
889              value, then the command returns a list describing the one  named
890              option (this list will be identical to the corresponding sublist
891              of the value returned if no option is  specified).   If  one  or
892              more option-value pairs are specified, then the command modifies
893              the given widget option(s) to have the given value(s);  in  this
894              case  the  command returns an empty string.  Option may have any
895              of the values accepted by the text command.                      │
896
897       pathName count ?options? index1 index2
898              Counts the number of relevant things between  the  two  indices. │
899              If  index1 is after index2, the result will be a negative number │
900              (and this holds for each of the possible options).   The  actual │
901              items which are counted depend on the options given.  The result │
902              is a list of integers, one  for  the  result  of  each  counting │
903              option given.  Valid counting options are -chars, -displaychars, │
904              -displayindices, -displaylines, -indices, -lines,  -xpixels  and │
905              -ypixels.  The  default  value,  if  no  option is specified, is │
906              -indices. There is an additional possible option  -update  which │
907              is  a  modifier.   If  given, then all subsequent options ensure │
908              that any possible out of date information is recalculated.  This │
909              currently  only has any effect for the -ypixels count (which, if │
910              -update is not given, will use the text widget's current  cached │
911              value for each line).  The count options are interpreted as fol‐ │
912              lows:                                                            │
913
914              -chars                                                           
915                     count all characters, whether  elided  or  not.   Do  not │
916                     count embedded windows or images.                         │
917
918              -displaychars                                                    
919                     count all non-elided characters.                          │
920
921              -displayindices                                                  
922                     count all non-elided characters, windows and images.      │
923
924              -displaylines                                                    
925                     count  all display lines (i.e. counting one for each time │
926                     a line wraps) from the line of the first index up to, but │
927                     not  including  the  display  line  of  the second index. │
928                     Therefore if they are both on the same display line, zero │
929                     will be returned.  By definition displaylines are visible │
930                     and therefore this only counts portions of actual visible │
931                     lines.                                                    │
932
933              -indices                                                         
934                     count all characters and embedded windows or images (i.e. │
935                     everything which  counts  in  text-widget  index  space), │
936                     whether they are elided or not.                           │
937
938              -lines                                                           
939                     count  all  logical lines (irrespective of wrapping) from │
940                     the line of the first index up to, but not including  the │
941                     line  of the second index.  Therefore if they are both on │
942                     the same line, zero will be returned.  Logical lines  are │
943                     counted  whether  they are currently visible (non-elided) │
944                     or not.                                                   │
945
946              -xpixels                                                         
947                     count the number of  horizontal  pixels  from  the  first │
948                     pixel of the first index to (but not including) the first │
949                     pixel of the second index.  To count  the  total  desired │
950                     width  of  the  text  widget  (assuming  wrapping  is not │
951                     enabled), first find the longest line and then use “.text │
952                     count -xpixels "${line}.0" "${line}.0 lineend"”.          │
953
954              -ypixels                                                         
955                     count  the number of vertical pixels from the first pixel │
956                     of the first index to (but not including) the first pixel │
957                     of  the  second  index.   If both indices are on the same │
958                     display line, zero will be returned.  To count the  total │
959                     number  of vertical pixels in the text widget, use “.text │
960                     count -ypixels 1.0 end”, and to  ensure  this  is  up  to │
961                     date, use “.text count -update -ypixels 1.0 end”.         │
962
963              The command returns a positive or negative integer corresponding │
964              to the number of items counted between  the  two  indices.   One │
965              such  integer  is  returned for each counting option given, so a │
966              list is returned if more than  one  option  was  supplied.   For │
967              example  “.text  count  -xpixels  -ypixels 1.3 4.5” is perfectly │
968              valid and will return a list of two elements.                    │
969
970       pathName debug ?boolean?
971              If boolean is specified, then it must have one of  the  true  or
972              false values accepted by Tcl_GetBoolean.  If the value is a true
973              one then internal consistency checks will be turned on in the B-
974              tree  code associated with text widgets.  If boolean has a false
975              value then the debugging checks will be turned off.   In  either
976              case  the  command  returns  an empty string.  If boolean is not
977              specified then the command returns on or off to indicate whether
978              or  not  debugging  is  turned  on.  There is a single debugging
979              switch shared by all text widgets:  turning debugging on or  off
980              in  any  widget turns it on or off for all widgets.  For widgets
981              with large amounts of text, the consistency checks may  cause  a
982              noticeable slow-down.
983
984              When  debugging  is  turned on, the drawing routines of the text
985              widget set the global variables tk_textRedraw and  tk_textRelay‐
986              out  to  the  lists  of indices that are redrawn.  The values of
987              these variables are tested by Tk's test suite.
988
989       pathName delete index1 ?index2 ...?
990              Delete a range of characters from the text.  If both index1  and
991              index2  are  specified,  then delete all the characters starting
992              with the one given by index1 and  stopping  just  before  index2
993              (i.e.  the  character at index2 is not deleted).  If index2 does
994              not specify a position later in the text  than  index1  then  no
995              characters  are  deleted.   If  index2 is not specified then the
996              single character at index1 is deleted.  It is not  allowable  to
997              delete  characters  in a way that would leave the text without a
998              newline as the last character.  The  command  returns  an  empty
999              string.  If more indices are given, multiple ranges of text will
1000              be deleted.  All indices are first checked for  validity  before
1001              any deletions are made.  They are sorted and the text is removed
1002              from the last range to the first range so deleted text does  not
1003              cause  an  undesired  index  shifting side-effects.  If multiple
1004              ranges with the same start index are  given,  then  the  longest
1005              range  is used.  If overlapping ranges are given, then they will
1006              be merged into spans that do not cause deletion of text  outside
1007              the given ranges due to text shifted during deletion.
1008
1009       pathName dlineinfo index
1010              Returns  a  list with five elements describing the area occupied
1011              by the display line containing index.  The first two elements of
1012              the  list  give the x and y coordinates of the upper-left corner
1013              of the area occupied by the line, the third and fourth  elements
1014              give  the  width  and  height of the area, and the fifth element
1015              gives the position of the baseline for the line,  measured  down
1016              from  the  top of the area.  All of this information is measured
1017              in pixels.  If the current  wrap  mode  is  none  and  the  line
1018              extends  beyond  the boundaries of the window, the area returned
1019              reflects the entire area of the  line,  including  the  portions
1020              that  are  out  of  the window.  If the line is shorter than the
1021              full width of the window then the area  returned  reflects  just
1022              the  portion  of  the  line  that  is occupied by characters and
1023              embedded windows.  If the display line containing index  is  not
1024              visible on the screen then the return value is an empty list.
1025
1026       pathName dump ?switches? index1 ?index2?
1027              Return  the  contents  of the text widget from index1 up to, but
1028              not including index2, including the text and  information  about
1029              marks,  tags, and embedded windows.  If index2 is not specified,
1030              then it defaults to one character past index1.  The  information
1031              is returned in the following format:
1032
1033              key1 value1 index1 key2 value2 index2 ...
1034
1035              The  possible  key  values are text, mark, tagon, tagoff, image,
1036              and window.  The corresponding value is the text, mark name, tag
1037              name,  image name, or window name.  The index information is the
1038              index of the start of the text, mark, tag transition,  image  or
1039              window.  One or more of the following switches (or abbreviations
1040              thereof) may be specified to control the dump:
1041
1042              -all   Return information about all elements: text, marks, tags,
1043                     images and windows.  This is the default.
1044
1045              -command command
1046                     Instead of returning the information as the result of the
1047                     dump operation, invoke the command on each element of the
1048                     text  widget  within  the  range.   The command has three
1049                     arguments appended to it before it is evaluated: the key,
1050                     value, and index.
1051
1052              -image Include information about images in the dump results.
1053
1054              -mark  Include information about marks in the dump results.
1055
1056              -tag   Include  information  about  tag  transitions in the dump
1057                     results. Tag information is returned as tagon and  tagoff
1058                     elements that indicate the begin and end of each range of
1059                     each tag, respectively.
1060
1061              -text  Include information about text in the dump results.   The
1062                     value  is  the  text up to the next element or the end of
1063                     range indicated by index2.  A text element does not  span
1064                     newlines.   A  multi-line  block of text that contains no
1065                     marks or tag transitions will still be dumped as a set of
1066                     text  segments that each end with a newline.  The newline
1067                     is part of the value.
1068
1069              -window
1070                     Include information about embedded windows  in  the  dump
1071                     results.   The  value  of  a  window  is its Tk pathname,
1072                     unless the window has not been  created  yet.   (It  must
1073                     have  a  create script.)  In this case an empty string is
1074                     returned, and you must query  the  window  by  its  index
1075                     position to get more information.
1076
1077       pathName edit option ?arg arg ...?
1078              This  command controls the undo mechanism and the modified flag.
1079              The exact behavior of the command depends on the option argument
1080              that follows the edit argument.  The following forms of the com‐
1081              mand are currently supported:
1082
1083              pathName edit modified ?boolean?
1084                     If boolean is not specified, returns the modified flag of
1085                     the  widget.  The insert, delete, edit undo and edit redo
1086                     commands or the user can set or clear the modified  flag.
1087                     If  boolean  is  specified, sets the modified flag of the
1088                     widget to boolean.
1089
1090              pathName edit redo
1091                     When the -undo option is true, reapplies the last  undone
1092                     edits  provided no other edits were done since then. Gen‐
1093                     erates an error when the redo stack is empty.  Does noth‐
1094                     ing when the -undo option is false.
1095
1096              pathName edit reset
1097                     Clears the undo and redo stacks.
1098
1099              pathName edit separator
1100                     Inserts  a  separator  (boundary) on the undo stack. Does
1101                     nothing when the -undo option is false.
1102
1103              pathName edit undo
1104                     Undoes the last edit action  when  the  -undo  option  is
1105                     true.   An  edit  action is defined as all the insert and
1106                     delete commands that are recorded on the  undo  stack  in
1107                     between  two separators. Generates an error when the undo
1108                     stack is empty.  Does nothing when the  -undo  option  is
1109                     false.
1110
1111       pathName get ?-displaychars? -- index1 ?index2 ...?
1112              Return  a  range  of characters from the text.  The return value
1113              will be all the characters in the text  starting  with  the  one
1114              whose index is index1 and ending just before the one whose index
1115              is index2 (the character at index2 will not  be  returned).   If
1116              index2  is  omitted  then  the  single  character  at  index1 is
1117              returned.  If there are no characters  in  the  specified  range
1118              (e.g.  index1 is past the end of the file or index2 is less than
1119              or equal to index1) then an empty string is  returned.   If  the
1120              specified  range contains embedded windows, no information about
1121              them is included in the  returned  string.   If  multiple  index
1122              pairs  are  given, multiple ranges of text will be returned in a
1123              list.  Invalid ranges will not be represented with empty strings
1124              in  the  list.   The  ranges are returned in the order passed to
1125              pathName get.  If  the  -displaychars  option  is  given,  then, │
1126              within  each  range,  only those characters which are not elided │
1127              will be returned.  This may have the effect  that  some  of  the │
1128              returned ranges are empty strings.
1129
1130       pathName image option ?arg arg ...?
1131              This  command is used to manipulate embedded images.  The behav‐
1132              ior of the command depends on the option argument  that  follows
1133              the  tag  argument.  The following forms of the command are cur‐
1134              rently supported:
1135
1136              pathName image cget index option
1137                     Returns the value of a configuration option for an embed‐
1138                     ded  image.   Index  identifies  the  embedded image, and
1139                     option specifies a particular configuration option, which
1140                     must  be  one  of the ones listed in the section EMBEDDED
1141                     IMAGES.
1142
1143              pathName image configure index ?option value ...?
1144                     Query or modify the configuration options for an embedded
1145                     image.   If  no  option  is  specified,  returns  a  list
1146                     describing all of the available options for the  embedded
1147                     image  at  index (see Tk_ConfigureInfo for information on
1148                     the format of this list).  If option is specified with no
1149                     value, then the command returns a list describing the one
1150                     named option (this list will be identical to  the  corre‐
1151                     sponding  sublist  of  the value returned if no option is
1152                     specified).  If one or more option-value pairs are speci‐
1153                     fied,  then  the  command modifies the given option(s) to
1154                     have the  given  value(s);   in  this  case  the  command
1155                     returns  an empty string.  See EMBEDDED IMAGES for infor‐
1156                     mation on the options that are supported.
1157
1158              pathName image create index ?option value ...?
1159                     This command creates a new image annotation,  which  will
1160                     appear  in  the text at the position given by index.  Any
1161                     number of option-value pairs may be specified to  config‐
1162                     ure the annotation.  Returns a unique identifier that may
1163                     be used as an index to refer to this image.  See EMBEDDED
1164                     IMAGES for information on the options that are supported,
1165                     and a description of the identifier returned.
1166
1167              pathName image names
1168                     Returns a list whose elements are the names of all  image
1169                     instances currently embedded in window.
1170
1171       pathName index index
1172              Returns   the  position  corresponding  to  index  in  the  form
1173              line.char where line is the line number and char is the  charac‐
1174              ter  number.   Index  may  have any of the forms described under
1175              INDICES above.
1176
1177       pathName insert index chars ?tagList chars tagList ...?
1178              Inserts all of the chars arguments just before the character  at
1179              index.   If  index  refers to the end of the text (the character
1180              after the last newline) then  the  new  text  is  inserted  just
1181              before  the  last  newline  instead.  If there is a single chars
1182              argument and no tagList, then the new text will receive any tags
1183              that  are present on both the character before and the character
1184              after the insertion point; if a tag is present on  only  one  of
1185              these  characters  then  it will not be applied to the new text.
1186              If tagList is specified then it consists of a list of tag names;
1187              the new characters will receive all of the tags in this list and
1188              no others, regardless of the tags present around  the  insertion
1189              point.   If  multiple  chars-tagList argument pairs are present,
1190              they produce the same effect as if a  separate  pathName  insert
1191              widget  command  had  been  issued for each pair, in order.  The
1192              last tagList argument may be omitted.
1193
1194       pathName mark option ?arg arg ...?
1195              This command is used to manipulate marks.  The exact behavior of
1196              the command depends on the option argument that follows the mark
1197              argument.  The following forms of the command are currently sup‐
1198              ported:
1199
1200              pathName mark gravity markName ?direction?
1201                     If  direction  is not specified, returns left or right to
1202                     indicate which of its  adjacent  characters  markName  is
1203                     attached  to.  If direction is specified, it must be left
1204                     or right; the gravity of markName is  set  to  the  given
1205                     value.
1206
1207              pathName mark names
1208                     Returns  a  list  whose elements are the names of all the
1209                     marks that are currently set.
1210
1211              pathName mark next index
1212                     Returns the name of the next mark at or after index.   If
1213                     index is specified in numerical form, then the search for
1214                     the next mark begins at that index.  If index is the name
1215                     of a mark, then the search for the next mark begins imme‐
1216                     diately after that mark.  This can still return a mark at
1217                     the same position if there are multiple marks at the same
1218                     index.  These semantics mean that the mark next operation
1219                     can  be used to step through all the marks in a text wid‐
1220                     get in the same order as the mark information returned by
1221                     the  pathName  dump operation.  If a mark has been set to
1222                     the special end index, then it appears to  be  after  end
1223                     with  respect  to  the  pathName mark next operation.  An
1224                     empty string is returned if  there  are  no  marks  after
1225                     index.
1226
1227              pathName mark previous index
1228                     Returns  the  name  of  the  mark at or before index.  If
1229                     index is specified in numerical form, then the search for
1230                     the  previous  mark begins with the character just before
1231                     that index.  If index is the name of  a  mark,  then  the
1232                     search  for  the next mark begins immediately before that
1233                     mark.  This can still return a mark at the same  position
1234                     if  there  are  multiple  marks at the same index.  These
1235                     semantics mean that the pathName mark previous  operation
1236                     can  be used to step through all the marks in a text wid‐
1237                     get in the reverse order as the mark information returned
1238                     by  the  pathName  dump  operation.   An  empty string is
1239                     returned if there are no marks before index.
1240
1241              pathName mark set markName index
1242                     Sets the mark named markName to a  position  just  before
1243                     the  character  at index.  If markName already exists, it
1244                     is moved from its old position; if it does not  exist,  a
1245                     new  mark  is  created.   This  command  returns an empty
1246                     string.
1247
1248              pathName mark unset markName ?markName markName ...?
1249                     Remove the mark corresponding to  each  of  the  markName
1250                     arguments.   The  removed  marks  will  not  be usable in
1251                     indices and will not  be  returned  by  future  calls  to
1252pathName  mark  names”.   This  command returns an empty
1253                     string.
1254
1255       pathName peer option args
1256              This command is used to create and query widget peers.   It  has │
1257              two forms, depending on option:                                  │
1258
1259              pathName peer create newPathName ?options?                       │
1260                     Creates  a  peer  text widget with the given newPathName, │
1261                     and any optional standard configuration options  (as  for │
1262                     the  text  command).   By  default the peer will have the │
1263                     same start and end line as the parent widget,  but  these │
1264                     can   be   overridden  with  the  standard  configuration │
1265                     options.                                                  │
1266
1267              pathName peer names                                              
1268                     Returns a list of peers of this  widget  (this  does  not │
1269                     include  the  widget itself).  The order within this list │
1270                     is undefined.                                             │
1271
1272       pathName replace index1 index2 chars ?tagList chars tagList ...?        │
1273              Replaces the range of characters between index1 and index2  with │
1274              the  given  characters  and  tags.   See the section on pathName
1275              insert for an explanation of  the  handling  of  the  tagList...
1276              arguments, and the section on pathName delete for an explanation │
1277              of the handling of the indices.  If  index2  corresponds  to  an │
1278              index  earlier  in the text than index1, an error will be gener‐ │
1279              ated.                                                            │
1280
1281              The deletion and insertion are arranged so that  no  unnecessary │
1282              scrolling  of the window or movement of insertion cursor occurs. │
1283              In addition the undo/redo stack are correctly modified, if  undo │
1284              operations  are  active in the text widget.  The command returns │
1285              an empty string.                                                 │
1286
1287       pathName scan option args
1288              This command is used to implement scanning on texts.  It has two
1289              forms, depending on option:
1290
1291              pathName scan mark x y
1292                     Records  x and y and the current view in the text window,
1293                     for use in conjunction with later  pathName  scan  dragto
1294                     commands.   Typically  this  command is associated with a
1295                     mouse button press in the widget.  It  returns  an  empty
1296                     string.
1297
1298              pathName scan dragto x y
1299                     This  command computes the difference between its x and y
1300                     arguments and the x and y arguments to the last  pathName
1301                     scan  mark  command  for the widget.  It then adjusts the
1302                     view by 10 times the  difference  in  coordinates.   This
1303                     command  is typically associated with mouse motion events
1304                     in the widget, to produce the effect of dragging the text
1305                     at high speed through the window.  The return value is an
1306                     empty string.
1307
1308       pathName search ?switches? pattern index ?stopIndex?
1309              Searches the text in pathName starting at index for a  range  of
1310              characters that matches pattern.  If a match is found, the index
1311              of the first character in the match is returned as result;  oth‐
1312              erwise  an empty string is returned.  One or more of the follow‐
1313              ing switches (or abbreviations thereof) may be specified to con‐
1314              trol the search:
1315
1316              -forwards
1317                     The search will proceed forward through the text, finding
1318                     the first matching range starting at or after  the  posi‐
1319                     tion given by index.  This is the default.
1320
1321              -backwards
1322                     The  search will proceed backward through the text, find‐
1323                     ing the matching range closest to index whose first char‐
1324                     acter is before index (it is not allowed to be at index). │
1325                     Note that, for a variety of reasons,  backwards  searches │
1326                     can  be substantially slower than forwards searches (par‐ │
1327                     ticularly when using -regexp), so it is recommended  that │
1328                     performance-critical code use forward searches.
1329
1330              -exact Use exact matching:  the characters in the matching range
1331                     must be identical to  those  in  pattern.   This  is  the
1332                     default.
1333
1334              -regexp
1335                     Treat  pattern  as  a  regular  expression  and  match it
1336                     against the text using the rules for regular  expressions
1337                     (see the regexp command for details).  The default match‐ │
1338                     ing  automatically  passes  both  the   -lineanchor   and │
1339                     -linestop   options   to   the   regexp   engine  (unless │
1340                     -nolinestop is used), so that ^$ match beginning and  end │
1341                     of line, and ., [^ sequences will never match the newline │
1342                     character \n.
1343
1344              -nolinestop
1345                     This allows . and [^ sequences to match the newline char‐ │
1346                     acter  \n, which they will otherwise not do (see the reg‐ 
1347                     exp command for details). This option is only  meaningful │
1348                     if  -regexp  is  also  given, and an error will be thrown │
1349                     otherwise.  For example, to match the  entire  text,  use │
1350pathName search -nolinestop -regexp ".*" 1.0”.
1351
1352              -nocase
1353                     Ignore case differences between the pattern and the text.
1354
1355              -count varName
1356                     The  argument  following -count gives the name of a vari‐
1357                     able; if a match is found, the number of index  positions
1358                     between  beginning  and end of the matching range will be
1359                     stored in the variable.  If there are no embedded  images
1360                     or windows in the matching range (and there are no elided
1361                     characters if -elide is not given), this is equivalent to
1362                     the  number  of  characters matched.  In either case, the
1363                     range matchIdx to matchIdx + $count chars will return the
1364                     entire matched text.
1365
1366              -all   Find  all matches in the given range and return a list of │
1367                     the indices of the first character of each match.   If  a │
1368                     -count  varName switch is given, then varName is also set │
1369                     to a list containing  one  element  for  each  successful │
1370                     match.   Note that, even for exact searches, the elements │
1371                     of this list may be  different,  if  there  are  embedded │
1372                     images,  windows  or  hidden  text.   Searches  with -all 
1373                     behave very similarly to the Tcl command regexp -all,  in │
1374                     that  overlapping matches are not normally returned.  For │
1375                     example, applying an -all search  of  the  pattern  “\w+” │
1376                     against  “hello  there”  will  just match twice, once for │
1377                     each word, and matching  “Z[a-z]+Z”  against  “ZooZooZoo” │
1378                     will just match once.
1379
1380              -overlap
1381                     When  performing  -all  searches, the normal behaviour is │
1382                     that matches which overlap an  already-found  match  will │
1383                     not  be  returned.  This switch changes that behaviour so │
1384                     that all matches which are not  totally  enclosed  within │
1385                     another  match  are  returned.   For example, applying an │
1386                     -overlap search  of  the  pattern  “\w+”  against  “hello │
1387                     there”  will  just match twice (i.e. no different to just │
1388                     -all), but matching “Z[a-z]+Z” against  “ZooZooZoo”  will │
1389                     now  match twice.  An error will be thrown if this switch │
1390                     is used without -all.
1391
1392              -strictlimits
1393                     When performing any search, the normal behaviour is  that │
1394                     the start and stop limits are checked with respect to the │
1395                     start of the matching text.  With the -strictlimits flag, │
1396                     the  entire  matching range must lie inside the start and │
1397                     stop limits specified for the match to be valid.
1398
1399              -elide Find elided (hidden) text as well. By default  only  dis‐
1400                     played text is searched.
1401
1402              --     This switch has no effect except to terminate the list of
1403                     switches: the next argument will be  treated  as  pattern
1404                     even if it starts with -.
1405
1406              The  matching  range may be within a single line of text, or run │
1407              across multiple lines (if parts of the pattern can match a  new- │
1408              line).   For regular expression matching one can use the various │
1409              newline-matching features such as $ to match the end of a  line, │
1410              ^  to match the beginning of a line, and to control whether . is │
1411              allowed to match a new-line.  If  stopIndex  is  specified,  the
1412              search stops at that index: for forward searches, no match at or
1413              after stopIndex will be considered;  for backward  searches,  no
1414              match earlier in the text than stopIndex will be considered.  If
1415              stopIndex is omitted, the entire text will be searched: when the
1416              beginning or end of the text is reached, the search continues at
1417              the other end until the starting location is reached again;   if
1418              stopIndex  is  specified, no wrap-around will occur.  This means
1419              that, for example, if the search is -forwards but  stopIndex  is
1420              earlier in the text than startIndex, nothing will ever be found.
1421              See KNOWN BUGS below for a number of minor  limitations  of  the
1422              pathName search command.
1423
1424       pathName see index
1425              Adjusts  the  view  in the window so that the character given by
1426              index is completely visible.  If index is already  visible  then
1427              the  command  does nothing.  If index is a short distance out of
1428              view, the command adjusts the view just  enough  to  make  index
1429              visible at the edge of the window.  If index is far out of view,
1430              then the command centers index in the window.
1431
1432       pathName tag option ?arg arg ...?
1433              This command is used to manipulate tags.  The exact behavior  of
1434              the  command depends on the option argument that follows the tag
1435              argument.  The following forms of the command are currently sup‐
1436              ported:
1437
1438              pathName tag add tagName index1 ?index2 index1 index2 ...?
1439                     Associate  the  tag  tagName  with  all of the characters
1440                     starting with index1 and ending just before  index2  (the
1441                     character at index2 is not tagged).  A single command may
1442                     contain any number of index1-index2 pairs.  If  the  last
1443                     index2  is omitted then the single character at index1 is
1444                     tagged.  If there are  no  characters  in  the  specified
1445                     range  (e.g. index1 is past the end of the file or index2
1446                     is less than or equal to index1) then the command has  no
1447                     effect.
1448
1449              pathName tag bind tagName ?sequence? ?script?
1450                     This command associates script with the tag given by tag‐
1451                     Name.  Whenever the  event  sequence  given  by  sequence
1452                     occurs for a character that has been tagged with tagName,
1453                     the script will be invoked.  This widget command is simi‐
1454                     lar  to the bind command except that it operates on char‐
1455                     acters in a text rather than  entire  widgets.   See  the
1456                     bind  manual  entry for complete details on the syntax of
1457                     sequence and the substitutions performed on script before
1458                     invoking  it.   If all arguments are specified then a new
1459                     binding is created, replacing any  existing  binding  for
1460                     the  same sequence and tagName (if the first character of
1461                     script is “+” then script augments  an  existing  binding
1462                     rather than replacing it).  In this case the return value
1463                     is an empty string.  If script is omitted then  the  com‐
1464                     mand  returns  the  script  associated  with  tagName and
1465                     sequence (an error occurs if there is no  such  binding).
1466                     If  both script and sequence are omitted then the command
1467                     returns a list of all the sequences  for  which  bindings
1468                     have been defined for tagName.
1469
1470                     The  only  events for which bindings may be specified are
1471                     those related to the mouse and keyboard (such  as  Enter,
1472                     Leave,  ButtonPress,  Motion,  and  KeyPress)  or virtual
1473                     events.  Event bindings for a text widget use the current
1474                     mark  described  under MARKS above.  An Enter event trig‐
1475                     gers for a tag when the tag first becomes present on  the
1476                     current  character,  and a Leave event triggers for a tag
1477                     when it ceases to be present on  the  current  character.
1478                     Enter and Leave events can happen either because the cur‐
1479                     rent mark moved or because the character at that position
1480                     changed.  Note that these events are different than Enter
1481                     and Leave events for windows.  Mouse and keyboard  events
1482                     are  directed  to  the  current  character.  If a virtual
1483                     event is used in a binding, that binding can trigger only
1484                     if  the  virtual event is defined by an underlying mouse-
1485                     related or keyboard-related event.
1486
1487                     It is possible for the current character to have multiple
1488                     tags,  and  for each of them to have a binding for a par‐
1489                     ticular event sequence.  When this occurs, one binding is
1490                     invoked  for  each  tag, in order from lowest-priority to
1491                     highest priority.  If there are multiple  matching  bind‐
1492                     ings  for a single tag, then the most specific binding is
1493                     chosen (see the manual entry for  the  bind  command  for
1494                     details).   continue  and  break  commands within binding
1495                     scripts are processed in the same  way  as  for  bindings
1496                     created with the bind command.
1497
1498                     If  bindings  are created for the widget as a whole using
1499                     the bind command, then those bindings will supplement the
1500                     tag  bindings.   The  tag bindings will be invoked first,
1501                     followed by bindings for the window as a whole.
1502
1503              pathName tag cget tagName option
1504                     This command returns the  current  value  of  the  option
1505                     named  option  associated  with the tag given by tagName.
1506                     Option may have any of the values accepted by  the  path‐
1507                     Name tag configure widget command.
1508
1509              pathName  tag  configure  tagName ?option? ?value? ?option value
1510              ...?
1511                     This command is similar to the pathName configure  widget
1512                     command  except  that it modifies options associated with
1513                     the tag given by tagName instead of modifying options for
1514                     the  overall text widget.  If no option is specified, the
1515                     command returns a list describing all  of  the  available
1516                     options for tagName (see Tk_ConfigureInfo for information
1517                     on the format of this list).  If option is specified with
1518                     no  value, then the command returns a list describing the
1519                     one named option (this list will be identical to the cor‐
1520                     responding  sublist of the value returned if no option is
1521                     specified).  If one or more option-value pairs are speci‐
1522                     fied,  then  the  command modifies the given option(s) to
1523                     have the given value(s) in tagName; in this case the com‐
1524                     mand returns an empty string.  See TAGS above for details
1525                     on the options available for tags.
1526
1527              pathName tag delete tagName ?tagName ...?
1528                     Deletes all tag information for each of the tagName argu‐
1529                     ments.   The command removes the tags from all characters
1530                     in the file and also deletes any other information  asso‐
1531                     ciated with the tags, such as bindings and display infor‐
1532                     mation.  The command returns an empty string.
1533
1534              pathName tag lower tagName ?belowThis?
1535                     Changes the priority of tag tagName so that  it  is  just
1536                     lower  in  priority than the tag whose name is belowThis.
1537                     If belowThis  is  omitted,  then  tagName's  priority  is
1538                     changed to make it lowest priority of all tags.
1539
1540              pathName tag names ?index?
1541                     Returns  a  list  whose elements are the names of all the
1542                     tags that are active at the character position  given  by
1543                     index.   If  index is omitted, then the return value will
1544                     describe all of the tags that exist for  the  text  (this
1545                     includes  all  tags  that  have been named in a “pathName
1546                     tag” widget command but have not been deleted by a “path‐
1547                     Name  tag  delete”  widget command, even if no characters
1548                     are currently marked with the tag).   The  list  will  be
1549                     sorted in order from lowest priority to highest priority.
1550
1551              pathName tag nextrange tagName index1 ?index2?
1552                     This  command searches the text for a range of characters
1553                     tagged with tagName where  the  first  character  of  the
1554                     range  is  no earlier than the character at index1 and no
1555                     later than the character  just  before  index2  (a  range
1556                     starting  at  index2 will not be considered).  If several
1557                     matching ranges exist, the first one is chosen.  The com‐
1558                     mand's  return  value  is a list containing two elements,
1559                     which are the index of the first character of  the  range
1560                     and the index of the character just after the last one in
1561                     the range.  If no matching range is found then the return
1562                     value is an empty string.  If index2 is not given then it
1563                     defaults to the end of the text.
1564
1565              pathName tag prevrange tagName index1 ?index2?
1566                     This command searches the text for a range of  characters
1567                     tagged  with  tagName  where  the  first character of the
1568                     range is before the character at index1  and  no  earlier
1569                     than  the character at index2 (a range starting at index2
1570                     will be considered).  If several matching  ranges  exist,
1571                     the  one  closest  to  index1  is  chosen.  The command's
1572                     return value is a list containing two elements, which are
1573                     the  index  of  the  first character of the range and the
1574                     index of the character just after the  last  one  in  the
1575                     range.   If  no  matching  range is found then the return
1576                     value is an empty string.  If index2 is not given then it
1577                     defaults to the beginning of the text.
1578
1579              pathName tag raise tagName ?aboveThis?
1580                     Changes  the  priority  of tag tagName so that it is just
1581                     higher in priority than the tag whose name is  aboveThis.
1582                     If  aboveThis  is  omitted,  then  tagName's  priority is
1583                     changed to make it highest priority of all tags.
1584
1585              pathName tag ranges tagName
1586                     Returns a list describing all of the ranges of text  that
1587                     have been tagged with tagName.  The first two elements of
1588                     the list describe the first tagged range in the text, the
1589                     next  two  elements describe the second range, and so on.
1590                     The first element of each pair contains the index of  the
1591                     first  character  of the range, and the second element of
1592                     the pair contains the index of the character  just  after
1593                     the  last  one  in the range.  If there are no characters
1594                     tagged with tag then an empty string is returned.
1595
1596              pathName tag remove tagName index1 ?index2 index1 index2 ...?
1597                     Remove the tag tagName from all of the characters  start‐
1598                     ing  at index1 and ending just before index2 (the charac‐
1599                     ter at index2 is not affected).   A  single  command  may
1600                     contain  any  number of index1-index2 pairs.  If the last
1601                     index2 is omitted then the tag is removed from the single
1602                     character  at  index1.  If there are no characters in the
1603                     specified range (e.g. index1 is past the end of the  file
1604                     or  index2 is less than or equal to index1) then the com‐
1605                     mand has  no  effect.   This  command  returns  an  empty
1606                     string.
1607
1608       pathName window option ?arg arg ...?
1609              This command is used to manipulate embedded windows.  The behav‐
1610              ior of the command depends on the option argument  that  follows
1611              the  tag  argument.  The following forms of the command are cur‐
1612              rently supported:
1613
1614              pathName window cget index option
1615                     Returns the value of a configuration option for an embed‐
1616                     ded  window.   Index  identifies the embedded window, and
1617                     option specifies a particular configuration option, which
1618                     must  be  one  of the ones listed in the section EMBEDDED
1619                     WINDOWS.
1620
1621              pathName window configure index ?option value ...?
1622                     Query or modify the configuration options for an embedded
1623                     window.   If  no  option  is  specified,  returns  a list
1624                     describing all of the available options for the  embedded
1625                     window  at index (see Tk_ConfigureInfo for information on
1626                     the format of this list).  If option is specified with no
1627                     value, then the command returns a list describing the one
1628                     named option (this list will be identical to  the  corre‐
1629                     sponding  sublist  of  the value returned if no option is
1630                     specified).  If one or more option-value pairs are speci‐
1631                     fied,  then  the  command modifies the given option(s) to
1632                     have the  given  value(s);   in  this  case  the  command
1633                     returns an empty string.  See EMBEDDED WINDOWS for infor‐
1634                     mation on the options that are supported.
1635
1636              pathName window create index ?option value ...?
1637                     This command creates a new window annotation, which  will
1638                     appear  in  the text at the position given by index.  Any
1639                     number of option-value pairs may be specified to  config‐
1640                     ure the annotation.  See EMBEDDED WINDOWS for information
1641                     on the options that  are  supported.   Returns  an  empty
1642                     string.
1643
1644              pathName window names
1645                     Returns  a  list whose elements are the names of all win‐
1646                     dows currently embedded in window.
1647
1648       pathName xview option args
1649              This command is used to query and change the horizontal position
1650              of the text in the widget's window.  It can take any of the fol‐
1651              lowing forms:
1652
1653              pathName xview
1654                     Returns a list containing two elements.  Each element  is
1655                     a  real fraction between 0 and 1;  together they describe
1656                     the portion of the document's  horizontal  span  that  is
1657                     visible in the window.  For example, if the first element
1658                     is .2 and the second element is .6, 20% of  the  text  is
1659                     off-screen  to the left, the middle 40% is visible in the
1660                     window, and 40% of the text is off-screen to  the  right.
1661                     The  fractions  refer only to the lines that are actually
1662                     visible in the window:  if the lines in  the  window  are
1663                     all  very  short,  so that they are entirely visible, the
1664                     returned fractions will be 0 and 1,  even  if  there  are
1665                     other lines in the text that are much wider than the win‐
1666                     dow.  These are the same values passed to scrollbars  via
1667                     the -xscrollcommand option.
1668
1669              pathName xview moveto fraction
1670                     Adjusts  the  view  in the window so that fraction of the
1671                     horizontal span of the text is off-screen  to  the  left.
1672                     Fraction is a fraction between 0 and 1.
1673
1674              pathName xview scroll number what
1675                     This  command shifts the view in the window left or right
1676                     according to number and what.  What must be units,  pages
1677                     or pixels.  If what is units or pages then number must be │
1678                     an integer, otherwise number may be specified in  any  of │
1679                     the  forms  acceptable to Tk_GetPixels, such as “2.0c” or │
1680                     “1i” (the result is rounded to the nearest integer value. │
1681                     If  no  units are given, pixels are assumed).  If what is │
1682                     units, the view adjusts left or right by number  average- │
1683                     width  characters on the display; if it is pages then the │
1684                     view adjusts by number screenfuls; if it is  pixels  then │
1685                     the view adjusts by number pixels.  If number is negative
1686                     then characters farther to the left become visible; if it
1687                     is  positive  then characters farther to the right become
1688                     visible.
1689
1690       pathName yview ?args?
1691              This command is used to query and change the  vertical  position
1692              of the text in the widget's window.  It can take any of the fol‐
1693              lowing forms:
1694
1695              pathName yview
1696                     Returns a list containing two elements, both of which are
1697                     real  fractions between 0 and 1.  The first element gives
1698                     the position of the first  visible  pixel  of  the  first
1699                     character  (or image, etc) in the top line in the window,
1700                     relative to the text as a whole (0.5 means it is  halfway
1701                     through the text, for example).  The second element gives
1702                     the position of the first pixel just after the last visi‐
1703                     ble one in the bottom line of the window, relative to the
1704                     text as a whole.  These are the  same  values  passed  to
1705                     scrollbars via the -yscrollcommand option.
1706
1707              pathName yview moveto fraction
1708                     Adjusts the view in the window so that the pixel given by
1709                     fraction appears at the top of the top line of  the  win‐
1710                     dow.   Fraction  is  a fraction between 0 and 1;  0 indi‐
1711                     cates the first pixel of the first character in the text,
1712                     0.33  indicates  the  pixel  that  is  one-third  the way
1713                     through the text; and so on.   Values  close  to  1  will │
1714                     indicate  values  close  to the last pixel in the text (1 │
1715                     actually refers to one pixel beyond the last pixel),  but │
1716                     in  such  cases  the  widget will never scroll beyond the │
1717                     last pixel, and so a  value  of  1  will  effectively  be │
1718                     rounded  back to whatever fraction ensures the last pixel │
1719                     is at the bottom of the window, and some other  pixel  is │
1720                     at the top.
1721
1722              pathName yview scroll number what
1723                     This  command  adjust  the  view in the window up or down
1724                     according to number and what.  What must be units,  pages
1725                     or pixels.  If what is units or pages then number must be │
1726                     an integer, otherwise number may be specified in  any  of │
1727                     the  forms  acceptable to Tk_GetPixels, such as “2.0c” or │
1728                     “1i” (the result is rounded to the nearest integer value. │
1729                     If  no  units are given, pixels are assumed).  If what is │
1730                     units, the view adjusts up or down by number lines on the │
1731                     display;  if  it is pages then the view adjusts by number
1732                     screenfuls; if it is pixels then the view adjusts by num‐
1733                     ber pixels.  If number is negative then earlier positions
1734                     in the text become visible;  if it is positive then later
1735                     positions in the text become visible.
1736
1737              pathName yview ?-pickplace? index
1738                     Changes  the  view  in  the widget's window to make index
1739                     visible.  If the -pickplace option is not specified  then
1740                     index  will  appear  at the top of the window.  If -pick‐
1741                     place is specified then the widget  chooses  where  index
1742                     appears in the window:
1743
1744                     [1]    If  index is already visible somewhere in the win‐
1745                            dow then the command does nothing.
1746
1747                     [2]    If index is only a few lines off-screen above  the
1748                            window  then  it  will be positioned at the top of
1749                            the window.
1750
1751                     [3]    If index is only a few lines off-screen below  the
1752                            window then it will be positioned at the bottom of
1753                            the window.
1754
1755                     [4]    Otherwise, index will be centered in the window.
1756
1757                     The -pickplace option has been obsoleted by the  pathName
1758                     see  widget  command (pathName see handles both x- and y-
1759                     motion to make a location visible, whereas the -pickplace
1760                     mode only handles motion in y).
1761
1762              pathName yview number
1763                     This  command makes the first character on the line after
1764                     the one given by number visible at the top of the window.
1765                     Number  must be an integer.  This command used to be used
1766                     for scrolling, but now it is obsolete.
1767

BINDINGS

1769       Tk automatically creates class bindings for texts that  give  them  the
1770       following  default  behavior.   In  the  descriptions  below, “word” is
1771       dependent on the value of the tcl_wordchars variable.  See tclvars(n).
1772
1773       [1]    Clicking mouse button 1  positions  the  insertion  cursor  just
1774              before the character underneath the mouse cursor, sets the input
1775              focus to this widget, and clears any selection  in  the  widget.
1776              Dragging with mouse button 1 strokes out a selection between the
1777              insertion cursor and the character under the mouse.
1778
1779       [2]    Double-clicking with mouse button 1 selects the word  under  the
1780              mouse  and  positions  the  insertion cursor at the start of the
1781              word.  Dragging after a double click will stroke out a selection
1782              consisting of whole words.
1783
1784       [3]    Triple-clicking  with  mouse button 1 selects the line under the
1785              mouse and positions the insertion cursor at  the  start  of  the
1786              line.  Dragging after a triple click will stroke out a selection
1787              consisting of whole lines.
1788
1789       [4]    The ends of the selection can be adjusted by dragging with mouse
1790              button  1 while the Shift key is down;  this will adjust the end
1791              of the selection that was nearest to the mouse cursor when  but‐
1792              ton 1 was pressed.  If the button is double-clicked before drag‐
1793              ging then the selection will  be  adjusted  in  units  of  whole
1794              words;   if  it  is  triple-clicked  then  the selection will be
1795              adjusted in units of whole lines.
1796
1797       [5]    Clicking mouse button 1 with the Control key down  will  reposi‐
1798              tion the insertion cursor without affecting the selection.
1799
1800       [6]    If  any  normal printing characters are typed, they are inserted
1801              at the point of the insertion cursor.
1802
1803       [7]    The view in the widget can be adjusted by  dragging  with  mouse
1804              button  2.   If  mouse  button  2  is clicked without moving the
1805              mouse, the selection is copied into the text at the position  of
1806              the  mouse  cursor.   The Insert key also inserts the selection,
1807              but at the position of the insertion cursor.
1808
1809       [8]    If the mouse is dragged out of the  widget  while  button  1  is
1810              pressed,  the  entry will automatically scroll to make more text
1811              visible (if there is more text off-screen on the side where  the
1812              mouse left the window).
1813
1814       [9]    The  Left and Right keys move the insertion cursor one character
1815              to the left or right;  they also  clear  any  selection  in  the
1816              text.   If  Left or Right is typed with the Shift key down, then
1817              the insertion cursor moves and  the  selection  is  extended  to
1818              include  the new character.  Control-Left and Control-Right move
1819              the insertion cursor by words, and Control-Shift-Left  and  Con‐
1820              trol-Shift-Right  move  the  insertion  cursor by words and also
1821              extend the selection.  Control-b and Control-f behave  the  same
1822              as  Left  and Right, respectively.  Meta-b and Meta-f behave the
1823              same as Control-Left and Control-Right, respectively.
1824
1825       [10]   The Up and Down keys move the insertion cursor one  line  up  or
1826              down  and  clear  any  selection in the text.  If Up or Right is
1827              typed with the Shift key down, then the insertion  cursor  moves
1828              and  the  selection  is  extended  to include the new character.
1829              Control-Up and Control-Down move the insertion cursor  by  para‐
1830              graphs  (groups of lines separated by blank lines), and Control-
1831              Shift-Up and Control-Shift-Down move  the  insertion  cursor  by
1832              paragraphs  and  also  extend the selection.  Control-p and Con‐
1833              trol-n behave the same as Up and Down, respectively.
1834
1835       [11]   The Next and Prior keys move the  insertion  cursor  forward  or
1836              backwards  by one screenful and clear any selection in the text.
1837              If the Shift key is held down while Next or Prior is typed, then
1838              the selection is extended to include the new character.
1839
1840       [12]   Control-Next  and Control-Prior scroll the view right or left by
1841              one page without moving the insertion cursor  or  affecting  the
1842              selection.
1843
1844       [13]   Home and Control-a move the insertion cursor to the beginning of
1845              its display line and clear any selection in the widget.   Shift-
1846              Home  moves the insertion cursor to the beginning of the display
1847              line and also extends the selection to that point.
1848
1849       [14]   End and Control-e move the insertion cursor to the  end  of  the
1850              display  line  and clear any selection in the widget.  Shift-End
1851              moves the cursor to the end of the display line and extends  the
1852              selection to that point.
1853
1854       [15]   Control-Home  and Meta-< move the insertion cursor to the begin‐
1855              ning of the text and clear any selection in  the  widget.   Con‐
1856              trol-Shift-Home  moves  the insertion cursor to the beginning of
1857              the text and also extends the selection to that point.
1858
1859       [16]   Control-End and Meta-> move the insertion cursor to the  end  of
1860              the  text and clear any selection in the widget.  Control-Shift-
1861              End moves the cursor to the end of  the  text  and  extends  the
1862              selection to that point.
1863
1864       [17]   The Select key and Control-Space set the selection anchor to the
1865              position of the insertion cursor.  They do not affect  the  cur‐
1866              rent selection.  Shift-Select and Control-Shift-Space adjust the
1867              selection to the  current  position  of  the  insertion  cursor,
1868              selecting  from  the anchor to the insertion cursor if there was
1869              not any selection previously.
1870
1871       [18]   Control-/ selects the entire contents of the widget.
1872
1873       [19]   Control-\ clears any selection in the widget.
1874
1875       [20]   The F16 key (labelled Copy on many Sun workstations)  or  Meta-w
1876              copies the selection in the widget to the clipboard, if there is
1877              a  selection.   This  action  is  carried  out  by  the  command
1878              tk_textCopy.
1879
1880       [21]   The F20 key (labelled Cut on many Sun workstations) or Control-w
1881              copies the selection in the widget to the clipboard and  deletes
1882              the  selection.   This  action  is  carried  out  by the command
1883              tk_textCut.  If there is no selection in the widget  then  these
1884              keys have no effect.
1885
1886       [22]   The  F18  key  (labelled Paste on many Sun workstations) or Con‐
1887              trol-y inserts the contents of the clipboard at the position  of
1888              the insertion cursor.  This action is carried out by the command
1889              tk_textPaste.
1890
1891       [23]   The Delete key deletes the selection, if there  is  one  in  the
1892              widget.   If  there is no selection, it deletes the character to
1893              the right of the insertion cursor.
1894
1895       [24]   Backspace and Control-h delete the selection, if there is one in
1896              the widget.  If there is no selection, they delete the character
1897              to the left of the insertion cursor.
1898
1899       [25]   Control-d deletes the character to the right  of  the  insertion
1900              cursor.
1901
1902       [26]   Meta-d deletes the word to the right of the insertion cursor.
1903
1904       [27]   Control-k  deletes  from  the insertion cursor to the end of its
1905              line; if the insertion cursor is already at the end of  a  line,
1906              then Control-k deletes the newline character.
1907
1908       [28]   Control-o  opens  a new line by inserting a newline character in
1909              front of the insertion cursor without moving the insertion  cur‐
1910              sor.
1911
1912       [29]   Meta-backspace  and  Meta-Delete  delete the word to the left of
1913              the insertion cursor.
1914
1915       [30]   Control-x deletes whatever is selected in the text widget  after
1916              copying it to the clipboard.
1917
1918       [31]   Control-t  reverses the order of the two characters to the right
1919              of the insertion cursor.
1920
1921       [32]   Control-z (and Control-underscore on UNIX when tk_strictMotif is
1922              true)  undoes  the last edit action if the -undo option is true.
1923              Does nothing otherwise.
1924
1925       [33]   Control-Z (or Control-y on Windows) reapplies  the  last  undone
1926              edit action if the -undo option is true. Does nothing otherwise.
1927
1928       If  the  widget  is disabled using the -state option, then its view can
1929       still be adjusted and text can still be selected, but no insertion cur‐
1930       sor will be displayed and no text modifications will take place.
1931
1932       The behavior of texts can be changed by defining new bindings for indi‐
1933       vidual widgets or by redefining the class bindings.
1934

KNOWN ISSUES

1936   ISSUES CONCERNING CHARS AND INDICES
1937       Before Tk 8.5, the widget used the string “chars”  to  refer  to  index │
1938       positions  (which  included  characters,  embedded windows and embedded │
1939       images).  As of Tk 8.5 the text widget deals separately  and  correctly │
1940       with  “chars” and “indices”.  For backwards compatibility, however, the │
1941       index modifiers “+N chars” and “-N chars” continue to refer to indices. │
1942       One  must  use  any  of the full forms “+N any chars” or “-N any chars” │
1943       etc. to refer to actual character indices.  This confusion may be fixed │
1944       in a future release by making the widget correctly interpret “+N chars” │
1945       as a synonym for “+N any chars”.
1946
1947   PERFORMANCE ISSUES
1948       Text widgets should run efficiently under a variety of conditions.  The
1949       text  widget uses about 2-3 bytes of main memory for each byte of text,
1950       so texts containing a megabyte or more  should  be  practical  on  most
1951       workstations.   Text  is  represented internally with a modified B-tree
1952       structure that makes operations relatively efficient  even  with  large
1953       texts.   Tags are included in the B-tree structure in a way that allows
1954       tags to span large ranges or have many disjoint smaller ranges  without
1955       loss  of  efficiency.   Marks are also implemented in a way that allows
1956       large numbers of marks.  In most cases it is fine to have large numbers
1957       of unique tags, or a tag that has many distinct ranges.
1958
1959       One  performance problem can arise if you have hundreds or thousands of
1960       different tags that all have the following characteristics:  the  first
1961       and last ranges of each tag are near the beginning and end of the text,
1962       respectively, or a single tag range covers most  of  the  text  widget.
1963       The  cost  of adding and deleting tags like this is proportional to the
1964       number of other tags with the same properties.  In contrast,  there  is
1965       no  problem  with  having  thousands  of distinct tags if their overall
1966       ranges are localized and spread uniformly throughout the text.
1967
1968       Very long text lines can be expensive, especially  if  they  have  many
1969       marks and tags within them.
1970
1971       The display line with the insert cursor is redrawn each time the cursor
1972       blinks, which causes a steady stream  of  graphics  traffic.   Set  the
1973       insertOffTime attribute to 0 avoid this.
1974
1975   KNOWN BUGS
1976       The  pathName  search -regexp sub-command attempts to perform sophisti‐ │
1977       cated regexp matching across multiple lines  in  an  efficient  fashion │
1978       (since  Tk  8.5),  examining  each line individually, and then in small │
1979       groups of lines, whether searching forwards or backwards.   Under  cer‐ │
1980       tain  conditions  the  search result might differ from that obtained by │
1981       applying the same regexp to the entire text from the widget in one  go. │
1982       For  example, when searching with a greedy regexp, the widget will con‐ │
1983       tinue to attempt to add extra lines to the match as long as one of  two │
1984       conditions  are  true:  either  Tcl's  regexp library returns a code to │
1985       indicate a longer match is possible (but there are known  bugs  in  Tcl │
1986       which  mean  this  code  is  not always correctly returned); or if each │
1987       extra line added results in at least a partial match with the  pattern. │
1988       This  means  in the case where the first extra line added results in no │
1989       match and Tcl's regexp system returns the incorrect code and  adding  a │
1990       second extra line would actually match, the text widget will return the │
1991       wrong result.  In practice this is a rare problem, but  it  can  occur, │
1992       for example:                                                            │
1993              pack [text .t]                                                   │
1994              .t insert 1.0 "aaaa\nbbbb\ncccc\nbbbb\naaaa\n"                   │
1995              .t search -regexp -- {(a+|b+\nc+\nb+)+\na+} 1.0                  │
1996       will  not  find  a match when one exists of 19 characters starting from │
1997       the first “b”.                                                          │
1998
1999       Whenever one possible match is fully enclosed in  another,  the  search │
2000       command will attempt to ensure only the larger match is returned.  When │
2001       performing backwards regexp searches it is possible that Tcl  will  not │
2002       always  achieve  this,  in the case where a match is preceded by one or │
2003       more short, non-overlapping matches, all of which  are  preceded  by  a │
2004       large  match  which actually encompasses all of them.  The search algo‐ │
2005       rithm used by the widget does not look back arbitrarily far for a  pos‐ │
2006       sible  match which might cover large portions of the widget.  For exam‐ │
2007       ple:                                                                    │
2008              pack [text .t]                                                   │
2009              .t insert 1.0 "aaaa\nbbbb\nbbbb\nbbbb\nbbbb\n"                   │
2010              .t search -regexp -backward -- {b+\n|a+\n(b+\n)+} end            │
2011       matches at “5.0” when a true greedy match would match at “1.0”.   Simi‐ │
2012       larly  if  we add -all to this case, it matches at all of “5.0”, “4.0”, │
2013       “3.0” and “1.0”, when really it should only match at “1.0”  since  that │
2014       match encloses all the others.
2015

SEE ALSO

2017       entry(n), scrollbar(n)
2018

KEYWORDS

2020       text, widget, tkvars
2021
2022
2023
2024Tk                                    8.5                              text(n)
Impressum