1text(n) Tk Built-In Commands text(n)
2______________________________________________________________________________
6
8 text, tk_textCopy, tk_textCut, tk_textPaste - Create and manipulate
9 'text' hypertext editing widgets
10
12 text pathName ?options?
13 tk_textCopy pathName
14 tk_textCut pathName
15 tk_textPaste pathName
16
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 See the options manual entry for details on the standard options.
28
30 Command-Line Name:-autoseparators
31 Database Name: autoSeparators
32 Database Class: AutoSeparators
33 Specifies a boolean that says whether separators are automati‐
35 cally inserted in the undo stack. Only meaningful when the -undo
36 option is true.
37 Command-Line Name:-blockcursor
39 Database Name: blockCursor
40 Database Class: BlockCursor
41 Specifies a boolean that says whether the blinking insertion
43 cursor should be drawn as a character-sized rectangular block.
44 If false (the default) a thin vertical line is used for the
45 insertion cursor.
46 Command-Line Name:-endline
48 Database Name: endLine
49 Database Class: EndLine
50 Specifies an integer line index representing the line of the
52 underlying textual data store that should be just after the last
53 line contained in the widget. This allows a text widget to
54 reflect only a portion of a larger piece of text. Instead of an
55 integer, the empty string can be provided to this configuration
56 option, which will configure the widget to end at the very last
57 line in the textual data store.
58 Command-Line Name:-height
60 Database Name: height
61 Database Class: Height
62 Specifies the desired height for the window, in units of charac‐
64 ters in the font given by the -font option. Must be at least
65 one.
66 Command-Line Name:-inactiveselectbackground
68 Database Name: inactiveSelectBackground
69 Database Class: Foreground
70 Specifies the colour to use for the selection (the sel tag) when
72 the window does not have the input focus. If empty, {}, then no
73 selection is shown when the window does not have the focus.
74 Command-Line Name:-insertunfocussed
76 Database Name: insertUnfocussed
77 Database Class: InsertUnfocussed
78 Specifies how to display the insertion cursor when the widget │
80 does not have the focus. Must be none (the default) which means │
81 to not display the cursor, hollow which means to display a hol‐ │
82 low box, or solid which means to display a solid box. Note that │
83 hollow and solid will appear very similar when the -blockcursor │
84 option is false.
85 Command-Line Name:-maxundo
87 Database Name: maxUndo
88 Database Class: MaxUndo
89 Specifies the maximum number of compound undo actions on the
91 undo stack. A zero or a negative value imply an unlimited undo
92 stack.
93 Command-Line Name:-spacing1
95 Database Name: spacing1
96 Database Class: Spacing1
97 Requests additional space above each text line in the widget,
99 using any of the standard forms for screen distances. If a line
100 wraps, this option only applies to the first line on the dis‐
101 play. This option may be overridden with -spacing1 options in
102 tags.
103 Command-Line Name:-spacing2
105 Database Name: spacing2
106 Database Class: Spacing2
107 For lines that wrap (so that they cover more than one line on
109 the display) this option specifies additional space to provide
110 between the display lines that represent a single line of text.
111 The value may have any of the standard forms for screen dis‐
112 tances. This option may be overridden with -spacing2 options in
113 tags.
114 Command-Line Name:-spacing3
116 Database Name: spacing3
117 Database Class: Spacing3
118 Requests additional space below each text line in the widget,
120 using any of the standard forms for screen distances. If a line
121 wraps, this option only applies to the last line on the display.
122 This option may be overridden with -spacing3 options in tags.
123 Command-Line Name:-startline
125 Database Name: startLine
126 Database Class: StartLine
127 Specifies an integer line index representing the first line of
129 the underlying textual data store that should be contained in
130 the widget. This allows a text widget to reflect only a portion
131 of a larger piece of text. Instead of an integer, the empty
132 string can be provided to this configuration option, which will
133 configure the widget to start at the very first line in the tex‐
134 tual data store.
135 Command-Line Name:-state
137 Database Name: state
138 Database Class: State
139 Specifies one of two states for the text: normal or disabled. If
141 the text is disabled then characters may not be inserted or
142 deleted and no insertion cursor will be displayed, even if the
143 input focus is in the widget.
144 Command-Line Name:-tabs
146 Database Name: tabs
147 Database Class: Tabs
148 Specifies a set of tab stops for the window. The option's value
150 consists of a list of screen distances giving the positions of
151 the tab stops, each of which is a distance relative to the left
152 edge of the widget (excluding borders, padding, etc). Each posi‐
153 tion may optionally be followed in the next list element by one
154 of the keywords left, right, center, or numeric, which specifies
155 how to justify text relative to the tab stop. Left is the
156 default; it causes the text following the tab character to be
157 positioned with its left edge at the tab position. Right means
158 that the right edge of the text following the tab character is
159 positioned at the tab position, and center means that the text
160 is centered at the tab position. Numeric means that the decimal
161 point in the text is positioned at the tab position; if there is
162 no decimal point then the least significant digit of the number
163 is positioned just to the left of the tab position; if there is
164 no number in the text then the text is right-justified at the
165 tab position. For example, “-tabs {2c left 4c 6c center}” cre‐
166 ates three tab stops at two-centimeter intervals; the first two
167 use left justification and the third uses center justification.
168 If the list of tab stops does not have enough elements to cover
170 all of the tabs in a text line, then Tk extrapolates new tab
171 stops using the spacing and alignment from the last tab stop in
172 the list. Tab distances must be strictly positive, and must
173 always increase from one tab stop to the next (if not, an error
174 is thrown). The value of the -tabs option may be overridden by
175 -tabs options in tags.
176 If no -tabs option is specified, or if it is specified as an
178 empty list, then Tk uses default tabs spaced every eight (aver‐
179 age size) characters. To achieve a different standard spacing,
180 for example every 4 characters, simply configure the widget with
181 “-tabs "[expr {4 * [font measure $font 0]}] left" -tabstyle
182 wordprocessor”.
183 Command-Line Name:-tabstyle
185 Database Name: tabStyle
186 Database Class: TabStyle
187 Specifies how to interpret the relationship between tab stops on
189 a line and tabs in the text of that line. The value must be tab‐
190 ular (the default) or wordprocessor. Note that tabs are inter‐
191 preted as they are encountered in the text. If the tab style is
192 tabular then the n'th tab character in the line's text will be
193 associated with the n'th tab stop defined for that line. If the
194 tab character's x coordinate falls to the right of the n'th tab
195 stop, then a gap of a single space will be inserted as a fall‐
196 back. If the tab style is wordprocessor then any tab character
197 being laid out will use (and be defined by) the first tab stop
198 to the right of the preceding characters already laid out on
199 that line. The value of the -tabstyle option may be overridden
200 by -tabstyle options in tags.
201 Command-Line Name:-undo
203 Database Name: undo
204 Database Class: Undo
205 Specifies a boolean that says whether the undo mechanism is
207 active or not.
208 Command-Line Name:-width
210 Database Name: width
211 Database Class: Width
212 Specifies the desired width for the window in units of charac‐
214 ters in the font given by the -font option. If the font does not
215 have a uniform width then the width of the character “0” is used
216 in translating from character units to screen units.
217 Command-Line Name:-wrap
219 Database Name: wrap
220 Database Class: Wrap
221 Specifies how to handle lines in the text that are too long to
223 be displayed in a single line of the text's window. The value
224 must be none or char or word. A wrap mode of none means that
225 each line of text appears as exactly one line on the screen;
226 extra characters that do not fit on the screen are not dis‐
227 played. In the other modes each line of text will be broken up
228 into several screen lines if necessary to keep all the charac‐
229 ters visible. In char mode a screen line break may occur after
230 any character; in word mode a line break will only be made at
231 word boundaries.
232______________________________________________________________________________
233
235 The text command creates a new window (given by the pathName argument)
236 and makes it into a text widget. Additional options, described above,
237 may be specified on the command line or in the option database to con‐
238 figure aspects of the text such as its default background color and
239 relief. The text command returns the path name of the new window.
240 A text widget displays one or more lines of text and allows that text
242 to be edited. Text widgets support four different kinds of annotations
243 on the text, called tags, marks, embedded windows or embedded images.
244 Tags allow different portions of the text to be displayed with differ‐
245 ent fonts and colors. In addition, Tcl commands can be associated with
246 tags so that scripts are invoked when particular actions such as key‐
247 strokes and mouse button presses occur in particular ranges of the
248 text. See TAGS below for more details.
249 The second form of annotation consists of floating markers in the text
251 called “marks”. Marks are used to keep track of various interesting
252 positions in the text as it is edited. See MARKS below for more
253 details.
254 The third form of annotation allows arbitrary windows to be embedded in
256 a text widget. See EMBEDDED WINDOWS below for more details.
257 The fourth form of annotation allows Tk images to be embedded in a text
259 widget. See EMBEDDED IMAGES below for more details.
260 The text widget also has a built-in undo/redo mechanism. See THE UNDO
262 MECHANISM below for more details.
263 The text widget allows for the creation of peer widgets. These are
265 other text widgets which share the same underlying data (text, marks,
266 tags, images, etc). See PEER WIDGETS below for more details.
267
269 Many of the widget commands for texts take one or more indices as argu‐
270 ments. An index is a string used to indicate a particular place within
271 a text, such as a place to insert characters or one endpoint of a range
272 of characters to delete. Indices have the syntax
273 base modifier modifier modifier ...
274 Where base gives a starting point and the modifiers adjust the index
275 from the starting point (e.g. move forward or backward one character).
276 Every index must contain a base, but the modifiers are optional. Most
277 modifiers (as documented below) allow an optional submodifier. Valid
278 submodifiers are any and display. If the submodifier is abbreviated,
279 then it must be followed by whitespace, but otherwise there need be no
280 space between the submodifier and the following modifier. Typically
281 the display submodifier adjusts the meaning of the following modifier
282 to make it refer to visual or non-elided units rather than logical
283 units, but this is explained for each relevant case below. Lastly,
284 where count is used as part of a modifier, it can be positive or nega‐
285 tive, so “base - -3 lines” is perfectly valid (and equivalent to “base
286 +3lines”).
287 The base for an index must have one of the following forms:
289 line.char Indicates char'th character on line line. Lines are num‐
291 bered from 1 for consistency with other UNIX programs that
292 use this numbering scheme. Within a line, characters are
293 numbered from 0. If char is end then it refers to the new‐
294 line character that ends the line.
295 @x,y Indicates the character that covers the pixel whose x and y
297 coordinates within the text's window are x and y.
298 end Indicates the end of the text (the character just after the
300 last newline).
301 mark Indicates the character just after the mark whose name is
303 mark.
304 tag.first Indicates the first character in the text that has been
306 tagged with tag. This form generates an error if no char‐
307 acters are currently tagged with tag.
308 tag.last Indicates the character just after the last one in the text
310 that has been tagged with tag. This form generates an error
311 if no characters are currently tagged with tag.
312 pathName Indicates the position of the embedded window whose name is
314 pathName. This form generates an error if there is no
315 embedded window by the given name.
316 imageName Indicates the position of the embedded image whose name is
318 imageName. This form generates an error if there is no
319 embedded image by the given name.
320 If the base could match more than one of the above forms, such as a
322 mark and imageName both having the same value, then the form earlier in
323 the above list takes precedence. If modifiers follow the base index,
324 each one of them must have one of the forms listed below. Keywords such
325 as chars and wordend may be abbreviated as long as the abbreviation is
326 unambiguous.
327 + count ?submodifier? chars
329 Adjust the index forward by count characters, moving to later
330 lines in the text if necessary. If there are fewer than count
331 characters in the text after the current index, then set the
332 index to the last index in the text. Spaces on either side of
333 count are optional. If the display submodifier is given, elided
334 characters are skipped over without being counted. If any is
335 given, then all characters are counted. For historical reasons,
336 if neither modifier is given then the count actually takes place
337 in units of index positions (see INDICES for details). This be‐
338 haviour may be changed in a future major release, so if you need
339 an index count, you are encouraged to use indices instead wher‐
340 ever possible.
341 - count ?submodifier? chars
343 Adjust the index backward by count characters, moving to earlier
344 lines in the text if necessary. If there are fewer than count
345 characters in the text before the current index, then set the
346 index to the first index in the text (1.0). Spaces on either
347 side of count are optional. If the display submodifier is given,
348 elided characters are skipped over without being counted. If any
349 is given, then all characters are counted. For historical rea‐
350 sons, if neither modifier is given then the count actually takes
351 place in units of index positions (see INDICES for details).
352 This behavior may be changed in a future major release, so if
353 you need an index count, you are encouraged to use indices
354 instead wherever possible.
355 + count ?submodifier? indices
357 Adjust the index forward by count index positions, moving to
358 later lines in the text if necessary. If there are fewer than
359 count index positions in the text after the current index, then
360 set the index to the last index position in the text. Spaces on
361 either side of count are optional. Note that an index position
362 is either a single character or a single embedded image or
363 embedded window. If the display submodifier is given, elided
364 indices are skipped over without being counted. If any is given,
365 then all indices are counted; this is also the default behaviour
366 if no modifier is given.
367 - count ?submodifier? indices
369 Adjust the index backward by count index positions, moving to
370 earlier lines in the text if necessary. If there are fewer than
371 count index positions in the text before the current index, then
372 set the index to the first index position (1.0) in the text.
373 Spaces on either side of count are optional. If the display sub‐
374 modifier is given, elided indices are skipped over without being
375 counted. If any is given, then all indices are counted; this is
376 also the default behaviour if no modifier is given.
377 + count ?submodifier? lines
379 Adjust the index forward by count lines, retaining the same
380 character position within the line. If there are fewer than
381 count lines after the line containing the current index, then
382 set the index to refer to the same character position on the
383 last line of the text. Then, if the line is not long enough to
384 contain a character at the indicated character position, adjust
385 the character position to refer to the last character of the
386 line (the newline). Spaces on either side of count are
387 optional. If the display submodifier is given, then each visual
388 display line is counted separately. Otherwise, if any (or no
389 modifier) is given, then each logical line (no matter how many
390 times it is visually wrapped) counts just once. If the relevant
391 lines are not wrapped, then these two methods of counting are
392 equivalent.
393 - count ?submodifier? lines
395 Adjust the index backward by count logical lines, retaining the
396 same character position within the line. If there are fewer than
397 count lines before the line containing the current index, then
398 set the index to refer to the same character position on the
399 first line of the text. Then, if the line is not long enough to
400 contain a character at the indicated character position, adjust
401 the character position to refer to the last character of the
402 line (the newline). Spaces on either side of count are optional.
403 If the display submodifier is given, then each visual display
404 line is counted separately. Otherwise, if any (or no modifier)
405 is given, then each logical line (no matter how many times it is
406 visually wrapped) counts just once. If the relevant lines are
407 not wrapped, then these two methods of counting are equivalent.
408 ?submodifier? linestart
410 Adjust the index to refer to the first index on the line. If the
411 display submodifier is given, this is the first index on the
412 display line, otherwise on the logical line.
413 ?submodifier? lineend
415 Adjust the index to refer to the last index on the line (the
416 newline). If the display submodifier is given, this is the last
417 index on the display line, otherwise on the logical line.
418 ?submodifier? wordstart
420 Adjust the index to refer to the first character of the word
421 containing the current index. A word consists of any number of
422 adjacent characters that are letters, digits, or underscores, or
423 a single character that is not one of these. If the display sub‐
424 modifier is given, this only examines non-elided characters,
425 otherwise all characters (elided or not) are examined.
426 ?submodifier? wordend
428 Adjust the index to refer to the character just after the last
429 one of the word containing the current index. If the current
430 index refers to the last character of the text then it is not
431 modified. If the display submodifier is given, this only exam‐
432 ines non-elided characters, otherwise all characters (elided or
433 not) are examined.
434 If more than one modifier is present then they are applied in left-to-
436 right order. For example, the index “end - 1 chars” refers to the next-
437 to-last character in the text and “insert wordstart - 1 c” refers to
438 the character just before the first one in the word containing the
439 insertion cursor. Modifiers are applied one by one in this left to
440 right order, and after each step the resulting index is constrained to
441 be a valid index in the text widget. So, for example, the index “1.0
442 -1c +1c” refers to the index “2.0”.
443 Where modifiers result in index changes by display lines, display chars
445 or display indices, and the base refers to an index inside an elided
446 tag, that base index is considered to be equivalent to the first fol‐
447 lowing non-elided index.
448
450 The first form of annotation in text widgets is a tag. A tag is a tex‐
451 tual string that is associated with some of the characters in a text.
452 Tags may contain arbitrary characters, but it is probably best to avoid
453 using the characters “ ” (space), +, or -: these characters have spe‐
454 cial meaning in indices, so tags containing them cannot be used as
455 indices. There may be any number of tags associated with characters in
456 a text. Each tag may refer to a single character, a range of charac‐
457 ters, or several ranges of characters. An individual character may have
458 any number of tags associated with it.
459 A priority order is defined among tags, and this order is used in
461 implementing some of the tag-related functions described below. When a
462 tag is defined (by associating it with characters or setting its dis‐
463 play options or binding commands to it), it is given a priority higher
464 than any existing tag. The priority order of tags may be redefined
465 using the “pathName tag raise” and “pathName tag lower” widget com‐
466 mands.
467 Tags serve three purposes in text widgets. First, they control the way
469 information is displayed on the screen. By default, characters are dis‐
470 played as determined by the -background, -font, and -foreground options
471 for the text widget. However, display options may be associated with
472 individual tags using the “pathName tag configure” widget command. If a
473 character has been tagged, then the display options associated with the
474 tag override the default display style. The following options are cur‐
475 rently supported for tags:
476 -background color
478 Color specifies the background color to use for characters asso‐
479 ciated with the tag. It may have any of the forms accepted by
480 Tk_GetColor.
481 -bgstipple bitmap
483 Bitmap specifies a bitmap that is used as a stipple pattern for
484 the background. It may have any of the forms accepted by Tk_Get‐
485 Bitmap. If bitmap has not been specified, or if it is specified
486 as an empty string, then a solid fill will be used for the back‐
487 ground.
488 -borderwidth pixels
490 Pixels specifies the width of a border to draw around the tag
491 using any of the forms accepted by Tk_GetPixels. This option
492 should be used in conjunction with the -relief option to provide
493 the desired border.
494 -elide boolean
496 Elide specifies whether the data should be elided. Elided data
497 (characters, images, embedded windows, etc.) is not displayed
498 and takes no space on screen, but further on behaves just as
499 normal data.
500 -fgstipple bitmap
502 Bitmap specifies a bitmap that is used as a stipple pattern when
503 drawing text and other foreground information such as under‐
504 lines. It may have any of the forms accepted by Tk_GetBitmap. If
505 bitmap has not been specified, or if it is specified as an empty
506 string, then a solid fill will be used.
507 -font fontName
509 FontName is the name of a font to use for drawing characters. It
510 may have any of the forms accepted by Tk_GetFont.
511 -foreground color
513 Color specifies the color to use when drawing text and other
514 foreground information such as underlines. It may have any of
515 the forms accepted by Tk_GetColor.
516 -justify justify
518 If the first non-elided character of a display line has a tag
519 for which this option has been specified, then justify deter‐
520 mines how to justify the line. It must be one of left, right, or
521 center. If a line wraps, then the justification for each line on
522 the display is determined by the first non-elided character of
523 that display line.
524 -lmargin1 pixels
526 If the first non-elided character of a text line has a tag for
527 which this option has been specified, then pixels specifies how
528 much the line should be indented from the left edge of the win‐
529 dow. Pixels may have any of the standard forms for screen dis‐
530 tances. If a line of text wraps, this option only applies to the
531 first line on the display; the -lmargin2 option controls the
532 indentation for subsequent lines.
533 -lmargin2 pixels
535 If the first non-elided character of a display line has a tag
536 for which this option has been specified, and if the display
537 line is not the first for its text line (i.e., the text line has
538 wrapped), then pixels specifies how much the line should be
539 indented from the left edge of the window. Pixels may have any
540 of the standard forms for screen distances. This option is only
541 used when wrapping is enabled, and it only applies to the second
542 and later display lines for a text line.
543 -lmargincolor color
545 Color specifies the background color to use in regions that do
546 not contain characters because they are indented by -lmargin1 or
547 -lmargin2. It may have any of the forms accepted by Tk_GetColor.
548 If color has not been specified, or if it is specified as an
549 empty string, then the color used is specified by the -back‐
550 ground tag option (or, if this is also unspecified, by the
551 -background widget option).
552 -offset pixels
554 Pixels specifies an amount by which the text's baseline should
555 be offset vertically from the baseline of the overall line, in
556 pixels. For example, a positive offset can be used for super‐
557 scripts and a negative offset can be used for subscripts. Pixels
558 may have any of the standard forms for screen distances.
559 -overstrike boolean
561 Specifies whether or not to draw a horizontal rule through the
562 middle of characters. Boolean may have any of the forms accepted
563 by Tcl_GetBoolean.
564 -overstrikefg color
566 Color specifies the color to use when displaying the overstrike.
567 It may have any of the forms accepted by Tk_GetColor. If color
568 has not been specified, or if it is specified as an empty
569 string, then the color specified by the -foreground tag option
570 is used.
571 -relief relief
573 Relief specifies the relief style to use for drawing the border,
574 in any of the forms accepted by Tk_GetRelief. This option is
575 used in conjunction with the -borderwidth option to enable to
576 the desired border appearance.
577 -rmargin pixels
579 If the first non-elided character of a display line has a tag
580 for which this option has been specified, then pixels specifies
581 how wide a margin to leave between the end of the line and the
582 right edge of the window. Pixels may have any of the standard
583 forms for screen distances. This option is only used when wrap‐
584 ping is enabled. If a text line wraps, the right margin for each
585 line on the display is determined by the first non-elided char‐
586 acter of that display line.
587 -rmargincolor color
589 Color specifies the background color to use in regions that do
590 not contain characters because they are indented by -rmargin. It
591 may have any of the forms accepted by Tk_GetColor. If color has
592 not been specified, or if it is specified as an empty string,
593 then the color used is specified by the -background tag option
594 (or, if this is also unspecified, by the -background widget
595 option).
596 -selectbackground color
598 Color specifies the background color to use when displaying
599 selected items. It may have any of the forms accepted by Tk_Get‐
600 Color. If color has not been specified, or if it is specified as
601 an empty string, then the color specified by the -background tag
602 option is used.
603 -selectforeground color
605 Color specifies the foreground color to use when displaying
606 selected items. It may have any of the forms accepted by Tk_Get‐
607 Color. If color has not been specified, or if it is specified as
608 an empty string, then the color specified by the -foreground tag
609 option is used.
610 -spacing1 pixels
612 Pixels specifies how much additional space should be left above
613 each text line, using any of the standard forms for screen dis‐
614 tances. If a line wraps, this option only applies to the first
615 line on the display.
616 -spacing2 pixels
618 For lines that wrap, this option specifies how much additional
619 space to leave between the display lines for a single text line.
620 Pixels may have any of the standard forms for screen distances.
621 -spacing3 pixels
623 Pixels specifies how much additional space should be left below
624 each text line, using any of the standard forms for screen dis‐
625 tances. If a line wraps, this option only applies to the last
626 line on the display.
627 -tabs tabList
629 TabList specifies a set of tab stops in the same form as for the
630 -tabs option for the text widget. This option only applies to a
631 display line if it applies to the first non-elided character on
632 that display line. If this option is specified as an empty
633 string, it cancels the option, leaving it unspecified for the
634 tag (the default). If the option is specified as a non-empty
635 string that is an empty list, such as -tags { }, then it
636 requests default 8-character tabs as described for the -tags
637 widget option.
638 -tabstyle style
640 Style specifies either the tabular or wordprocessor style of
641 tabbing to use for the text widget. This option only applies to
642 a display line if it applies to the first non-elided character
643 on that display line. If this option is specified as an empty
644 string, it cancels the option, leaving it unspecified for the
645 tag (the default).
646 -underline boolean
648 Boolean specifies whether or not to draw an underline underneath
649 characters. It may have any of the forms accepted by Tcl_Get‐
650 Boolean.
651 -underlinefg color
653 Color specifies the color to use when displaying the underline.
654 It may have any of the forms accepted by Tk_GetColor. If color
655 has not been specified, or if it is specified as an empty
656 string, then the color specified by the -foreground tag option
657 is used.
658 -wrap mode
660 Mode specifies how to handle lines that are wider than the
661 text's window. This option only applies to a display line if it
662 applies to the first non-elided character on that display line.
663 It has the same legal values as the -wrap option for the text
664 widget: none, char, or word. If this tag option is specified, it
665 overrides the -wrap option for the text widget.
666 If a character has several tags associated with it, and if their dis‐
668 play options conflict, then the options of the highest priority tag are
669 used. If a particular display option has not been specified for a par‐
670 ticular tag, or if it is specified as an empty string, then that option
671 will never be used; the next-highest-priority tag's option will used
672 instead. If no tag specifies a particular display option, then the
673 default style for the widget will be used.
674 The second purpose for tags is event bindings. You can associate bind‐
676 ings with a tag in much the same way you can associate bindings with a
677 widget class: whenever particular X events occur on characters with the
678 given tag, a given Tcl command will be executed. Tag bindings can be
679 used to give behaviors to ranges of characters; among other things,
680 this allows hypertext-like features to be implemented. For details, see
681 the description of the “pathName tag bind” widget command below. Tag
682 bindings are shared between all peer widgets (including any bindings
683 for the special sel tag).
684 The third use for tags is in managing the selection. See THE SELECTION
686 below. With the exception of the special sel tag, all tags are shared
687 between peer text widgets, and may be manipulated on an equal basis
688 from any such widget. The sel tag exists separately and independently
689 in each peer text widget (but any tag bindings to sel are shared).
690
692 The second form of annotation in text widgets is a mark. Marks are used
693 for remembering particular places in a text. They are something like
694 tags, in that they have names and they refer to places in the file, but
695 a mark is not associated with particular characters. Instead, a mark is
696 associated with the gap between two characters. Only a single position
697 may be associated with a mark at any given time. If the characters
698 around a mark are deleted the mark will still remain; it will just have
699 new neighbor characters. In contrast, if the characters containing a
700 tag are deleted then the tag will no longer have an association with
701 characters in the file. Marks may be manipulated with the “pathName
702 mark” widget command, and their current locations may be determined by
703 using the mark name as an index in widget commands.
704 Each mark also has a “gravity”, which is either left or right. The
706 gravity for a mark specifies what happens to the mark when text is
707 inserted at the point of the mark. If a mark has left gravity, then the
708 mark is treated as if it were attached to the character on its left, so
709 the mark will remain to the left of any text inserted at the mark posi‐
710 tion. If the mark has right gravity, new text inserted at the mark
711 position will appear to the left of the mark (so that the mark remains
712 rightmost). The gravity for a mark defaults to right.
713 The name space for marks is different from that for tags: the same name
715 may be used for both a mark and a tag, but they will refer to different
716 things.
717 Two marks have special significance. First, the mark insert is associ‐
719 ated with the insertion cursor, as described under THE INSERTION CURSOR
720 below. Second, the mark current is associated with the character clos‐
721 est to the mouse and is adjusted automatically to track the mouse posi‐
722 tion and any changes to the text in the widget (one exception: current
723 is not updated in response to mouse motions if a mouse button is down;
724 the update will be deferred until all mouse buttons have been
725 released). Neither of these special marks may be deleted. With the
726 exception of these two special marks, all marks are shared between peer
727 text widgets, and may be manipulated on an equal basis from any peer.
728
730 The third form of annotation in text widgets is an embedded window.
731 Each embedded window annotation causes a window to be displayed at a
732 particular point in the text. There may be any number of embedded win‐
733 dows in a text widget, and any widget may be used as an embedded window
734 (subject to the usual rules for geometry management, which require the
735 text window to be the parent of the embedded window or a descendant of
736 its parent).
737 The embedded window's position on the screen will be updated as the
739 text is modified or scrolled, and it will be mapped and unmapped as it
740 moves into and out of the visible area of the text widget. Each embed‐
741 ded window occupies one unit's worth of index space in the text widget,
742 and it may be referred to either by the name of its embedded window or
743 by its position in the widget's index space. If the range of text con‐
744 taining the embedded window is deleted then the window is destroyed.
745 Similarly if the text widget as a whole is deleted, then the window is
746 destroyed.
747 Eliding an embedded window immediately after scheduling it for creation
749 via pathName window create index -create will prevent it from being
750 effectively created. Uneliding an elided embedded window scheduled for
751 creation via pathName window create index -create will automatically
752 trigger the associated creation script. After destroying an elided
753 embedded window, the latter won't get automatically recreated.
754 When an embedded window is added to a text widget with the pathName
756 window create widget command, several configuration options may be
757 associated with it. These options may be modified later with the path‐
758 Name window configure widget command. The following options are cur‐
759 rently supported:
760 -align where
762 If the window is not as tall as the line in which it is dis‐
763 played, this option determines where the window is displayed in
764 the line. Where must have one of the values top (align the top
765 of the window with the top of the line), center (center the win‐
766 dow within the range of the line), bottom (align the bottom of
767 the window with the bottom of the line's area), or baseline
768 (align the bottom of the window with the baseline of the line).
769 -create script
771 Specifies a Tcl script that may be evaluated to create the win‐
772 dow for the annotation. If no -window option has been specified
773 for the annotation this script will be evaluated when the anno‐
774 tation is about to be displayed on the screen. Script must cre‐
775 ate a window for the annotation and return the name of that win‐
776 dow as its result. Two substitutions will be performed in script
777 before evaluation. %W will be substituted by the name of the
778 parent text widget, and %% will be substituted by a single %.
779 If the annotation's window should ever be deleted, script will
780 be evaluated again the next time the annotation is displayed.
781 -padx pixels
783 Pixels specifies the amount of extra space to leave on each side
784 of the embedded window. It may have any of the usual forms
785 defined for a screen distance.
786 -pady pixels
788 Pixels specifies the amount of extra space to leave on the top
789 and on the bottom of the embedded window. It may have any of the
790 usual forms defined for a screen distance.
791 -stretch boolean
793 If the requested height of the embedded window is less than the
794 height of the line in which it is displayed, this option can be
795 used to specify whether the window should be stretched verti‐
796 cally to fill its line. If the -pady option has been specified
797 as well, then the requested padding will be retained even if the
798 window is stretched.
799 -window pathName
801 Specifies the name of a window to display in the annotation.
802 Note that if a pathName has been set, then later configuring a
803 window to the empty string will not delete the widget corre‐
804 sponding to the old pathName. Rather it will remove the associ‐
805 ation between the old pathName and the text widget. If multiple
806 peer widgets are in use, it is usually simpler to use the -cre‐
807 ate option if embedded windows are desired in each peer.
808
810 The final form of annotation in text widgets is an embedded image. Each
811 embedded image annotation causes an image to be displayed at a particu‐
812 lar point in the text. There may be any number of embedded images in a
813 text widget, and a particular image may be embedded in multiple places
814 in the same text widget.
815 The embedded image's position on the screen will be updated as the text
817 is modified or scrolled. Each embedded image occupies one unit's worth
818 of index space in the text widget, and it may be referred to either by
819 its position in the widget's index space, or the name it is assigned
820 when the image is inserted into the text widget with pathName image
821 create. If the range of text containing the embedded image is deleted
822 then that copy of the image is removed from the screen.
823 Eliding an embedded image immediately after scheduling it for creation
825 via pathName image create index -create will prevent it from being
826 effectively created. Uneliding an elided embedded image scheduled for
827 creation via pathName image create index -create will automatically
828 trigger the associated creation script. After destroying an elided
829 embedded image, the latter won't get automatically recreated.
830 When an embedded image is added to a text widget with the pathName
832 image create widget command, a name unique to this instance of the
833 image is returned. This name may then be used to refer to this image
834 instance. The name is taken to be the value of the -name option
835 (described below). If the -name option is not provided, the -image name
836 is used instead. If the imageName is already in use in the text wid‐
837 get, then #nn is added to the end of the imageName, where nn is an
838 arbitrary integer. This insures the imageName is unique. Once this name
839 is assigned to this instance of the image, it does not change, even
840 though the -image or -name values can be changed with pathName image
841 configure.
842 When an embedded image is added to a text widget with the pathName
844 image create widget command, several configuration options may be asso‐
845 ciated with it. These options may be modified later with the pathName
846 image configure widget command. The following options are currently
847 supported:
848 -align where
850 If the image is not as tall as the line in which it is dis‐
851 played, this option determines where the image is displayed in
852 the line. Where must have one of the values top (align the top
853 of the image with the top of the line), center (center the image
854 within the range of the line), bottom (align the bottom of the
855 image with the bottom of the line's area), or baseline (align
856 the bottom of the image with the baseline of the line).
857 -image image
859 Specifies the name of the Tk image to display in the annotation.
860 If image is not a valid Tk image, then an error is returned.
861 -name ImageName
863 Specifies the name by which this image instance may be refer‐
864 enced in the text widget. If ImageName is not supplied, then the
865 name of the Tk image is used instead. If the imageName is
866 already in use, #nn is appended to the end of the name as
867 described above.
868 -padx pixels
870 Pixels specifies the amount of extra space to leave on each side
871 of the embedded image. It may have any of the usual forms
872 defined for a screen distance.
873 -pady pixels
875 Pixels specifies the amount of extra space to leave on the top
876 and on the bottom of the embedded image. It may have any of the
877 usual forms defined for a screen distance.
878
880 Selection support is implemented via tags. If the -exportselection
881 option for the text widget is true then the sel tag will be associated
882 with the selection:
883 [1] Whenever characters are tagged with sel the text widget will
885 claim ownership of the selection.
886 [2] Attempts to retrieve the selection will be serviced by the text
888 widget, returning all the characters with the sel tag.
889 [3] If the selection is claimed away by another application or by
891 another window within this application, then the sel tag will be
892 removed from all characters in the text.
893 [4] Whenever the sel tag range changes a virtual event <<Selection>>
895 is generated.
896 The sel tag is automatically defined when a text widget is created, and
898 it may not be deleted with the “pathName tag delete” widget command.
899 Furthermore, the -selectbackground, -selectborderwidth, and -select‐
900 foreground options for the text widget are tied to the -background,
901 -borderwidth, and -foreground options for the sel tag: changes in
902 either will automatically be reflected in the other. Also the -inac‐
903 tiveselectbackground option for the text widget is used instead of
904 -selectbackground when the text widget does not have the focus. This
905 allows programmatic control over the visualization of the sel tag for
906 foreground and background windows, or to have sel not shown at all
907 (when -inactiveselectbackground is empty) for background windows. Each
908 peer text widget has its own sel tag which can be separately configured
909 and set.
910
912 The mark named insert has special significance in text widgets. It is
913 defined automatically when a text widget is created and it may not be
914 unset with the “pathName mark unset” widget command. The insert mark
915 represents the position of the insertion cursor, and the insertion cur‐
916 sor will automatically be drawn at this point whenever the text widget
917 has the input focus.
918
920 The text widget can keep track of changes to the content of the widget
921 by means of the modified flag. Inserting or deleting text will set this
922 flag. The flag can be queried, set and cleared programmatically as
923 well. Whenever the flag changes state a <<Modified>> virtual event is
924 generated. See the pathName edit modified widget command for more
925 details.
926
928 The text widget has an unlimited undo and redo mechanism (when the
929 -undo widget option is true) which records every insert and delete
930 action on a stack.
931 Boundaries (called “separators”) are inserted between edit actions. The
933 purpose of these separators is to group inserts, deletes and replaces
934 into one compound edit action. When undoing a change everything between
935 two separators will be undone. The undone changes are then moved to the
936 redo stack, so that an undone edit can be redone again. The redo stack
937 is cleared whenever new edit actions are recorded on the undo stack.
938 The undo and redo stacks can be cleared to keep their depth under con‐
939 trol.
940 Separators are inserted automatically when the -autoseparators widget
942 option is true. You can insert separators programmatically as well. If
943 a separator is already present at the top of the undo stack no other
944 will be inserted. That means that two separators on the undo stack are
945 always separated by at least one insert or delete action.
946 The <<UndoStack>> virtual event is generated every time the undo stack
948 or the redo stack becomes empty or unempty.
949 The undo mechanism is also linked to the modified flag. This means that
951 undoing or redoing changes can take a modified text widget back to the
952 unmodified state or vice versa. The modified flag will be set automati‐
953 cally to the appropriate state. This automatic coupling does not work
954 when the modified flag has been set by the user, until the flag has
955 been reset again.
956 See below for the pathName edit widget command that controls the undo
958 mechanism.
959
961 The text widget has a separate store of all its data concerning each
962 line's textual contents, marks, tags, images and windows, and the undo
963 stack.
964 While this data store cannot be accessed directly (i.e. without a text
966 widget as an intermediary), multiple text widgets can be created, each
967 of which present different views on the same underlying data. Such text
968 widgets are known as peer text widgets.
969 As text is added, deleted, edited and coloured in any one widget, and
971 as images, marks, tags are adjusted, all such changes will be reflected
972 in all peers.
973 All data and markup is shared, except for a few small details. First,
975 the sel tag may be set and configured (in its display style) differ‐
976 ently for each peer. Second, each peer has its own insert and current
977 mark positions (but all other marks are shared). Third, embedded win‐
978 dows, which are arbitrary other widgets, cannot be shared between
979 peers. This means the -window option of embedded windows is indepen‐
980 dently set for each peer (it is advisable to use the -create script
981 capabilities to allow each peer to create its own embedded windows as
982 needed). Fourth, all of the configuration options of each peer (e.g.
983 -font, etc) can be set independently, with the exception of -undo,
984 -maxundo, -autoseparators (i.e. all undo, redo and modified state
985 issues are shared).
986 Finally any single peer need not contain all lines from the underlying
988 data store. When creating a peer, a contiguous range of lines (e.g.
989 only lines 52 through 125) may be specified. This allows a peer to con‐
990 tain just a small portion of the overall text. The range of lines will
991 expand and contract as text is inserted or deleted. The peer will only
992 ever display complete lines of text (one cannot share just part of a
993 line). If the peer's contents contracts to nothing (i.e. all complete
994 lines in the peer widget have been deleted from another widget), then
995 it is impossible for new lines to be inserted. The peer will simply
996 become an empty shell on which the background can be configured, but
997 which will never show any content (without manual reconfiguration of
998 the start and end lines). Note that a peer which does not contain all
999 of the underlying data store still has indices numbered from “1.0” to
1000 “end”. It is simply that those indices reflect a subset of the total
1001 data, and data outside the contained range is not accessible to the
1002 peer. This means that the command peerName index end may return quite
1003 different values in different peers. Similarly, commands like peerName
1004 tag ranges will not return index ranges outside that which is meaning‐
1005 ful to the peer. The configuration options -startline and -endline may
1006 be used to control how much of the underlying data is contained in any
1007 given text widget.
1008 Note that peers are really peers. Deleting the “original” text widget
1010 will not cause any other peers to be deleted, or otherwise affected.
1011 See below for the pathName peer widget command that controls the cre‐
1013 ation of peer widgets.
1014
1016 In order to maintain a responsive user-experience, the text widget cal‐
1017 culates lines metrics (line heights in pixels) asynchronously. Because
1018 of this, some commands of the text widget may return wrong results if
1019 the asynchronous calculations are not finished at the time of calling.
1020 This applies to pathName count -ypixels and pathName yview.
1021 Again for performance reasons, it would not be appropriate to let these
1023 commands always wait for the end of the update calculation each time
1024 they are called. In most use cases of these commands a more or less
1025 inaccurate result does not really matter compared to execution speed.
1026 In case accurate result is needed (and if the text widget is managed by
1028 a geometry manager), one can resort to pathName sync and pathName pend‐
1029 ingsync to control the synchronization of the view of text widgets.
1030 The <<WidgetViewSync>> virtual event fires when the line heights of the
1032 text widget become obsolete (due to some editing command or configura‐
1033 tion change), and again when the internal data of the text widget are
1034 back in sync with the widget view. The detail field (%d substitution)
1035 is either true (when the widget is in sync) or false (when it is not).
1036 pathName sync, pathName pendingsync and <<WidgetViewSync>> apply to
1038 each text widget independently of its peers.
1039 Examples of use:
1041 ## Example 1:
1042 # immediately complete line metrics at any cost (GUI unresponsive)
1043 $w sync
1044 $w yview moveto $fraction
1045 ## Example 2:
1047 # synchronously wait for up-to-date line metrics (GUI responsive)
1048 # before executing the scheduled command, but don't block execution flow
1049 $w sync -command [list $w yview moveto $fraction]
1050 ## Example 3:
1052 # init
1053 set yud($w) 0
1054 proc updateaction w {
1055 set ::yud($w) 1
1056 # any other update action here...
1057 }
1058 # runtime, synchronously wait for up-to-date line metrics (GUI responsive)
1059 $w sync -command [list updateaction $w]
1060 vwait yud($w)
1061 $w yview moveto $fraction
1062 ## Example 4:
1064 # init
1065 set todo($w) {}
1066 proc updateaction w {
1067 foreach cmd $::todo($w) {uplevel #0 $cmd}
1068 set todo($w) {}
1069 }
1070 # runtime
1071 lappend todo($w) [list $w yview moveto $fraction]
1072 $w sync -command [list updateaction $w]
1073 ## Example 5:
1075 # init
1076 set todo($w) {}
1077 bind $w <<WidgetViewSync>> {
1078 if {%d} {
1079 foreach cmd $todo(%W) {eval $cmd}
1080 set todo(%W) {}
1081 }
1082 }
1083 # runtime
1084 if {![$w pendingsync]} {
1085 $w yview moveto $fraction
1086 } else {
1087 lappend todo($w) [list $w yview moveto $fraction]
1088 }
1089
1091 The text command creates a new Tcl command whose name is the same as
1092 the path name of the text's window. This command may be used to invoke
1093 various operations on the widget. It has the following general form:
1094 pathName option ?arg arg ...?
1095 PathName is the name of the command, which is the same as the text wid‐
1096 get's path name. Option and the args determine the exact behavior of
1097 the command. The following commands are possible for text widgets:
1098 pathName bbox index
1100 Returns a list of four elements describing the screen area of
1101 the character given by index. The first two elements of the list
1102 give the x and y coordinates of the upper-left corner of the
1103 area occupied by the character, and the last two elements give
1104 the width and height of the area. If the character is only par‐
1105 tially visible on the screen, then the return value reflects
1106 just the visible part. If the character is not visible on the
1107 screen then the return value is an empty list.
1108 pathName cget option
1110 Returns the current value of the configuration option given by
1111 option. Option may have any of the values accepted by the text
1112 command.
1113 pathName compare index1 op index2
1115 Compares the indices given by index1 and index2 according to the
1116 relational operator given by op, and returns 1 if the relation‐
1117 ship is satisfied and 0 if it is not. Op must be one of the
1118 operators <, <=, ==, >=, >, or !=. If op is == then 1 is
1119 returned if the two indices refer to the same character, if op
1120 is < then 1 is returned if index1 refers to an earlier character
1121 in the text than index2, and so on.
1122 pathName configure ?option? ?value option value ...?
1124 Query or modify the configuration options of the widget. If no
1125 option is specified, returns a list describing all of the avail‐
1126 able options for pathName (see Tk_ConfigureInfo for information
1127 on the format of this list). If option is specified with no
1128 value, then the command returns a list describing the one named
1129 option (this list will be identical to the corresponding sublist
1130 of the value returned if no option is specified). If one or more
1131 option-value pairs are specified, then the command modifies the
1132 given widget option(s) to have the given value(s); in this case
1133 the command returns an empty string. Option may have any of the
1134 values accepted by the text command.
1135 pathName count ?options? index1 index2
1137 Counts the number of relevant things between the two indices. If
1138 index1 is after index2, the result will be a negative number
1139 (and this holds for each of the possible options). The actual
1140 items which are counted depend on the options given. The result
1141 is a list of integers, one for the result of each counting
1142 option given. Valid counting options are -chars, -displaychars,
1143 -displayindices, -displaylines, -indices, -lines, -xpixels and
1144 -ypixels. The default value, if no option is specified, is
1145 -indices. There is an additional possible option -update which
1146 is a modifier. If given (and if the text widget is managed by a
1147 geometry manager), then all subsequent options ensure that any
1148 possible out of date information is recalculated. This cur‐
1149 rently only has any effect for the -ypixels count (which, if
1150 -update is not given, will use the text widget's current cached
1151 value for each line). This -update option is obsoleted by path‐
1152 Name sync, pathName pendingsync and <<WidgetViewSync>>. The
1153 count options are interpreted as follows:
1154 -chars count all characters, whether elided or not. Do not count
1156 embedded windows or images.
1157 -displaychars
1159 count all non-elided characters.
1160 -displayindices
1162 count all non-elided characters, windows and images.
1163 -displaylines
1165 count all display lines (i.e. counting one for each time
1166 a line wraps) from the line of the first index up to, but
1167 not including the display line of the second index.
1168 Therefore if they are both on the same display line, zero
1169 will be returned. By definition displaylines are visible
1170 and therefore this only counts portions of actual visible
1171 lines.
1172 -indices
1174 count all characters and embedded windows or images (i.e.
1175 everything which counts in text-widget index space),
1176 whether they are elided or not.
1177 -lines count all logical lines (irrespective of wrapping) from
1179 the line of the first index up to, but not including the
1180 line of the second index. Therefore if they are both on
1181 the same line, zero will be returned. Logical lines are
1182 counted whether they are currently visible (non-elided)
1183 or not.
1184 -xpixels
1186 count the number of horizontal pixels from the first
1187 pixel of the first index to (but not including) the first
1188 pixel of the second index. To count the total desired
1189 width of the text widget (assuming wrapping is not
1190 enabled), first find the longest line and then use “.text
1191 count -xpixels "${line}.0" "${line}.0 lineend"”.
1192 -ypixels
1194 count the number of vertical pixels from the first pixel
1195 of the first index to (but not including) the first pixel
1196 of the second index. If both indices are on the same dis‐
1197 play line, zero will be returned. To count the total num‐
1198 ber of vertical pixels in the text widget, use “.text
1199 count -ypixels 1.0 end”, and to ensure this is up to
1200 date, use “.text count -update -ypixels 1.0 end”.
1201 The command returns a positive or negative integer corresponding
1203 to the number of items counted between the two indices. One such
1204 integer is returned for each counting option given, so a list is
1205 returned if more than one option was supplied. For example
1206 “.text count -xpixels -ypixels 1.3 4.5” is perfectly valid and
1207 will return a list of two elements.
1208 pathName debug ?boolean?
1210 If boolean is specified, then it must have one of the true or
1211 false values accepted by Tcl_GetBoolean. If the value is a true
1212 one then internal consistency checks will be turned on in the B-
1213 tree code associated with text widgets. If boolean has a false
1214 value then the debugging checks will be turned off. In either
1215 case the command returns an empty string. If boolean is not
1216 specified then the command returns on or off to indicate whether
1217 or not debugging is turned on. There is a single debugging
1218 switch shared by all text widgets: turning debugging on or off
1219 in any widget turns it on or off for all widgets. For widgets
1220 with large amounts of text, the consistency checks may cause a
1221 noticeable slow-down.
1222 When debugging is turned on, the drawing routines of the text
1224 widget set the global variables tk_textRedraw and tk_textRelay‐
1225 out to the lists of indices that are redrawn. The values of
1226 these variables are tested by Tk's test suite.
1227 pathName delete index1 ?index2 ...?
1229 Delete a range of characters from the text. If both index1 and
1230 index2 are specified, then delete all the characters starting
1231 with the one given by index1 and stopping just before index2
1232 (i.e. the character at index2 is not deleted). If index2 does
1233 not specify a position later in the text than index1 then no
1234 characters are deleted. If index2 is not specified then the
1235 single character at index1 is deleted. Attempts to delete char‐
1236 acters in a way that would leave the text without a newline as
1237 the last character will be tweaked by the text widget to avoid
1238 this. In particular, deletion of complete lines of text up to
1239 the end of the text will also delete the newline character just
1240 before the deleted block so that it is replaced by the new final
1241 newline of the text widget. The command returns an empty
1242 string. If more indices are given, multiple ranges of text will
1243 be deleted. All indices are first checked for validity before
1244 any deletions are made. They are sorted and the text is removed
1245 from the last range to the first range so deleted text does not
1246 cause an undesired index shifting side-effects. If multiple
1247 ranges with the same start index are given, then the longest
1248 range is used. If overlapping ranges are given, then they will
1249 be merged into spans that do not cause deletion of text outside
1250 the given ranges due to text shifted during deletion.
1251 pathName dlineinfo index
1253 Returns a list with five elements describing the area occupied
1254 by the display line containing index. The first two elements of
1255 the list give the x and y coordinates of the upper-left corner
1256 of the area occupied by the line, the third and fourth elements
1257 give the width and height of the area, and the fifth element
1258 gives the position of the baseline for the line, measured down
1259 from the top of the area. All of this information is measured in
1260 pixels. If the current wrap mode is none and the line extends
1261 beyond the boundaries of the window, the area returned reflects
1262 the entire area of the line, including the portions that are out
1263 of the window. If the line is shorter than the full width of the
1264 window then the area returned reflects just the portion of the
1265 line that is occupied by characters and embedded windows. If the
1266 display line containing index is not visible on the screen then
1267 the return value is an empty list.
1268 pathName dump ?switches? index1 ?index2?
1270 Return the contents of the text widget from index1 up to, but
1271 not including index2, including the text and information about
1272 marks, tags, and embedded windows. If index2 is not specified,
1273 then it defaults to one character past index1. The information
1274 is returned in the following format:
1275 key1 value1 index1 key2 value2 index2 ...
1277 The possible key values are text, mark, tagon, tagoff, image,
1279 and window. The corresponding value is the text, mark name, tag
1280 name, image name, or window name. The index information is the
1281 index of the start of the text, mark, tag transition, image or
1282 window. One or more of the following switches (or abbreviations
1283 thereof) may be specified to control the dump:
1284 -all Return information about all elements: text, marks, tags,
1286 images and windows. This is the default.
1287 -command command
1289 Instead of returning the information as the result of the
1290 dump operation, invoke the command on each element of the
1291 text widget within the range. The command has three
1292 arguments appended to it before it is evaluated: the key,
1293 value, and index.
1294 -image Include information about images in the dump results.
1296 -mark Include information about marks in the dump results.
1298 -tag Include information about tag transitions in the dump
1300 results. Tag information is returned as tagon and tagoff
1301 elements that indicate the begin and end of each range of
1302 each tag, respectively.
1303 -text Include information about text in the dump results. The
1305 value is the text up to the next element or the end of
1306 range indicated by index2. A text element does not span
1307 newlines. A multi-line block of text that contains no
1308 marks or tag transitions will still be dumped as a set of
1309 text segments that each end with a newline. The newline
1310 is part of the value.
1311 -window
1313 Include information about embedded windows in the dump
1314 results. The value of a window is its Tk pathname, unless
1315 the window has not been created yet. (It must have a cre‐
1316 ate script.) In this case an empty string is returned,
1317 and you must query the window by its index position to
1318 get more information.
1319 pathName edit option ?arg arg ...?
1321 This command controls the undo mechanism and the modified flag.
1322 The exact behavior of the command depends on the option argument
1323 that follows the edit argument. The following forms of the com‐
1324 mand are currently supported:
1325 pathName edit canredo
1327 Returns a boolean true if redo is possible, i.e. when the
1328 redo stack is not empty. Otherwise returns false.
1329 pathName edit canundo
1331 Returns a boolean true if undo is possible, i.e. when the
1332 undo stack is not empty. Otherwise returns false.
1333 pathName edit modified ?boolean?
1335 If boolean is not specified, returns the modified flag of
1336 the widget. The insert, delete, edit undo and edit redo
1337 commands or the user can set or clear the modified flag.
1338 If boolean is specified, sets the modified flag of the
1339 widget to boolean.
1340 pathName edit redo
1342 When the -undo option is true, reapplies the last undone
1343 edits provided no other edits were done since then. Gen‐
1344 erates an error when the redo stack is empty. Does noth‐
1345 ing when the -undo option is false.
1346 pathName edit reset
1348 Clears the undo and redo stacks.
1349 pathName edit separator
1351 Inserts a separator (boundary) on the undo stack. Does
1352 nothing when the -undo option is false.
1353 pathName edit undo
1355 Undoes the last edit action when the -undo option is
1356 true. An edit action is defined as all the insert and
1357 delete commands that are recorded on the undo stack in
1358 between two separators. Generates an error when the undo
1359 stack is empty. Does nothing when the -undo option is
1360 false.
1361 pathName get ?-displaychars? ?--? index1 ?index2 ...?
1363 Return a range of characters from the text. The return value
1364 will be all the characters in the text starting with the one
1365 whose index is index1 and ending just before the one whose index
1366 is index2 (the character at index2 will not be returned). If
1367 index2 is omitted then the single character at index1 is
1368 returned. If there are no characters in the specified range
1369 (e.g. index1 is past the end of the file or index2 is less than
1370 or equal to index1) then an empty string is returned. If the
1371 specified range contains embedded windows, no information about
1372 them is included in the returned string. If multiple index pairs
1373 are given, multiple ranges of text will be returned in a list.
1374 Invalid ranges will not be represented with empty strings in the
1375 list. The ranges are returned in the order passed to pathName
1376 get. If the -displaychars option is given, then, within each
1377 range, only those characters which are not elided will be
1378 returned. This may have the effect that some of the returned
1379 ranges are empty strings.
1380 pathName image option ?arg arg ...?
1382 This command is used to manipulate embedded images. The behavior
1383 of the command depends on the option argument that follows the
1384 tag argument. The following forms of the command are currently
1385 supported:
1386 pathName image cget index option
1388 Returns the value of a configuration option for an embed‐
1389 ded image. Index identifies the embedded image, and
1390 option specifies a particular configuration option, which
1391 must be one of the ones listed in the section EMBEDDED
1392 IMAGES.
1393 pathName image configure index ?option value ...?
1395 Query or modify the configuration options for an embedded
1396 image. If no option is specified, returns a list describ‐
1397 ing all of the available options for the embedded image
1398 at index (see Tk_ConfigureInfo for information on the
1399 format of this list). If option is specified with no
1400 value, then the command returns a list describing the one
1401 named option (this list will be identical to the corre‐
1402 sponding sublist of the value returned if no option is
1403 specified). If one or more option-value pairs are speci‐
1404 fied, then the command modifies the given option(s) to
1405 have the given value(s); in this case the command returns
1406 an empty string. See EMBEDDED IMAGES for information on
1407 the options that are supported.
1408 pathName image create index ?option value ...?
1410 This command creates a new image annotation, which will
1411 appear in the text at the position given by index. Any
1412 number of option-value pairs may be specified to config‐
1413 ure the annotation. Returns a unique identifier that may
1414 be used as an index to refer to this image. See EMBEDDED
1415 IMAGES for information on the options that are supported,
1416 and a description of the identifier returned.
1417 pathName image names
1419 Returns a list whose elements are the names of all image
1420 instances currently embedded in window.
1421 pathName index index
1423 Returns the position corresponding to index in the form
1424 line.char where line is the line number and char is the charac‐
1425 ter number. Index may have any of the forms described under
1426 INDICES above.
1427 pathName insert index chars ?tagList chars tagList ...?
1429 Inserts all of the chars arguments just before the character at
1430 index. If index refers to the end of the text (the character
1431 after the last newline) then the new text is inserted just
1432 before the last newline instead. If there is a single chars
1433 argument and no tagList, then the new text will receive any tags
1434 that are present on both the character before and the character
1435 after the insertion point; if a tag is present on only one of
1436 these characters then it will not be applied to the new text. If
1437 tagList is specified then it consists of a list of tag names;
1438 the new characters will receive all of the tags in this list and
1439 no others, regardless of the tags present around the insertion
1440 point. If multiple chars-tagList argument pairs are present,
1441 they produce the same effect as if a separate pathName insert
1442 widget command had been issued for each pair, in order. The last
1443 tagList argument may be omitted.
1444 pathName mark option ?arg arg ...?
1446 This command is used to manipulate marks. The exact behavior of
1447 the command depends on the option argument that follows the mark
1448 argument. The following forms of the command are currently sup‐
1449 ported:
1450 pathName mark gravity markName ?direction?
1452 If direction is not specified, returns left or right to
1453 indicate which of its adjacent characters markName is
1454 attached to. If direction is specified, it must be left
1455 or right; the gravity of markName is set to the given
1456 value.
1457 pathName mark names
1459 Returns a list whose elements are the names of all the
1460 marks that are currently set.
1461 pathName mark next index
1463 Returns the name of the next mark at or after index. If
1464 index is specified in numerical form, then the search for
1465 the next mark begins at that index. If index is the name
1466 of a mark, then the search for the next mark begins imme‐
1467 diately after that mark. This can still return a mark at
1468 the same position if there are multiple marks at the same
1469 index. These semantics mean that the mark next operation
1470 can be used to step through all the marks in a text wid‐
1471 get in the same order as the mark information returned by
1472 the pathName dump operation. If a mark has been set to
1473 the special end index, then it appears to be after end
1474 with respect to the pathName mark next operation. An
1475 empty string is returned if there are no marks after
1476 index.
1477 pathName mark previous index
1479 Returns the name of the mark at or before index. If index
1480 is specified in numerical form, then the search for the
1481 previous mark begins with the character just before that
1482 index. If index is the name of a mark, then the search
1483 for the next mark begins immediately before that mark.
1484 This can still return a mark at the same position if
1485 there are multiple marks at the same index. These seman‐
1486 tics mean that the pathName mark previous operation can
1487 be used to step through all the marks in a text widget in
1488 the reverse order as the mark information returned by the
1489 pathName dump operation. An empty string is returned if
1490 there are no marks before index.
1491 pathName mark set markName index
1493 Sets the mark named markName to a position just before
1494 the character at index. If markName already exists, it is
1495 moved from its old position; if it does not exist, a new
1496 mark is created. This command returns an empty string.
1497 pathName mark unset markName ?markName markName ...?
1499 Remove the mark corresponding to each of the markName
1500 arguments. The removed marks will not be usable in
1501 indices and will not be returned by future calls to
1502 “pathName mark names”. This command returns an empty
1503 string.
1504 pathName peer option args
1506 This command is used to create and query widget peers. It has
1507 two forms, depending on option:
1508 pathName peer create newPathName ?options?
1510 Creates a peer text widget with the given newPathName,
1511 and any optional standard configuration options (as for
1512 the text command). By default the peer will have the same
1513 start and end line as the parent widget, but these can be
1514 overridden with the standard configuration options.
1515 pathName peer names
1517 Returns a list of peers of this widget (this does not
1518 include the widget itself). The order within this list is
1519 undefined.
1520 pathName pendingsync
1522 Returns 1 if the line heights calculations are not up-to-date, 0
1523 otherwise.
1524 pathName replace index1 index2 chars ?tagList chars tagList ...?
1526 Replaces the range of characters between index1 and index2 with
1527 the given characters and tags. See the section on pathName
1528 insert for an explanation of the handling of the tagList...
1529 arguments, and the section on pathName delete for an explanation
1530 of the handling of the indices. If index2 corresponds to an
1531 index earlier in the text than index1, an error will be gener‐
1532 ated.
1533 The deletion and insertion are arranged so that no unnecessary
1535 scrolling of the window or movement of insertion cursor occurs.
1536 In addition the undo/redo stack are correctly modified, if undo
1537 operations are active in the text widget. The command returns an
1538 empty string.
1539 pathName scan option args
1541 This command is used to implement scanning on texts. It has two
1542 forms, depending on option:
1543 pathName scan mark x y
1545 Records x and y and the current view in the text window,
1546 for use in conjunction with later pathName scan dragto
1547 commands. Typically this command is associated with a
1548 mouse button press in the widget. It returns an empty
1549 string.
1550 pathName scan dragto x y
1552 This command computes the difference between its x and y
1553 arguments and the x and y arguments to the last pathName
1554 scan mark command for the widget. It then adjusts the
1555 view by 10 times the difference in coordinates. This com‐
1556 mand is typically associated with mouse motion events in
1557 the widget, to produce the effect of dragging the text at
1558 high speed through the window. The return value is an
1559 empty string.
1560 pathName search ?switches? pattern index ?stopIndex?
1562 Searches the text in pathName starting at index for a range of
1563 characters that matches pattern. If a match is found, the index
1564 of the first character in the match is returned as result; oth‐
1565 erwise an empty string is returned. One or more of the following
1566 switches (or abbreviations thereof) may be specified to control
1567 the search:
1568 -forwards
1570 The search will proceed forward through the text, finding
1571 the first matching range starting at or after the posi‐
1572 tion given by index. This is the default.
1573 -backwards
1575 The search will proceed backward through the text, find‐
1576 ing the matching range closest to index whose first char‐
1577 acter is before index (it is not allowed to be at index).
1578 Note that, for a variety of reasons, backwards searches
1579 can be substantially slower than forwards searches (par‐
1580 ticularly when using -regexp), so it is recommended that
1581 performance-critical code use forward searches.
1582 -exact Use exact matching: the characters in the matching range
1584 must be identical to those in pattern. This is the
1585 default.
1586 -regexp
1588 Treat pattern as a regular expression and match it
1589 against the text using the rules for regular expressions
1590 (see the regexp command and the re_syntax page for
1591 details). The default matching automatically passes both
1592 the -lineanchor and -linestop options to the regexp
1593 engine (unless -nolinestop is used), so that ^$ match
1594 beginning and end of line, and ., [^ sequences will never
1595 match the newline character \n.
1596 -nolinestop
1598 This allows . and [^ sequences to match the newline char‐
1599 acter \n, which they will otherwise not do (see the reg‐
1600 exp command for details). This option is only meaningful
1601 if -regexp is also given, and an error will be thrown
1602 otherwise. For example, to match the entire text, use
1603 “pathName search -nolinestop -regexp ".*" 1.0”.
1604 -nocase
1606 Ignore case differences between the pattern and the text.
1607 -count varName
1609 The argument following -count gives the name of a vari‐
1610 able; if a match is found, the number of index positions
1611 between beginning and end of the matching range will be
1612 stored in the variable. If there are no embedded images
1613 or windows in the matching range (and there are no elided
1614 characters if -elide is not given), this is equivalent to
1615 the number of characters matched. In either case, the
1616 range matchIdx to matchIdx + $count chars will return the
1617 entire matched text.
1618 -all Find all matches in the given range and return a list of
1620 the indices of the first character of each match. If a
1621 -count varName switch is given, then varName is also set
1622 to a list containing one element for each successful
1623 match. Note that, even for exact searches, the elements
1624 of this list may be different, if there are embedded
1625 images, windows or hidden text. Searches with -all
1626 behave very similarly to the Tcl command regexp -all, in
1627 that overlapping matches are not normally returned. For
1628 example, applying an -all search of the pattern “\w+”
1629 against “hello there” will just match twice, once for
1630 each word, and matching “Z[a-z]+Z” against “ZooZooZoo”
1631 will just match once.
1632 -overlap
1634 When performing -all searches, the normal behaviour is
1635 that matches which overlap an already-found match will
1636 not be returned. This switch changes that behaviour so
1637 that all matches which are not totally enclosed within
1638 another match are returned. For example, applying an
1639 -overlap search of the pattern “\w+” against “hello
1640 there” will just match twice (i.e. no different to just
1641 -all), but matching “Z[a-z]+Z” against “ZooZooZoo” will
1642 now match twice. An error will be thrown if this switch
1643 is used without -all.
1644 -strictlimits
1646 When performing any search, the normal behaviour is that
1647 the start and stop limits are checked with respect to the
1648 start of the matching text. With the -strictlimits flag,
1649 the entire matching range must lie inside the start and
1650 stop limits specified for the match to be valid.
1651 -elide Find elided (hidden) text as well. By default only dis‐
1653 played text is searched.
1654 -- This switch has no effect except to terminate the list of
1656 switches: the next argument will be treated as pattern
1657 even if it starts with -.
1658 The matching range may be within a single line of text, or run
1660 across multiple lines (if parts of the pattern can match a new-
1661 line). For regular expression matching one can use the various
1662 newline-matching features such as $ to match the end of a line,
1663 ^ to match the beginning of a line, and to control whether . is
1664 allowed to match a new-line. If stopIndex is specified, the
1665 search stops at that index: for forward searches, no match at or
1666 after stopIndex will be considered; for backward searches, no
1667 match earlier in the text than stopIndex will be considered. If
1668 stopIndex is omitted, the entire text will be searched: when the
1669 beginning or end of the text is reached, the search continues at
1670 the other end until the starting location is reached again; if
1671 stopIndex is specified, no wrap-around will occur. This means
1672 that, for example, if the search is -forwards but stopIndex is
1673 earlier in the text than startIndex, nothing will ever be found.
1674 See KNOWN BUGS below for a number of minor limitations of the
1675 pathName search command.
1676 pathName see index
1678 Adjusts the view in the window so that the character given by
1679 index is completely visible. If index is already visible then
1680 the command does nothing. If index is a short distance out of
1681 view, the command adjusts the view just enough to make index
1682 visible at the edge of the window. If index is far out of view,
1683 then the command centers index in the window.
1684 pathName sync ?-command command?
1686 Controls the synchronization of the view of the text widget.
1687 pathName sync
1689 Immediately brings the line metrics up-to-date by forcing
1690 computation of any outdated line heights. The command
1691 returns immediately if there is no such outdated line
1692 heights, otherwise it returns only at the end of the com‐
1693 putation. The command returns an empty string.
1694 pathName sync -command command
1696 Schedules command to be executed (by the event loop)
1697 exactly once as soon as all line heights are up-to-date.
1698 If there are no pending line metrics calculations, the
1699 scheduling is immediate. The command returns the empty
1700 string. bgerror is called on command failure.
1701 pathName tag option ?arg arg ...?
1703 This command is used to manipulate tags. The exact behavior of
1704 the command depends on the option argument that follows the tag
1705 argument. The following forms of the command are currently sup‐
1706 ported:
1707 pathName tag add tagName index1 ?index2 index1 index2 ...?
1709 Associate the tag tagName with all of the characters
1710 starting with index1 and ending just before index2 (the
1711 character at index2 is not tagged). A single command may
1712 contain any number of index1-index2 pairs. If the last
1713 index2 is omitted then the single character at index1 is
1714 tagged. If there are no characters in the specified range
1715 (e.g. index1 is past the end of the file or index2 is
1716 less than or equal to index1) then the command has no
1717 effect.
1718 pathName tag bind tagName ?sequence? ?script?
1720 This command associates script with the tag given by tag‐
1721 Name. Whenever the event sequence given by sequence
1722 occurs for a character that has been tagged with tagName,
1723 the script will be invoked. This widget command is simi‐
1724 lar to the bind command except that it operates on char‐
1725 acters in a text rather than entire widgets. See the bind
1726 manual entry for complete details on the syntax of
1727 sequence and the substitutions performed on script before
1728 invoking it. If all arguments are specified then a new
1729 binding is created, replacing any existing binding for
1730 the same sequence and tagName (if the first character of
1731 script is “+” then script augments an existing binding
1732 rather than replacing it). In this case the return value
1733 is an empty string. If script is omitted then the command
1734 returns the script associated with tagName and sequence
1735 (an error occurs if there is no such binding). If both
1736 script and sequence are omitted then the command returns
1737 a list of all the sequences for which bindings have been
1738 defined for tagName.
1739 The only events for which bindings may be specified are
1741 those related to the mouse and keyboard (such as Enter,
1742 Leave, ButtonPress, Motion, and KeyPress) or virtual
1743 events. Event bindings for a text widget use the current
1744 mark described under MARKS above. An Enter event triggers
1745 for a tag when the tag first becomes present on the cur‐
1746 rent character, and a Leave event triggers for a tag when
1747 it ceases to be present on the current character. Enter
1748 and Leave events can happen either because the current
1749 mark moved or because the character at that position
1750 changed. Note that these events are different than Enter
1751 and Leave events for windows. Mouse and keyboard events
1752 are directed to the current character. If a virtual event
1753 is used in a binding, that binding can trigger only if
1754 the virtual event is defined by an underlying mouse-
1755 related or keyboard-related event.
1756 It is possible for the current character to have multiple
1758 tags, and for each of them to have a binding for a par‐
1759 ticular event sequence. When this occurs, one binding is
1760 invoked for each tag, in order from lowest-priority to
1761 highest priority. If there are multiple matching bindings
1762 for a single tag, then the most specific binding is cho‐
1763 sen (see the manual entry for the bind command for
1764 details). continue and break commands within binding
1765 scripts are processed in the same way as for bindings
1766 created with the bind command.
1767 If bindings are created for the widget as a whole using
1769 the bind command, then those bindings will supplement the
1770 tag bindings. The tag bindings will be invoked first,
1771 followed by bindings for the window as a whole.
1772 pathName tag cget tagName option
1774 This command returns the current value of the option
1775 named option associated with the tag given by tagName.
1776 Option may have any of the values accepted by the path‐
1777 Name tag configure widget command.
1778 pathName tag configure tagName ?option? ?value? ?option value
1780 ...?
1781 This command is similar to the pathName configure widget
1782 command except that it modifies options associated with
1783 the tag given by tagName instead of modifying options for
1784 the overall text widget. If no option is specified, the
1785 command returns a list describing all of the available
1786 options for tagName (see Tk_ConfigureInfo for information
1787 on the format of this list). If option is specified with
1788 no value, then the command returns a list describing the
1789 one named option (this list will be identical to the cor‐
1790 responding sublist of the value returned if no option is
1791 specified). If one or more option-value pairs are speci‐
1792 fied, then the command modifies the given option(s) to
1793 have the given value(s) in tagName; in this case the com‐
1794 mand returns an empty string. See TAGS above for details
1795 on the options available for tags.
1796 pathName tag delete tagName ?tagName ...?
1798 Deletes all tag information for each of the tagName argu‐
1799 ments. The command removes the tags from all characters
1800 in the file and also deletes any other information asso‐
1801 ciated with the tags, such as bindings and display infor‐
1802 mation. The command returns an empty string.
1803 pathName tag lower tagName ?belowThis?
1805 Changes the priority of tag tagName so that it is just
1806 lower in priority than the tag whose name is belowThis.
1807 If belowThis is omitted, then tagName's priority is
1808 changed to make it lowest priority of all tags.
1809 pathName tag names ?index?
1811 Returns a list whose elements are the names of all the
1812 tags that are active at the character position given by
1813 index. If index is omitted, then the return value will
1814 describe all of the tags that exist for the text (this
1815 includes all tags that have been named in a “pathName
1816 tag” widget command but have not been deleted by a “path‐
1817 Name tag delete” widget command, even if no characters
1818 are currently marked with the tag). The list will be
1819 sorted in order from lowest priority to highest priority.
1820 pathName tag nextrange tagName index1 ?index2?
1822 This command searches the text for a range of characters
1823 tagged with tagName where the first character of the
1824 range is no earlier than the character at index1 and no
1825 later than the character just before index2 (a range
1826 starting at index2 will not be considered). If several
1827 matching ranges exist, the first one is chosen. The com‐
1828 mand's return value is a list containing two elements,
1829 which are the index of the first character of the range
1830 and the index of the character just after the last one in
1831 the range. If no matching range is found then the return
1832 value is an empty string. If index2 is not given then it
1833 defaults to the end of the text.
1834 pathName tag prevrange tagName index1 ?index2?
1836 This command searches the text for a range of characters
1837 tagged with tagName where the first character of the
1838 range is before the character at index1 and no earlier
1839 than the character at index2 (a range starting at index2
1840 will be considered). If several matching ranges exist,
1841 the one closest to index1 is chosen. The command's return
1842 value is a list containing two elements, which are the
1843 index of the first character of the range and the index
1844 of the character just after the last one in the range. If
1845 no matching range is found then the return value is an
1846 empty string. If index2 is not given then it defaults to
1847 the beginning of the text.
1848 pathName tag raise tagName ?aboveThis?
1850 Changes the priority of tag tagName so that it is just
1851 higher in priority than the tag whose name is aboveThis.
1852 If aboveThis is omitted, then tagName's priority is
1853 changed to make it highest priority of all tags.
1854 pathName tag ranges tagName
1856 Returns a list describing all of the ranges of text that
1857 have been tagged with tagName. The first two elements of
1858 the list describe the first tagged range in the text, the
1859 next two elements describe the second range, and so on.
1860 The first element of each pair contains the index of the
1861 first character of the range, and the second element of
1862 the pair contains the index of the character just after
1863 the last one in the range. If there are no characters
1864 tagged with tag then an empty string is returned.
1865 pathName tag remove tagName index1 ?index2 index1 index2 ...?
1867 Remove the tag tagName from all of the characters start‐
1868 ing at index1 and ending just before index2 (the charac‐
1869 ter at index2 is not affected). A single command may con‐
1870 tain any number of index1-index2 pairs. If the last
1871 index2 is omitted then the tag is removed from the single
1872 character at index1. If there are no characters in the
1873 specified range (e.g. index1 is past the end of the file
1874 or index2 is less than or equal to index1) then the com‐
1875 mand has no effect. This command returns an empty string.
1876 pathName window option ?arg arg ...?
1878 This command is used to manipulate embedded windows. The behav‐
1879 ior of the command depends on the option argument that follows
1880 the window argument. The following forms of the command are cur‐
1881 rently supported:
1882 pathName window cget index option
1884 Returns the value of a configuration option for an embed‐
1885 ded window. Index identifies the embedded window, and
1886 option specifies a particular configuration option, which
1887 must be one of the ones listed in the section EMBEDDED
1888 WINDOWS.
1889 pathName window configure index ?option value ...?
1891 Query or modify the configuration options for an embedded
1892 window. If no option is specified, returns a list
1893 describing all of the available options for the embedded
1894 window at index (see Tk_ConfigureInfo for information on
1895 the format of this list). If option is specified with no
1896 value, then the command returns a list describing the one
1897 named option (this list will be identical to the corre‐
1898 sponding sublist of the value returned if no option is
1899 specified). If one or more option-value pairs are speci‐
1900 fied, then the command modifies the given option(s) to
1901 have the given value(s); in this case the command returns
1902 an empty string. See EMBEDDED WINDOWS for information on
1903 the options that are supported.
1904 pathName window create index ?option value ...?
1906 This command creates a new window annotation, which will
1907 appear in the text at the position given by index. Any
1908 number of option-value pairs may be specified to config‐
1909 ure the annotation. See EMBEDDED WINDOWS for information
1910 on the options that are supported. Returns an empty
1911 string.
1912 pathName window names
1914 Returns a list whose elements are the names of all win‐
1915 dows currently embedded in window.
1916 pathName xview option args
1918 This command is used to query and change the horizontal position
1919 of the text in the widget's window. It can take any of the fol‐
1920 lowing forms:
1921 pathName xview
1923 Returns a list containing two elements. Each element is a
1924 real fraction between 0 and 1; together they describe the
1925 portion of the document's horizontal span that is visible
1926 in the window. For example, if the first element is .2
1927 and the second element is .6, 20% of the text is off-
1928 screen to the left, the middle 40% is visible in the win‐
1929 dow, and 40% of the text is off-screen to the right. The
1930 fractions refer only to the lines that are actually visi‐
1931 ble in the window: if the lines in the window are all
1932 very short, so that they are entirely visible, the
1933 returned fractions will be 0 and 1, even if there are
1934 other lines in the text that are much wider than the win‐
1935 dow. These are the same values passed to scrollbars via
1936 the -xscrollcommand option.
1937 pathName xview moveto fraction
1939 Adjusts the view in the window so that fraction of the
1940 horizontal span of the text is off-screen to the left.
1941 Fraction is a fraction between 0 and 1.
1942 pathName xview scroll number what
1944 This command shifts the view in the window left or right
1945 according to number and what. What must be units, pages
1946 or pixels. If what is units or pages then number must be
1947 an integer, otherwise number may be specified in any of
1948 the forms acceptable to Tk_GetPixels, such as “2.0c” or
1949 “1i” (the result is rounded to the nearest integer value.
1950 If no units are given, pixels are assumed). If what is
1951 units, the view adjusts left or right by number average-
1952 width characters on the display; if it is pages then the
1953 view adjusts by number screenfuls; if it is pixels then
1954 the view adjusts by number pixels. If number is negative
1955 then characters farther to the left become visible; if it
1956 is positive then characters farther to the right become
1957 visible.
1958 pathName yview ?args?
1960 This command is used to query and change the vertical position
1961 of the text in the widget's window. It can take any of the fol‐
1962 lowing forms:
1963 pathName yview
1965 Returns a list containing two elements, both of which are
1966 real fractions between 0 and 1. The first element gives
1967 the position of the first visible pixel of the first
1968 character (or image, etc) in the top line in the window,
1969 relative to the text as a whole (0.5 means it is halfway
1970 through the text, for example). The second element gives
1971 the position of the first pixel just after the last visi‐
1972 ble one in the bottom line of the window, relative to the
1973 text as a whole. These are the same values passed to
1974 scrollbars via the -yscrollcommand option.
1975 pathName yview moveto fraction
1977 Adjusts the view in the window so that the pixel given by
1978 fraction appears at the top of the top line of the win‐
1979 dow. Fraction is a fraction between 0 and 1; 0 indicates
1980 the first pixel of the first character in the text, 0.33
1981 indicates the pixel that is one-third the way through the
1982 text; and so on. Values close to 1 will indicate values
1983 close to the last pixel in the text (1 actually refers to
1984 one pixel beyond the last pixel), but in such cases the
1985 widget will never scroll beyond the last pixel, and so a
1986 value of 1 will effectively be rounded back to whatever
1987 fraction ensures the last pixel is at the bottom of the
1988 window, and some other pixel is at the top.
1989 pathName yview scroll number what
1991 This command adjust the view in the window up or down
1992 according to number and what. What must be units, pages
1993 or pixels. If what is units or pages then number must be
1994 an integer, otherwise number may be specified in any of
1995 the forms acceptable to Tk_GetPixels, such as “2.0c” or
1996 “1i” (the result is rounded to the nearest integer value.
1997 If no units are given, pixels are assumed). If what is
1998 units, the view adjusts up or down by number lines on the
1999 display; if it is pages then the view adjusts by number
2000 screenfuls; if it is pixels then the view adjusts by num‐
2001 ber pixels. If number is negative then earlier positions
2002 in the text become visible; if it is positive then later
2003 positions in the text become visible.
2004 pathName yview ?-pickplace? index
2006 Changes the view in the widget's window to make index
2007 visible. If the -pickplace option is not specified then
2008 index will appear at the top of the window. If -pickplace
2009 is specified then the widget chooses where index appears
2010 in the window:
2011 [1] If index is already visible somewhere in the win‐
2013 dow then the command does nothing.
2014 [2] If index is only a few lines off-screen above the
2016 window then it will be positioned at the top of
2017 the window.
2018 [3] If index is only a few lines off-screen below the
2020 window then it will be positioned at the bottom of
2021 the window.
2022 [4] Otherwise, index will be centered in the window.
2024 The -pickplace option has been obsoleted by the pathName
2026 see widget command (pathName see handles both x- and y-
2027 motion to make a location visible, whereas the -pickplace
2028 mode only handles motion in y).
2029 pathName yview number
2031 This command makes the first character on the line after
2032 the one given by number visible at the top of the window.
2033 Number must be an integer. This command used to be used
2034 for scrolling, but now it is obsolete.
2035
2037 Tk automatically creates class bindings for texts that give them the
2038 following default behavior. In the descriptions below, “word” is depen‐
2039 dent on the value of the tcl_wordchars variable. See tclvars(n).
2040 [1] Clicking mouse button 1 positions the insertion cursor just
2042 before the character underneath the mouse cursor, sets the input
2043 focus to this widget, and clears any selection in the widget.
2044 Dragging with mouse button 1 strokes out a selection between the
2045 insertion cursor and the character under the mouse.
2046 [2] Double-clicking with mouse button 1 selects the word under the
2048 mouse and positions the insertion cursor at the start of the
2049 word. Dragging after a double click will stroke out a selection
2050 consisting of whole words.
2051 [3] Triple-clicking with mouse button 1 selects the line under the
2053 mouse and positions the insertion cursor at the start of the
2054 line. Dragging after a triple click will stroke out a selection
2055 consisting of whole lines.
2056 [4] The ends of the selection can be adjusted by dragging with mouse
2058 button 1 while the Shift key is down; this will adjust the end
2059 of the selection that was nearest to the mouse cursor when but‐
2060 ton 1 was pressed. If the button is double-clicked before drag‐
2061 ging then the selection will be adjusted in units of whole
2062 words; if it is triple-clicked then the selection will be
2063 adjusted in units of whole lines.
2064 [5] Clicking mouse button 1 with the Control key down will reposi‐
2066 tion the insertion cursor without affecting the selection.
2067 [6] If any normal printing characters are typed, they are inserted
2069 at the point of the insertion cursor.
2070 [7] The view in the widget can be adjusted by dragging with mouse
2072 button 2. If mouse button 2 is clicked without moving the mouse,
2073 the selection is copied into the text at the position of the
2074 mouse cursor. The Insert key also inserts the selection, but at
2075 the position of the insertion cursor.
2076 [8] If the mouse is dragged out of the widget while button 1 is
2078 pressed, the entry will automatically scroll to make more text
2079 visible (if there is more text off-screen on the side where the
2080 mouse left the window).
2081 [9] The Left and Right keys move the insertion cursor one character
2083 to the left or right; they also clear any selection in the text.
2084 If Left or Right is typed with the Shift key down, then the
2085 insertion cursor moves and the selection is extended to include
2086 the new character. Control-Left and Control-Right move the
2087 insertion cursor by words, and Control-Shift-Left and Control-
2088 Shift-Right move the insertion cursor by words and also extend
2089 the selection. Control-b and Control-f behave the same as Left
2090 and Right, respectively. Meta-b and Meta-f behave the same as
2091 Control-Left and Control-Right, respectively.
2092 [10] The Up and Down keys move the insertion cursor one line up or
2094 down and clear any selection in the text. If Up or Right is
2095 typed with the Shift key down, then the insertion cursor moves
2096 and the selection is extended to include the new character. Con‐
2097 trol-Up and Control-Down move the insertion cursor by paragraphs
2098 (groups of lines separated by blank lines), and Control-Shift-Up
2099 and Control-Shift-Down move the insertion cursor by paragraphs
2100 and also extend the selection. Control-p and Control-n behave
2101 the same as Up and Down, respectively.
2102 [11] The Next and Prior keys move the insertion cursor forward or
2104 backwards by one screenful and clear any selection in the text.
2105 If the Shift key is held down while Next or Prior is typed, then
2106 the selection is extended to include the new character.
2107 [12] Control-Next and Control-Prior scroll the view right or left by
2109 one page without moving the insertion cursor or affecting the
2110 selection.
2111 [13] Home and Control-a move the insertion cursor to the beginning of
2113 its display line and clear any selection in the widget. Shift-
2114 Home moves the insertion cursor to the beginning of the display
2115 line and also extends the selection to that point.
2116 [14] End and Control-e move the insertion cursor to the end of the
2118 display line and clear any selection in the widget. Shift-End
2119 moves the cursor to the end of the display line and extends the
2120 selection to that point.
2121 [15] Control-Home and Meta-< move the insertion cursor to the begin‐
2123 ning of the text and clear any selection in the widget. Control-
2124 Shift-Home moves the insertion cursor to the beginning of the
2125 text and also extends the selection to that point.
2126 [16] Control-End and Meta-> move the insertion cursor to the end of
2128 the text and clear any selection in the widget. Control-Shift-
2129 End moves the cursor to the end of the text and extends the
2130 selection to that point.
2131 [17] The Select key and Control-Space set the selection anchor to the
2133 position of the insertion cursor. They do not affect the current
2134 selection. Shift-Select and Control-Shift-Space adjust the
2135 selection to the current position of the insertion cursor,
2136 selecting from the anchor to the insertion cursor if there was
2137 not any selection previously.
2138 [18] Control-/ selects the entire contents of the widget.
2140 [19] Control-\ clears any selection in the widget.
2142 [20] The F16 key (labelled Copy on many Sun workstations) or Meta-w
2144 copies the selection in the widget to the clipboard, if there is
2145 a selection. This action is carried out by the command
2146 tk_textCopy.
2147 [21] The F20 key (labelled Cut on many Sun workstations) or Control-w
2149 copies the selection in the widget to the clipboard and deletes
2150 the selection. This action is carried out by the command
2151 tk_textCut. If there is no selection in the widget then these
2152 keys have no effect.
2153 [22] The F18 key (labelled Paste on many Sun workstations) or Con‐
2155 trol-y inserts the contents of the clipboard at the position of
2156 the insertion cursor. This action is carried out by the command
2157 tk_textPaste.
2158 [23] The Delete key deletes the selection, if there is one in the
2160 widget. If there is no selection, it deletes the character to
2161 the right of the insertion cursor.
2162 [24] Backspace and Control-h delete the selection, if there is one in
2164 the widget. If there is no selection, they delete the character
2165 to the left of the insertion cursor.
2166 [25] Control-d deletes the character to the right of the insertion
2168 cursor.
2169 [26] Meta-d deletes the word to the right of the insertion cursor.
2171 [27] Control-k deletes from the insertion cursor to the end of its
2173 line; if the insertion cursor is already at the end of a line,
2174 then Control-k deletes the newline character.
2175 [28] Control-o opens a new line by inserting a newline character in
2177 front of the insertion cursor without moving the insertion cur‐
2178 sor.
2179 [29] Meta-backspace and Meta-Delete delete the word to the left of
2181 the insertion cursor.
2182 [30] Control-x deletes whatever is selected in the text widget after
2184 copying it to the clipboard.
2185 [31] Control-t reverses the order of the two characters to the right
2187 of the insertion cursor.
2188 [32] Control-z undoes the last edit action if the -undo option is
2190 true. Does nothing otherwise.
2191 [33] Control-Z (or Control-y on Windows) reapplies the last undone
2193 edit action if the -undo option is true. Does nothing otherwise.
2194 If the widget is disabled using the -state option, then its view can
2196 still be adjusted and text can still be selected, but no insertion cur‐
2197 sor will be displayed and no text modifications will take place.
2198 The behavior of texts can be changed by defining new bindings for indi‐
2200 vidual widgets or by redefining the class bindings.
2201
2203 ISSUES CONCERNING CHARS AND INDICES
2204 Before Tk 8.5, the widget used the string “chars” to refer to index
2205 positions (which included characters, embedded windows and embedded
2206 images). As of Tk 8.5 the text widget deals separately and correctly
2207 with “chars” and “indices”. For backwards compatibility, however, the
2208 index modifiers “+N chars” and “-N chars” continue to refer to indices.
2209 One must use any of the full forms “+N any chars” or “-N any chars”
2210 etc. to refer to actual character indices. This confusion may be fixed
2211 in a future release by making the widget correctly interpret “+N chars”
2212 as a synonym for “+N any chars”.
2213 PERFORMANCE ISSUES
2215 Text widgets should run efficiently under a variety of conditions. The
2216 text widget uses about 2-3 bytes of main memory for each byte of text,
2217 so texts containing a megabyte or more should be practical on most
2218 workstations. Text is represented internally with a modified B-tree
2219 structure that makes operations relatively efficient even with large
2220 texts. Tags are included in the B-tree structure in a way that allows
2221 tags to span large ranges or have many disjoint smaller ranges without
2222 loss of efficiency. Marks are also implemented in a way that allows
2223 large numbers of marks. In most cases it is fine to have large numbers
2224 of unique tags, or a tag that has many distinct ranges.
2225 One performance problem can arise if you have hundreds or thousands of
2227 different tags that all have the following characteristics: the first
2228 and last ranges of each tag are near the beginning and end of the text,
2229 respectively, or a single tag range covers most of the text widget. The
2230 cost of adding and deleting tags like this is proportional to the num‐
2231 ber of other tags with the same properties. In contrast, there is no
2232 problem with having thousands of distinct tags if their overall ranges
2233 are localized and spread uniformly throughout the text.
2234 Very long text lines can be expensive, especially if they have many
2236 marks and tags within them.
2237 The display line with the insert cursor is redrawn each time the cursor
2239 blinks, which causes a steady stream of graphics traffic. Set the
2240 -insertofftime attribute to 0 avoid this.
2241 KNOWN BUGS
2243 The pathName search -regexp sub-command attempts to perform sophisti‐
2244 cated regexp matching across multiple lines in an efficient fashion
2245 (since Tk 8.5), examining each line individually, and then in small
2246 groups of lines, whether searching forwards or backwards. Under certain
2247 conditions the search result might differ from that obtained by apply‐
2248 ing the same regexp to the entire text from the widget in one go. For
2249 example, when searching with a greedy regexp, the widget will continue
2250 to attempt to add extra lines to the match as long as one of two condi‐
2251 tions are true: either Tcl's regexp library returns a code to indicate
2252 a longer match is possible (but there are known bugs in Tcl which mean
2253 this code is not always correctly returned); or if each extra line
2254 added results in at least a partial match with the pattern. This means
2255 in the case where the first extra line added results in no match and
2256 Tcl's regexp system returns the incorrect code and adding a second
2257 extra line would actually match, the text widget will return the wrong
2258 result. In practice this is a rare problem, but it can occur, for exam‐
2259 ple:
2260 pack [text .t]
2261 .t insert 1.0 "aaaa\nbbbb\ncccc\nbbbb\naaaa\n"
2262 .t search -regexp -- {(a+|b+\nc+\nb+)+\na+} 1.0
2263 will not find a match when one exists of 19 characters starting from
2264 the first “b”.
2265 Whenever one possible match is fully enclosed in another, the search
2267 command will attempt to ensure only the larger match is returned. When
2268 performing backwards regexp searches it is possible that Tcl will not
2269 always achieve this, in the case where a match is preceded by one or
2270 more short, non-overlapping matches, all of which are preceded by a
2271 large match which actually encompasses all of them. The search algo‐
2272 rithm used by the widget does not look back arbitrarily far for a pos‐
2273 sible match which might cover large portions of the widget. For exam‐
2274 ple:
2275 pack [text .t]
2276 .t insert 1.0 "aaaa\nbbbb\nbbbb\nbbbb\nbbbb\n"
2277 .t search -regexp -backward -- {b+\n|a+\n(b+\n)+} end
2278 matches at “5.0” when a true greedy match would match at “1.0”. Simi‐
2279 larly if we add -all to this case, it matches at all of “5.0”, “4.0”,
2280 “3.0” and “1.0”, when really it should only match at “1.0” since that
2281 match encloses all the others.
2282
2284 entry(n), scrollbar(n)
2285
2287 text, widget, tkvars
2288Tk 8.5 text(n)