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 in‐
45 sertion 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 un‐
52 derlying textual data store that should be just after the last
53 line contained in the widget. This allows a text widget to re‐
54 flect only a portion of a larger piece of text. Instead of an
55 integer, the empty string can be provided to this configuration
56 option, which will configure the widget to end at the very last
57 line in the textual data store.
58 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 de‐
156 fault; it causes the text following the tab character to be po‐
157 sitioned with its left edge at the tab position. Right means
158 that the right edge of the text following the tab character is
159 positioned at the tab position, and center means that the text
160 is centered at the tab position. Numeric means that the decimal
161 point in the text is positioned at the tab position; if there is
162 no decimal point then the least significant digit of the number
163 is positioned just to the left of the tab position; if there is
164 no number in the text then the text is right-justified at the
165 tab position. For example, “-tabs {2c left 4c 6c center}” cre‐
166 ates three tab stops at two-centimeter intervals; the first two
167 use left justification and the third uses center justification.
168 If the list of tab stops does not have enough elements to cover
170 all of the tabs in a text line, then Tk extrapolates new tab
171 stops using the spacing and alignment from the last tab stop in
172 the list. Tab distances must be strictly positive, and must al‐
173 ways increase from one tab stop to the next (if not, an error is
174 thrown). The value of the -tabs option may be overridden by
175 -tabs options in tags.
176 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 ac‐
207 tive 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; ex‐
226 tra characters that do not fit on the screen are not displayed.
227 In the other modes each line of text will be broken up into sev‐
228 eral screen lines if necessary to keep all the characters visi‐
229 ble. In char mode a screen line break may occur after any char‐
230 acter; in word mode a line break will only be made at word
231 boundaries.
232______________________________________________________________________________
233
235 The text command creates a new window (given by the pathName argument)
236 and makes it into a text widget. Additional options, described above,
237 may be specified on the command line or in the option database to con‐
238 figure aspects of the text such as its default background color and re‐
239 lief. The text command returns the path name of the new window.
240 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 de‐
253 tails.
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 em‐
315 bedded 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 em‐
319 bedded 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 in‐
332 dex to the last index in the text. Spaces on either side of
333 count are optional. If the display submodifier is given, elided
334 characters are skipped over without being counted. If any is
335 given, then all characters are counted. For historical reasons,
336 if neither modifier is given then the count actually takes place
337 in units of index positions (see INDICES for details). This be‐
338 haviour may be changed in a future major release, so if you need
339 an index count, you are encouraged to use indices instead wher‐
340 ever possible.
341 - count ?submodifier? chars
343 Adjust the index backward by count characters, moving to earlier
344 lines in the text if necessary. If there are fewer than count
345 characters in the text before the current index, then set the
346 index to the first index in the text (1.0). Spaces on either
347 side of count are optional. If the display submodifier is given,
348 elided characters are skipped over without being counted. If any
349 is given, then all characters are counted. For historical rea‐
350 sons, if neither modifier is given then the count actually takes
351 place in units of index positions (see INDICES for details).
352 This behavior may be changed in a future major release, so if
353 you need an index count, you are encouraged to use indices in‐
354 stead wherever possible.
355 + count ?submodifier? indices
357 Adjust the index forward by count index positions, moving to
358 later lines in the text if necessary. If there are fewer than
359 count index positions in the text after the current index, then
360 set the index to the last index position in the text. Spaces on
361 either side of count are optional. Note that an index position
362 is either a single character or a single embedded image or em‐
363 bedded window. If the display submodifier is given, elided in‐
364 dices are skipped over without being counted. If any is given,
365 then all indices are counted; this is also the default behaviour
366 if no modifier is given.
367 - 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 op‐
387 tional. If the display submodifier is given, then each visual
388 display line is counted separately. Otherwise, if any (or no
389 modifier) is given, then each logical line (no matter how many
390 times it is visually wrapped) counts just once. If the relevant
391 lines are not wrapped, then these two methods of counting are
392 equivalent.
393 - 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 in‐
430 dex refers to the last character of the text then it is not mod‐
431 ified. If the display submodifier is given, this only examines
432 non-elided characters, otherwise all characters (elided or not)
433 are examined.
434 If more than one modifier is present then they are applied in left-to-
436 right order. For example, the index “end - 1 chars” refers to the next-
437 to-last character in the text and “insert wordstart - 1 c” refers to
438 the character just before the first one in the word containing the in‐
439 sertion cursor. Modifiers are applied one by one in this left to right
440 order, and after each step the resulting index is constrained to be a
441 valid index in the text widget. So, for example, the index “1.0 -1c
442 +1c” refers to the index “2.0”.
443 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 in‐
455 dices. There may be any number of tags associated with characters in a
456 text. Each tag may refer to a single character, a range of characters,
457 or several ranges of characters. An individual character may have any
458 number of tags associated with it.
459 A priority order is defined among tags, and this order is used in im‐
461 plementing some of the tag-related functions described below. When a
462 tag is defined (by associating it with characters or setting its dis‐
463 play options or binding commands to it), it is given a priority higher
464 than any existing tag. The priority order of tags may be redefined us‐
465 ing the “pathName tag raise” and “pathName tag lower” widget commands.
466 Tags serve three purposes in text widgets. First, they control the way
468 information is displayed on the screen. By default, characters are dis‐
469 played as determined by the -background, -font, and -foreground options
470 for the text widget. However, display options may be associated with
471 individual tags using the “pathName tag configure” widget command. If a
472 character has been tagged, then the display options associated with the
473 tag override the default display style. The following options are cur‐
474 rently supported for tags:
475 -background color
477 Color specifies the background color to use for characters asso‐
478 ciated with the tag. It may have any of the forms accepted by
479 Tk_GetColor.
480 -bgstipple bitmap
482 Bitmap specifies a bitmap that is used as a stipple pattern for
483 the background. It may have any of the forms accepted by Tk_Get‐
484 Bitmap. If bitmap has not been specified, or if it is specified
485 as an empty string, then a solid fill will be used for the back‐
486 ground.
487 -borderwidth pixels
489 Pixels specifies the width of a border to draw around the tag
490 using any of the forms accepted by Tk_GetPixels. This option
491 should be used in conjunction with the -relief option to provide
492 the desired border.
493 -elide boolean
495 Elide specifies whether the data should be elided. Elided data
496 (characters, images, embedded windows, etc.) is not displayed
497 and takes no space on screen, but further on behaves just as
498 normal data.
499 -fgstipple bitmap
501 Bitmap specifies a bitmap that is used as a stipple pattern when
502 drawing text and other foreground information such as under‐
503 lines. It may have any of the forms accepted by Tk_GetBitmap. If
504 bitmap has not been specified, or if it is specified as an empty
505 string, then a solid fill will be used.
506 -font fontName
508 FontName is the name of a font to use for drawing characters. It
509 may have any of the forms accepted by Tk_GetFont.
510 -foreground color
512 Color specifies the color to use when drawing text and other
513 foreground information such as underlines. It may have any of
514 the forms accepted by Tk_GetColor.
515 -justify justify
517 If the first non-elided character of a display line has a tag
518 for which this option has been specified, then justify deter‐
519 mines how to justify the line. It must be one of left, right, or
520 center. If a line wraps, then the justification for each line on
521 the display is determined by the first non-elided character of
522 that display line.
523 -lmargin1 pixels
525 If the first non-elided character of a text line has a tag for
526 which this option has been specified, then pixels specifies how
527 much the line should be indented from the left edge of the win‐
528 dow. Pixels may have any of the standard forms for screen dis‐
529 tances. If a line of text wraps, this option only applies to the
530 first line on the display; the -lmargin2 option controls the in‐
531 dentation for subsequent lines.
532 -lmargin2 pixels
534 If the first non-elided character of a display line has a tag
535 for which this option has been specified, and if the display
536 line is not the first for its text line (i.e., the text line has
537 wrapped), then pixels specifies how much the line should be in‐
538 dented from the left edge of the window. Pixels may have any of
539 the standard forms for screen distances. This option is only
540 used when wrapping is enabled, and it only applies to the second
541 and later display lines for a text line.
542 -lmargincolor color
544 Color specifies the background color to use in regions that do
545 not contain characters because they are indented by -lmargin1 or
546 -lmargin2. It may have any of the forms accepted by Tk_GetColor.
547 If color has not been specified, or if it is specified as an
548 empty string, then the color used is specified by the -back‐
549 ground tag option (or, if this is also unspecified, by the
550 -background widget option).
551 -offset pixels
553 Pixels specifies an amount by which the text's baseline should
554 be offset vertically from the baseline of the overall line, in
555 pixels. For example, a positive offset can be used for super‐
556 scripts and a negative offset can be used for subscripts. Pixels
557 may have any of the standard forms for screen distances.
558 -overstrike boolean
560 Specifies whether or not to draw a horizontal rule through the
561 middle of characters. Boolean may have any of the forms accepted
562 by Tcl_GetBoolean.
563 -overstrikefg color
565 Color specifies the color to use when displaying the overstrike.
566 It may have any of the forms accepted by Tk_GetColor. If color
567 has not been specified, or if it is specified as an empty
568 string, then the color specified by the -foreground tag option
569 is used.
570 -relief relief
572 Relief specifies the relief style to use for drawing the border,
573 in any of the forms accepted by Tk_GetRelief. This option is
574 used in conjunction with the -borderwidth option to enable to
575 the desired border appearance.
576 -rmargin pixels
578 If the first non-elided character of a display line has a tag
579 for which this option has been specified, then pixels specifies
580 how wide a margin to leave between the end of the line and the
581 right edge of the window. Pixels may have any of the standard
582 forms for screen distances. This option is only used when wrap‐
583 ping is enabled. If a text line wraps, the right margin for each
584 line on the display is determined by the first non-elided char‐
585 acter of that display line.
586 -rmargincolor color
588 Color specifies the background color to use in regions that do
589 not contain characters because they are indented by -rmargin. It
590 may have any of the forms accepted by Tk_GetColor. If color has
591 not been specified, or if it is specified as an empty string,
592 then the color used is specified by the -background tag option
593 (or, if this is also unspecified, by the -background widget op‐
594 tion).
595 -selectbackground color
597 Color specifies the background color to use when displaying se‐
598 lected items. It may have any of the forms accepted by Tk_Get‐
599 Color. If color has not been specified, or if it is specified as
600 an empty string, then the color specified by the -background tag
601 option is used.
602 -selectforeground color
604 Color specifies the foreground color to use when displaying se‐
605 lected items. It may have any of the forms accepted by Tk_Get‐
606 Color. If color has not been specified, or if it is specified as
607 an empty string, then the color specified by the -foreground tag
608 option is used.
609 -spacing1 pixels
611 Pixels specifies how much additional space should be left above
612 each text line, using any of the standard forms for screen dis‐
613 tances. If a line wraps, this option only applies to the first
614 line on the display.
615 -spacing2 pixels
617 For lines that wrap, this option specifies how much additional
618 space to leave between the display lines for a single text line.
619 Pixels may have any of the standard forms for screen distances.
620 -spacing3 pixels
622 Pixels specifies how much additional space should be left below
623 each text line, using any of the standard forms for screen dis‐
624 tances. If a line wraps, this option only applies to the last
625 line on the display.
626 -tabs tabList
628 TabList specifies a set of tab stops in the same form as for the
629 -tabs option for the text widget. This option only applies to a
630 display line if it applies to the first non-elided character on
631 that display line. If this option is specified as an empty
632 string, it cancels the option, leaving it unspecified for the
633 tag (the default). If the option is specified as a non-empty
634 string that is an empty list, such as -tags { }, then it re‐
635 quests default 8-character tabs as described for the -tags wid‐
636 get option.
637 -tabstyle style
639 Style specifies either the tabular or wordprocessor style of
640 tabbing to use for the text widget. This option only applies to
641 a display line if it applies to the first non-elided character
642 on that display line. If this option is specified as an empty
643 string, it cancels the option, leaving it unspecified for the
644 tag (the default).
645 -underline boolean
647 Boolean specifies whether or not to draw an underline underneath
648 characters. It may have any of the forms accepted by Tcl_Get‐
649 Boolean.
650 -underlinefg color
652 Color specifies the color to use when displaying the underline.
653 It may have any of the forms accepted by Tk_GetColor. If color
654 has not been specified, or if it is specified as an empty
655 string, then the color specified by the -foreground tag option
656 is used.
657 -wrap mode
659 Mode specifies how to handle lines that are wider than the
660 text's window. This option only applies to a display line if it
661 applies to the first non-elided character on that display line.
662 It has the same legal values as the -wrap option for the text
663 widget: none, char, or word. If this tag option is specified, it
664 overrides the -wrap option for the text widget.
665 If a character has several tags associated with it, and if their dis‐
667 play options conflict, then the options of the highest priority tag are
668 used. If a particular display option has not been specified for a par‐
669 ticular tag, or if it is specified as an empty string, then that option
670 will never be used; the next-highest-priority tag's option will used
671 instead. If no tag specifies a particular display option, then the de‐
672 fault style for the widget will be used.
673 The second purpose for tags is event bindings. You can associate bind‐
675 ings with a tag in much the same way you can associate bindings with a
676 widget class: whenever particular X events occur on characters with the
677 given tag, a given Tcl command will be executed. Tag bindings can be
678 used to give behaviors to ranges of characters; among other things,
679 this allows hypertext-like features to be implemented. For details, see
680 the description of the “pathName tag bind” widget command below. Tag
681 bindings are shared between all peer widgets (including any bindings
682 for the special sel tag).
683 The third use for tags is in managing the selection. See THE SELECTION
685 below. With the exception of the special sel tag, all tags are shared
686 between peer text widgets, and may be manipulated on an equal basis
687 from any such widget. The sel tag exists separately and independently
688 in each peer text widget (but any tag bindings to sel are shared).
689
691 The second form of annotation in text widgets is a mark. Marks are used
692 for remembering particular places in a text. They are something like
693 tags, in that they have names and they refer to places in the file, but
694 a mark is not associated with particular characters. Instead, a mark is
695 associated with the gap between two characters. Only a single position
696 may be associated with a mark at any given time. If the characters
697 around a mark are deleted the mark will still remain; it will just have
698 new neighbor characters. In contrast, if the characters containing a
699 tag are deleted then the tag will no longer have an association with
700 characters in the file. Marks may be manipulated with the “pathName
701 mark” widget command, and their current locations may be determined by
702 using the mark name as an index in widget commands.
703 Each mark also has a “gravity”, which is either left or right. The
705 gravity for a mark specifies what happens to the mark when text is in‐
706 serted at the point of the mark. If a mark has left gravity, then the
707 mark is treated as if it were attached to the character on its left, so
708 the mark will remain to the left of any text inserted at the mark posi‐
709 tion. If the mark has right gravity, new text inserted at the mark po‐
710 sition will appear to the left of the mark (so that the mark remains
711 rightmost). The gravity for a mark defaults to right.
712 The name space for marks is different from that for tags: the same name
714 may be used for both a mark and a tag, but they will refer to different
715 things.
716 Two marks have special significance. First, the mark insert is associ‐
718 ated with the insertion cursor, as described under THE INSERTION CURSOR
719 below. Second, the mark current is associated with the character clos‐
720 est to the mouse and is adjusted automatically to track the mouse posi‐
721 tion and any changes to the text in the widget (one exception: current
722 is not updated in response to mouse motions if a mouse button is down;
723 the update will be deferred until all mouse buttons have been re‐
724 leased). Neither of these special marks may be deleted. With the ex‐
725 ception of these two special marks, all marks are shared between peer
726 text widgets, and may be manipulated on an equal basis from any peer.
727
729 The third form of annotation in text widgets is an embedded window.
730 Each embedded window annotation causes a window to be displayed at a
731 particular point in the text. There may be any number of embedded win‐
732 dows in a text widget, and any widget may be used as an embedded window
733 (subject to the usual rules for geometry management, which require the
734 text window to be the parent of the embedded window or a descendant of
735 its parent).
736 The embedded window's position on the screen will be updated as the
738 text is modified or scrolled, and it will be mapped and unmapped as it
739 moves into and out of the visible area of the text widget. Each embed‐
740 ded window occupies one unit's worth of index space in the text widget,
741 and it may be referred to either by the name of its embedded window or
742 by its position in the widget's index space. If the range of text con‐
743 taining the embedded window is deleted then the window is destroyed.
744 Similarly if the text widget as a whole is deleted, then the window is
745 destroyed.
746 Eliding an embedded window immediately after scheduling it for creation
748 via pathName window create index -create will prevent it from being ef‐
749 fectively created. Uneliding an elided embedded window scheduled for
750 creation via pathName window create index -create will automatically
751 trigger the associated creation script. After destroying an elided em‐
752 bedded window, the latter won't get automatically recreated.
753 When an embedded window is added to a text widget with the pathName
755 window create widget command, several configuration options may be as‐
756 sociated with it. These options may be modified later with the pathName
757 window configure widget command. The following options are currently
758 supported:
759 -align where
761 If the window is not as tall as the line in which it is dis‐
762 played, this option determines where the window is displayed in
763 the line. Where must have one of the values top (align the top
764 of the window with the top of the line), center (center the win‐
765 dow within the range of the line), bottom (align the bottom of
766 the window with the bottom of the line's area), or baseline
767 (align the bottom of the window with the baseline of the line).
768 -create script
770 Specifies a Tcl script that may be evaluated to create the win‐
771 dow for the annotation. If no -window option has been specified
772 for the annotation this script will be evaluated when the anno‐
773 tation is about to be displayed on the screen. Script must cre‐
774 ate a window for the annotation and return the name of that win‐
775 dow as its result. Two substitutions will be performed in script
776 before evaluation. %W will be substituted by the name of the
777 parent text widget, and %% will be substituted by a single %.
778 If the annotation's window should ever be deleted, script will
779 be evaluated again the next time the annotation is displayed.
780 -padx pixels
782 Pixels specifies the amount of extra space to leave on each side
783 of the embedded window. It may have any of the usual forms de‐
784 fined for a screen distance.
785 -pady pixels
787 Pixels specifies the amount of extra space to leave on the top
788 and on the bottom of the embedded window. It may have any of the
789 usual forms defined for a screen distance.
790 -stretch boolean
792 If the requested height of the embedded window is less than the
793 height of the line in which it is displayed, this option can be
794 used to specify whether the window should be stretched verti‐
795 cally to fill its line. If the -pady option has been specified
796 as well, then the requested padding will be retained even if the
797 window is stretched.
798 -window pathName
800 Specifies the name of a window to display in the annotation.
801 Note that if a pathName has been set, then later configuring a
802 window to the empty string will not delete the widget corre‐
803 sponding to the old pathName. Rather it will remove the associ‐
804 ation between the old pathName and the text widget. If multiple
805 peer widgets are in use, it is usually simpler to use the -cre‐
806 ate option if embedded windows are desired in each peer.
807
809 The final form of annotation in text widgets is an embedded image. Each
810 embedded image annotation causes an image to be displayed at a particu‐
811 lar point in the text. There may be any number of embedded images in a
812 text widget, and a particular image may be embedded in multiple places
813 in the same text widget.
814 The embedded image's position on the screen will be updated as the text
816 is modified or scrolled. Each embedded image occupies one unit's worth
817 of index space in the text widget, and it may be referred to either by
818 its position in the widget's index space, or the name it is assigned
819 when the image is inserted into the text widget with pathName image
820 create. If the range of text containing the embedded image is deleted
821 then that copy of the image is removed from the screen.
822 Eliding an embedded image immediately after scheduling it for creation
824 via pathName image create index -create will prevent it from being ef‐
825 fectively created. Uneliding an elided embedded image scheduled for
826 creation via pathName image create index -create will automatically
827 trigger the associated creation script. After destroying an elided em‐
828 bedded image, the latter won't get automatically recreated.
829 When an embedded image is added to a text widget with the pathName im‐
831 age create widget command, a name unique to this instance of the image
832 is returned. This name may then be used to refer to this image in‐
833 stance. The name is taken to be the value of the -name option (de‐
834 scribed below). If the -name option is not provided, the -image name is
835 used instead. If the imageName is already in use in the text widget,
836 then #nn is added to the end of the imageName, where nn is an arbitrary
837 integer. This insures the imageName is unique. Once this name is as‐
838 signed to this instance of the image, it does not change, even though
839 the -image or -name values can be changed with pathName image config‐
840 ure.
841 When an embedded image is added to a text widget with the pathName im‐
843 age create widget command, several configuration options may be associ‐
844 ated with it. These options may be modified later with the pathName im‐
845 age configure widget command. The following options are currently sup‐
846 ported:
847 -align where
849 If the image is not as tall as the line in which it is dis‐
850 played, this option determines where the image is displayed in
851 the line. Where must have one of the values top (align the top
852 of the image with the top of the line), center (center the image
853 within the range of the line), bottom (align the bottom of the
854 image with the bottom of the line's area), or baseline (align
855 the bottom of the image with the baseline of the line).
856 -image image
858 Specifies the name of the Tk image to display in the annotation.
859 If image is not a valid Tk image, then an error is returned.
860 -name ImageName
862 Specifies the name by which this image instance may be refer‐
863 enced in the text widget. If ImageName is not supplied, then the
864 name of the Tk image is used instead. If the imageName is al‐
865 ready in use, #nn is appended to the end of the name as de‐
866 scribed above.
867 -padx pixels
869 Pixels specifies the amount of extra space to leave on each side
870 of the embedded image. It may have any of the usual forms de‐
871 fined for a screen distance.
872 -pady pixels
874 Pixels specifies the amount of extra space to leave on the top
875 and on the bottom of the embedded image. It may have any of the
876 usual forms defined for a screen distance.
877
879 Selection support is implemented via tags. If the -exportselection op‐
880 tion for the text widget is true then the sel tag will be associated
881 with the selection:
882 [1] Whenever characters are tagged with sel the text widget will
884 claim ownership of the selection.
885 [2] Attempts to retrieve the selection will be serviced by the text
887 widget, returning all the characters with the sel tag.
888 [3] If the selection is claimed away by another application or by
890 another window within this application, then the sel tag will be
891 removed from all characters in the text.
892 [4] Whenever the sel tag range changes a virtual event <<Selection>>
894 is generated.
895 The sel tag is automatically defined when a text widget is created, and
897 it may not be deleted with the “pathName tag delete” widget command.
898 Furthermore, the -selectbackground, -selectborderwidth, and -select‐
899 foreground options for the text widget are tied to the -background,
900 -borderwidth, and -foreground options for the sel tag: changes in ei‐
901 ther will automatically be reflected in the other. Also the -inactives‐
902 electbackground option for the text widget is used instead of -select‐
903 background when the text widget does not have the focus. This allows
904 programmatic control over the visualization of the sel tag for fore‐
905 ground and background windows, or to have sel not shown at all (when
906 -inactiveselectbackground is empty) for background windows. Each peer
907 text widget has its own sel tag which can be separately configured and
908 set.
909
911 The mark named insert has special significance in text widgets. It is
912 defined automatically when a text widget is created and it may not be
913 unset with the “pathName mark unset” widget command. The insert mark
914 represents the position of the insertion cursor, and the insertion cur‐
915 sor will automatically be drawn at this point whenever the text widget
916 has the input focus.
917
919 The text widget can keep track of changes to the content of the widget
920 by means of the modified flag. Inserting or deleting text will set this
921 flag. The flag can be queried, set and cleared programmatically as
922 well. Whenever the flag changes state a <<Modified>> virtual event is
923 generated. See the pathName edit modified widget command for more de‐
924 tails.
925
927 The text widget has an unlimited undo and redo mechanism (when the
928 -undo widget option is true) which records every insert and delete ac‐
929 tion on a stack.
930 Boundaries (called “separators”) are inserted between edit actions. The
932 purpose of these separators is to group inserts, deletes and replaces
933 into one compound edit action. When undoing a change everything between
934 two separators will be undone. The undone changes are then moved to the
935 redo stack, so that an undone edit can be redone again. The redo stack
936 is cleared whenever new edit actions are recorded on the undo stack.
937 The undo and redo stacks can be cleared to keep their depth under con‐
938 trol.
939 Separators are inserted automatically when the -autoseparators widget
941 option is true. You can insert separators programmatically as well. If
942 a separator is already present at the top of the undo stack no other
943 will be inserted. That means that two separators on the undo stack are
944 always separated by at least one insert or delete action.
945 The <<UndoStack>> virtual event is generated every time the undo stack
947 or the redo stack becomes empty or unempty.
948 The undo mechanism is also linked to the modified flag. This means that
950 undoing or redoing changes can take a modified text widget back to the
951 unmodified state or vice versa. The modified flag will be set automati‐
952 cally to the appropriate state. This automatic coupling does not work
953 when the modified flag has been set by the user, until the flag has
954 been reset again.
955 See below for the pathName edit widget command that controls the undo
957 mechanism.
958
960 The text widget has a separate store of all its data concerning each
961 line's textual contents, marks, tags, images and windows, and the undo
962 stack.
963 While this data store cannot be accessed directly (i.e. without a text
965 widget as an intermediary), multiple text widgets can be created, each
966 of which present different views on the same underlying data. Such text
967 widgets are known as peer text widgets.
968 As text is added, deleted, edited and coloured in any one widget, and
970 as images, marks, tags are adjusted, all such changes will be reflected
971 in all peers.
972 All data and markup is shared, except for a few small details. First,
974 the sel tag may be set and configured (in its display style) differ‐
975 ently for each peer. Second, each peer has its own insert and current
976 mark positions (but all other marks are shared). Third, embedded win‐
977 dows, which are arbitrary other widgets, cannot be shared between
978 peers. This means the -window option of embedded windows is indepen‐
979 dently set for each peer (it is advisable to use the -create script ca‐
980 pabilities to allow each peer to create its own embedded windows as
981 needed). Fourth, all of the configuration options of each peer (e.g.
982 -font, etc) can be set independently, with the exception of -undo,
983 -maxundo, -autoseparators (i.e. all undo, redo and modified state is‐
984 sues are shared).
985 Finally any single peer need not contain all lines from the underlying
987 data store. When creating a peer, a contiguous range of lines (e.g.
988 only lines 52 through 125) may be specified. This allows a peer to con‐
989 tain just a small portion of the overall text. The range of lines will
990 expand and contract as text is inserted or deleted. The peer will only
991 ever display complete lines of text (one cannot share just part of a
992 line). If the peer's contents contracts to nothing (i.e. all complete
993 lines in the peer widget have been deleted from another widget), then
994 it is impossible for new lines to be inserted. The peer will simply be‐
995 come an empty shell on which the background can be configured, but
996 which will never show any content (without manual reconfiguration of
997 the start and end lines). Note that a peer which does not contain all
998 of the underlying data store still has indices numbered from “1.0” to
999 “end”. It is simply that those indices reflect a subset of the total
1000 data, and data outside the contained range is not accessible to the
1001 peer. This means that the command peerName index end may return quite
1002 different values in different peers. Similarly, commands like peerName
1003 tag ranges will not return index ranges outside that which is meaning‐
1004 ful to the peer. The configuration options -startline and -endline may
1005 be used to control how much of the underlying data is contained in any
1006 given text widget.
1007 Note that peers are really peers. Deleting the “original” text widget
1009 will not cause any other peers to be deleted, or otherwise affected.
1010 See below for the pathName peer widget command that controls the cre‐
1012 ation of peer widgets.
1013
1015 In order to maintain a responsive user-experience, the text widget cal‐
1016 culates lines metrics (line heights in pixels) asynchronously. Because
1017 of this, some commands of the text widget may return wrong results if
1018 the asynchronous calculations are not finished at the time of calling.
1019 This applies to pathName count -ypixels and pathName yview.
1020 Again for performance reasons, it would not be appropriate to let these
1022 commands always wait for the end of the update calculation each time
1023 they are called. In most use cases of these commands a more or less in‐
1024 accurate result does not really matter compared to execution speed.
1025 In case accurate result is needed (and if the text widget is managed by
1027 a geometry manager), one can resort to pathName sync and pathName pend‐
1028 ingsync to control the synchronization of the view of text widgets.
1029 The <<WidgetViewSync>> virtual event fires when the line heights of the
1031 text widget become obsolete (due to some editing command or configura‐
1032 tion change), and again when the internal data of the text widget are
1033 back in sync with the widget view. The detail field (%d substitution)
1034 is either true (when the widget is in sync) or false (when it is not).
1035 pathName sync, pathName pendingsync and <<WidgetViewSync>> apply to
1037 each text widget independently of its peers.
1038 Examples of use:
1040 ## Example 1:
1041 # immediately complete line metrics at any cost (GUI unresponsive)
1042 $w sync
1043 $w yview moveto $fraction
1044 ## Example 2:
1046 # synchronously wait for up-to-date line metrics (GUI responsive)
1047 # before executing the scheduled command, but don't block execution flow
1048 $w sync -command [list $w yview moveto $fraction]
1049 ## Example 3:
1051 # init
1052 set yud($w) 0
1053 proc updateaction w {
1054 set ::yud($w) 1
1055 # any other update action here...
1056 }
1057 # runtime, synchronously wait for up-to-date line metrics (GUI responsive)
1058 $w sync -command [list updateaction $w]
1059 vwait yud($w)
1060 $w yview moveto $fraction
1061 ## Example 4:
1063 # init
1064 set todo($w) {}
1065 proc updateaction w {
1066 foreach cmd $::todo($w) {uplevel #0 $cmd}
1067 set todo($w) {}
1068 }
1069 # runtime
1070 lappend todo($w) [list $w yview moveto $fraction]
1071 $w sync -command [list updateaction $w]
1072 ## Example 5:
1074 # init
1075 set todo($w) {}
1076 bind $w <<WidgetViewSync>> {
1077 if {%d} {
1078 foreach cmd $todo(%W) {eval $cmd}
1079 set todo(%W) {}
1080 }
1081 }
1082 # runtime
1083 if {![$w pendingsync]} {
1084 $w yview moveto $fraction
1085 } else {
1086 lappend todo($w) [list $w yview moveto $fraction]
1087 }
1088
1090 The text command creates a new Tcl command whose name is the same as
1091 the path name of the text's window. This command may be used to invoke
1092 various operations on the widget. It has the following general form:
1093 pathName option ?arg arg ...?
1094 PathName is the name of the command, which is the same as the text wid‐
1095 get's path name. Option and the args determine the exact behavior of
1096 the command. The following commands are possible for text widgets:
1097 pathName bbox index
1099 Returns a list of four elements describing the screen area of
1100 the character given by index. The first two elements of the list
1101 give the x and y coordinates of the upper-left corner of the
1102 area occupied by the character, and the last two elements give
1103 the width and height of the area. If the character is only par‐
1104 tially visible on the screen, then the return value reflects
1105 just the visible part. If the character is not visible on the
1106 screen then the return value is an empty list.
1107 pathName cget option
1109 Returns the current value of the configuration option given by
1110 option. Option may have any of the values accepted by the text
1111 command.
1112 pathName compare index1 op index2
1114 Compares the indices given by index1 and index2 according to the
1115 relational operator given by op, and returns 1 if the relation‐
1116 ship is satisfied and 0 if it is not. Op must be one of the op‐
1117 erators <, <=, ==, >=, >, or !=. If op is == then 1 is returned
1118 if the two indices refer to the same character, if op is < then
1119 1 is returned if index1 refers to an earlier character in the
1120 text than index2, and so on.
1121 pathName configure ?option? ?value option value ...?
1123 Query or modify the configuration options of the widget. If no
1124 option is specified, returns a list describing all of the avail‐
1125 able options for pathName (see Tk_ConfigureInfo for information
1126 on the format of this list). If option is specified with no
1127 value, then the command returns a list describing the one named
1128 option (this list will be identical to the corresponding sublist
1129 of the value returned if no option is specified). If one or more
1130 option-value pairs are specified, then the command modifies the
1131 given widget option(s) to have the given value(s); in this case
1132 the command returns an empty string. Option may have any of the
1133 values accepted by the text command.
1134 pathName count ?options? index1 index2
1136 Counts the number of relevant things between the two indices. If
1137 index1 is after index2, the result will be a negative number
1138 (and this holds for each of the possible options). The actual
1139 items which are counted depend on the options given. The result
1140 is a list of integers, one for the result of each counting op‐
1141 tion given. Valid counting options are -chars, -displaychars,
1142 -displayindices, -displaylines, -indices, -lines, -xpixels and
1143 -ypixels. The default value, if no option is specified, is -in‐
1144 dices. There is an additional possible option -update which is a
1145 modifier. If given (and if the text widget is managed by a geom‐
1146 etry manager), then all subsequent options ensure that any pos‐
1147 sible out of date information is recalculated. This currently
1148 only has any effect for the -ypixels count (which, if -update is
1149 not given, will use the text widget's current cached value for
1150 each line). This -update option is obsoleted by pathName sync,
1151 pathName pendingsync and <<WidgetViewSync>>. The count options
1152 are interpreted as follows:
1153 -chars count all characters, whether elided or not. Do not count
1155 embedded windows or images.
1156 -displaychars
1158 count all non-elided characters.
1159 -displayindices
1161 count all non-elided characters, windows and images.
1162 -displaylines
1164 count all display lines (i.e. counting one for each time
1165 a line wraps) from the line of the first index up to, but
1166 not including the display line of the second index.
1167 Therefore if they are both on the same display line, zero
1168 will be returned. By definition displaylines are visible
1169 and therefore this only counts portions of actual visible
1170 lines.
1171 -indices
1173 count all characters and embedded windows or images (i.e.
1174 everything which counts in text-widget index space),
1175 whether they are elided or not.
1176 -lines count all logical lines (irrespective of wrapping) from
1178 the line of the first index up to, but not including the
1179 line of the second index. Therefore if they are both on
1180 the same line, zero will be returned. Logical lines are
1181 counted whether they are currently visible (non-elided)
1182 or not.
1183 -xpixels
1185 count the number of horizontal pixels from the first
1186 pixel of the first index to (but not including) the first
1187 pixel of the second index. To count the total desired
1188 width of the text widget (assuming wrapping is not en‐
1189 abled), first find the longest line and then use “.text
1190 count -xpixels "${line}.0" "${line}.0 lineend"”.
1191 -ypixels
1193 count the number of vertical pixels from the first pixel
1194 of the first index to (but not including) the first pixel
1195 of the second index. If both indices are on the same dis‐
1196 play line, zero will be returned. To count the total num‐
1197 ber of vertical pixels in the text widget, use “.text
1198 count -ypixels 1.0 end”, and to ensure this is up to
1199 date, use “.text count -update -ypixels 1.0 end”.
1200 The command returns a positive or negative integer corresponding
1202 to the number of items counted between the two indices. One such
1203 integer is returned for each counting option given, so a list is
1204 returned if more than one option was supplied. For example
1205 “.text count -xpixels -ypixels 1.3 4.5” is perfectly valid and
1206 will return a list of two elements.
1207 pathName debug ?boolean?
1209 If boolean is specified, then it must have one of the true or
1210 false values accepted by Tcl_GetBoolean. If the value is a true
1211 one then internal consistency checks will be turned on in the B-
1212 tree code associated with text widgets. If boolean has a false
1213 value then the debugging checks will be turned off. In either
1214 case the command returns an empty string. If boolean is not
1215 specified then the command returns on or off to indicate whether
1216 or not debugging is turned on. There is a single debugging
1217 switch shared by all text widgets: turning debugging on or off
1218 in any widget turns it on or off for all widgets. For widgets
1219 with large amounts of text, the consistency checks may cause a
1220 noticeable slow-down.
1221 When debugging is turned on, the drawing routines of the text
1223 widget set the global variables tk_textRedraw and tk_textRelay‐
1224 out to the lists of indices that are redrawn. The values of
1225 these variables are tested by Tk's test suite.
1226 pathName delete index1 ?index2 ...?
1228 Delete a range of characters from the text. If both index1 and
1229 index2 are specified, then delete all the characters starting
1230 with the one given by index1 and stopping just before index2
1231 (i.e. the character at index2 is not deleted). If index2 does
1232 not specify a position later in the text than index1 then no
1233 characters are deleted. If index2 is not specified then the
1234 single character at index1 is deleted. Attempts to delete char‐
1235 acters in a way that would leave the text without a newline as
1236 the last character will be tweaked by the text widget to avoid
1237 this. In particular, deletion of complete lines of text up to
1238 the end of the text will also delete the newline character just
1239 before the deleted block so that it is replaced by the new final
1240 newline of the text widget. The command returns an empty
1241 string. If more indices are given, multiple ranges of text will
1242 be deleted. All indices are first checked for validity before
1243 any deletions are made. They are sorted and the text is removed
1244 from the last range to the first range so deleted text does not
1245 cause an undesired index shifting side-effects. If multiple
1246 ranges with the same start index are given, then the longest
1247 range is used. If overlapping ranges are given, then they will
1248 be merged into spans that do not cause deletion of text outside
1249 the given ranges due to text shifted during deletion.
1250 pathName dlineinfo index
1252 Returns a list with five elements describing the area occupied
1253 by the display line containing index. The first two elements of
1254 the list give the x and y coordinates of the upper-left corner
1255 of the area occupied by the line, the third and fourth elements
1256 give the width and height of the area, and the fifth element
1257 gives the position of the baseline for the line, measured down
1258 from the top of the area. All of this information is measured in
1259 pixels. If the current wrap mode is none and the line extends
1260 beyond the boundaries of the window, the area returned reflects
1261 the entire area of the line, including the portions that are out
1262 of the window. If the line is shorter than the full width of the
1263 window then the area returned reflects just the portion of the
1264 line that is occupied by characters and embedded windows. If the
1265 display line containing index is not visible on the screen then
1266 the return value is an empty list.
1267 pathName dump ?switches? index1 ?index2?
1269 Return the contents of the text widget from index1 up to, but
1270 not including index2, including the text and information about
1271 marks, tags, and embedded windows. If index2 is not specified,
1272 then it defaults to one character past index1. The information
1273 is returned in the following format:
1274 key1 value1 index1 key2 value2 index2 ...
1276 The possible key values are text, mark, tagon, tagoff, image,
1278 and window. The corresponding value is the text, mark name, tag
1279 name, image name, or window name. The index information is the
1280 index of the start of the text, mark, tag transition, image or
1281 window. One or more of the following switches (or abbreviations
1282 thereof) may be specified to control the dump:
1283 -all Return information about all elements: text, marks, tags,
1285 images and windows. This is the default.
1286 -command command
1288 Instead of returning the information as the result of the
1289 dump operation, invoke the command on each element of the
1290 text widget within the range. The command has three ar‐
1291 guments appended to it before it is evaluated: the key,
1292 value, and index.
1293 -image Include information about images in the dump results.
1295 -mark Include information about marks in the dump results.
1297 -tag Include information about tag transitions in the dump re‐
1299 sults. Tag information is returned as tagon and tagoff
1300 elements that indicate the begin and end of each range of
1301 each tag, respectively.
1302 -text Include information about text in the dump results. The
1304 value is the text up to the next element or the end of
1305 range indicated by index2. A text element does not span
1306 newlines. A multi-line block of text that contains no
1307 marks or tag transitions will still be dumped as a set of
1308 text segments that each end with a newline. The newline
1309 is part of the value.
1310 -window
1312 Include information about embedded windows in the dump
1313 results. The value of a window is its Tk pathname, unless
1314 the window has not been created yet. (It must have a cre‐
1315 ate script.) In this case an empty string is returned,
1316 and you must query the window by its index position to
1317 get more information.
1318 pathName edit option ?arg arg ...?
1320 This command controls the undo mechanism and the modified flag.
1321 The exact behavior of the command depends on the option argument
1322 that follows the edit argument. The following forms of the com‐
1323 mand are currently supported:
1324 pathName edit canredo
1326 Returns a boolean true if redo is possible, i.e. when the
1327 redo stack is not empty. Otherwise returns false.
1328 pathName edit canundo
1330 Returns a boolean true if undo is possible, i.e. when the
1331 undo stack is not empty. Otherwise returns false.
1332 pathName edit modified ?boolean?
1334 If boolean is not specified, returns the modified flag of
1335 the widget. The insert, delete, edit undo and edit redo
1336 commands or the user can set or clear the modified flag.
1337 If boolean is specified, sets the modified flag of the
1338 widget to boolean.
1339 pathName edit redo
1341 When the -undo option is true, reapplies the last undone
1342 edits provided no other edits were done since then. Gen‐
1343 erates an error when the redo stack is empty. Does noth‐
1344 ing when the -undo option is false.
1345 pathName edit reset
1347 Clears the undo and redo stacks.
1348 pathName edit separator
1350 Inserts a separator (boundary) on the undo stack. Does
1351 nothing when the -undo option is false.
1352 pathName edit undo
1354 Undoes the last edit action when the -undo option is
1355 true. An edit action is defined as all the insert and
1356 delete commands that are recorded on the undo stack in
1357 between two separators. Generates an error when the undo
1358 stack is empty. Does nothing when the -undo option is
1359 false.
1360 pathName get ?-displaychars? ?--? index1 ?index2 ...?
1362 Return a range of characters from the text. The return value
1363 will be all the characters in the text starting with the one
1364 whose index is index1 and ending just before the one whose index
1365 is index2 (the character at index2 will not be returned). If in‐
1366 dex2 is omitted then the single character at index1 is returned.
1367 If there are no characters in the specified range (e.g. index1
1368 is past the end of the file or index2 is less than or equal to
1369 index1) then an empty string is returned. If the specified range
1370 contains embedded windows, no information about them is included
1371 in the returned string. If multiple index pairs are given, mul‐
1372 tiple ranges of text will be returned in a list. Invalid ranges
1373 will not be represented with empty strings in the list. The
1374 ranges are returned in the order passed to pathName get. If the
1375 -displaychars option is given, then, within each range, only
1376 those characters which are not elided will be returned. This may
1377 have the effect that some of the returned ranges are empty
1378 strings.
1379 pathName image option ?arg arg ...?
1381 This command is used to manipulate embedded images. The behavior
1382 of the command depends on the option argument that follows the
1383 image argument. The following forms of the command are currently
1384 supported:
1385 pathName image cget index option
1387 Returns the value of a configuration option for an embed‐
1388 ded image. Index identifies the embedded image, and op‐
1389 tion specifies a particular configuration option, which
1390 must be one of the ones listed in the section EMBEDDED
1391 IMAGES.
1392 pathName image configure index ?option value ...?
1394 Query or modify the configuration options for an embedded
1395 image. If no option is specified, returns a list describ‐
1396 ing all of the available options for the embedded image
1397 at index (see Tk_ConfigureInfo for information on the
1398 format of this list). If option is specified with no
1399 value, then the command returns a list describing the one
1400 named option (this list will be identical to the corre‐
1401 sponding sublist of the value returned if no option is
1402 specified). If one or more option-value pairs are speci‐
1403 fied, then the command modifies the given option(s) to
1404 have the given value(s); in this case the command returns
1405 an empty string. See EMBEDDED IMAGES for information on
1406 the options that are supported.
1407 pathName image create index ?option value ...?
1409 This command creates a new image annotation, which will
1410 appear in the text at the position given by index. Any
1411 number of option-value pairs may be specified to config‐
1412 ure the annotation. Returns a unique identifier that may
1413 be used as an index to refer to this image. See EMBEDDED
1414 IMAGES for information on the options that are supported,
1415 and a description of the identifier returned.
1416 pathName image names
1418 Returns a list whose elements are the names of all image
1419 instances currently embedded in window.
1420 pathName index index
1422 Returns the position corresponding to index in the form
1423 line.char where line is the line number and char is the charac‐
1424 ter number. Index may have any of the forms described under IN‐
1425 DICES above.
1426 pathName insert index chars ?tagList chars tagList ...?
1428 Inserts all of the chars arguments just before the character at
1429 index. If index refers to the end of the text (the character af‐
1430 ter the last newline) then the new text is inserted just before
1431 the last newline instead. If there is a single chars argument
1432 and no tagList, then the new text will receive any tags that are
1433 present on both the character before and the character after the
1434 insertion point; if a tag is present on only one of these char‐
1435 acters then it will not be applied to the new text. If tagList
1436 is specified then it consists of a list of tag names; the new
1437 characters will receive all of the tags in this list and no oth‐
1438 ers, regardless of the tags present around the insertion point.
1439 If multiple chars-tagList argument pairs are present, they pro‐
1440 duce the same effect as if a separate pathName insert widget
1441 command had been issued for each pair, in order. The last
1442 tagList argument may be omitted.
1443 pathName mark option ?arg arg ...?
1445 This command is used to manipulate marks. The exact behavior of
1446 the command depends on the option argument that follows the mark
1447 argument. The following forms of the command are currently sup‐
1448 ported:
1449 pathName mark gravity markName ?direction?
1451 If direction is not specified, returns left or right to
1452 indicate which of its adjacent characters markName is at‐
1453 tached to. If direction is specified, it must be left or
1454 right; the gravity of markName is set to the given value.
1455 pathName mark names
1457 Returns a list whose elements are the names of all the
1458 marks that are currently set.
1459 pathName mark next index
1461 Returns the name of the next mark at or after index. If
1462 index is specified in numerical form, then the search for
1463 the next mark begins at that index. If index is the name
1464 of a mark, then the search for the next mark begins imme‐
1465 diately after that mark. This can still return a mark at
1466 the same position if there are multiple marks at the same
1467 index. These semantics mean that the mark next operation
1468 can be used to step through all the marks in a text wid‐
1469 get in the same order as the mark information returned by
1470 the pathName dump operation. If a mark has been set to
1471 the special end index, then it appears to be after end
1472 with respect to the pathName mark next operation. An
1473 empty string is returned if there are no marks after in‐
1474 dex.
1475 pathName mark previous index
1477 Returns the name of the mark at or before index. If index
1478 is specified in numerical form, then the search for the
1479 previous mark begins with the character just before that
1480 index. If index is the name of a mark, then the search
1481 for the next mark begins immediately before that mark.
1482 This can still return a mark at the same position if
1483 there are multiple marks at the same index. These seman‐
1484 tics mean that the pathName mark previous operation can
1485 be used to step through all the marks in a text widget in
1486 the reverse order as the mark information returned by the
1487 pathName dump operation. An empty string is returned if
1488 there are no marks before index.
1489 pathName mark set markName index
1491 Sets the mark named markName to a position just before
1492 the character at index. If markName already exists, it is
1493 moved from its old position; if it does not exist, a new
1494 mark is created. This command returns an empty string.
1495 pathName mark unset markName ?markName markName ...?
1497 Remove the mark corresponding to each of the markName ar‐
1498 guments. The removed marks will not be usable in indices
1499 and will not be returned by future calls to “pathName
1500 mark names”. This command returns an empty string.
1501 pathName peer option args
1503 This command is used to create and query widget peers. It has
1504 two forms, depending on option:
1505 pathName peer create newPathName ?options?
1507 Creates a peer text widget with the given newPathName,
1508 and any optional standard configuration options (as for
1509 the text command). By default the peer will have the same
1510 start and end line as the parent widget, but these can be
1511 overridden with the standard configuration options.
1512 pathName peer names
1514 Returns a list of peers of this widget (this does not in‐
1515 clude the widget itself). The order within this list is
1516 undefined.
1517 pathName pendingsync
1519 Returns 1 if the line heights calculations are not up-to-date, 0
1520 otherwise.
1521 pathName replace index1 index2 chars ?tagList chars tagList ...?
1523 Replaces the range of characters between index1 and index2 with
1524 the given characters and tags. See the section on pathName in‐
1525 sert for an explanation of the handling of the tagList... argu‐
1526 ments, and the section on pathName delete for an explanation of
1527 the handling of the indices. If index2 corresponds to an index
1528 earlier in the text than index1, an error will be generated.
1529 The deletion and insertion are arranged so that no unnecessary
1531 scrolling of the window or movement of insertion cursor occurs.
1532 In addition the undo/redo stack are correctly modified, if undo
1533 operations are active in the text widget. The command returns an
1534 empty string.
1535 pathName scan option args
1537 This command is used to implement scanning on texts. It has two
1538 forms, depending on option:
1539 pathName scan mark x y
1541 Records x and y and the current view in the text window,
1542 for use in conjunction with later pathName scan dragto
1543 commands. Typically this command is associated with a
1544 mouse button press in the widget. It returns an empty
1545 string.
1546 pathName scan dragto x y
1548 This command computes the difference between its x and y
1549 arguments and the x and y arguments to the last pathName
1550 scan mark command for the widget. It then adjusts the
1551 view by 10 times the difference in coordinates. This com‐
1552 mand is typically associated with mouse motion events in
1553 the widget, to produce the effect of dragging the text at
1554 high speed through the window. The return value is an
1555 empty string.
1556 pathName search ?switches? pattern index ?stopIndex?
1558 Searches the text in pathName starting at index for a range of
1559 characters that matches pattern. If a match is found, the index
1560 of the first character in the match is returned as result; oth‐
1561 erwise an empty string is returned. One or more of the following
1562 switches (or abbreviations thereof) may be specified to control
1563 the search:
1564 -forwards
1566 The search will proceed forward through the text, finding
1567 the first matching range starting at or after the posi‐
1568 tion given by index. This is the default.
1569 -backwards
1571 The search will proceed backward through the text, find‐
1572 ing the matching range closest to index whose first char‐
1573 acter is before index (it is not allowed to be at index).
1574 Note that, for a variety of reasons, backwards searches
1575 can be substantially slower than forwards searches (par‐
1576 ticularly when using -regexp), so it is recommended that
1577 performance-critical code use forward searches.
1578 -exact Use exact matching: the characters in the matching range
1580 must be identical to those in pattern. This is the de‐
1581 fault.
1582 -regexp
1584 Treat pattern as a regular expression and match it
1585 against the text using the rules for regular expressions
1586 (see the regexp command and the re_syntax page for de‐
1587 tails). The default matching automatically passes both
1588 the -lineanchor and -linestop options to the regexp en‐
1589 gine (unless -nolinestop is used), so that ^$ match be‐
1590 ginning and end of line, and ., [^ sequences will never
1591 match the newline character \n.
1592 -nolinestop
1594 This allows . and [^ sequences to match the newline char‐
1595 acter \n, which they will otherwise not do (see the reg‐
1596 exp command for details). This option is only meaningful
1597 if -regexp is also given, and an error will be thrown
1598 otherwise. For example, to match the entire text, use
1599 “pathName search -nolinestop -regexp ".*" 1.0”.
1600 -nocase
1602 Ignore case differences between the pattern and the text.
1603 -count varName
1605 The argument following -count gives the name of a vari‐
1606 able; if a match is found, the number of index positions
1607 between beginning and end of the matching range will be
1608 stored in the variable. If there are no embedded images
1609 or windows in the matching range (and there are no elided
1610 characters if -elide is not given), this is equivalent to
1611 the number of characters matched. In either case, the
1612 range matchIdx to matchIdx + $count chars will return the
1613 entire matched text.
1614 -all Find all matches in the given range and return a list of
1616 the indices of the first character of each match. If a
1617 -count varName switch is given, then varName is also set
1618 to a list containing one element for each successful
1619 match. Note that, even for exact searches, the elements
1620 of this list may be different, if there are embedded im‐
1621 ages, windows or hidden text. Searches with -all behave
1622 very similarly to the Tcl command regexp -all, in that
1623 overlapping matches are not normally returned. For exam‐
1624 ple, applying an -all search of the pattern “\w+” against
1625 “hello there” will just match twice, once for each word,
1626 and matching “Z[a-z]+Z” against “ZooZooZoo” will just
1627 match once.
1628 -overlap
1630 When performing -all searches, the normal behaviour is
1631 that matches which overlap an already-found match will
1632 not be returned. This switch changes that behaviour so
1633 that all matches which are not totally enclosed within
1634 another match are returned. For example, applying an
1635 -overlap search of the pattern “\w+” against “hello
1636 there” will just match twice (i.e. no different to just
1637 -all), but matching “Z[a-z]+Z” against “ZooZooZoo” will
1638 now match twice. An error will be thrown if this switch
1639 is used without -all.
1640 -strictlimits
1642 When performing any search, the normal behaviour is that
1643 the start and stop limits are checked with respect to the
1644 start of the matching text. With the -strictlimits flag,
1645 the entire matching range must lie inside the start and
1646 stop limits specified for the match to be valid.
1647 -elide Find elided (hidden) text as well. By default only dis‐
1649 played text is searched.
1650 -- This switch has no effect except to terminate the list of
1652 switches: the next argument will be treated as pattern
1653 even if it starts with -.
1654 The matching range may be within a single line of text, or run
1656 across multiple lines (if parts of the pattern can match a new-
1657 line). For regular expression matching one can use the various
1658 newline-matching features such as $ to match the end of a line,
1659 ^ to match the beginning of a line, and to control whether . is
1660 allowed to match a new-line. If stopIndex is specified, the
1661 search stops at that index: for forward searches, no match at or
1662 after stopIndex will be considered; for backward searches, no
1663 match earlier in the text than stopIndex will be considered. If
1664 stopIndex is omitted, the entire text will be searched: when the
1665 beginning or end of the text is reached, the search continues at
1666 the other end until the starting location is reached again; if
1667 stopIndex is specified, no wrap-around will occur. This means
1668 that, for example, if the search is -forwards but stopIndex is
1669 earlier in the text than startIndex, nothing will ever be found.
1670 See KNOWN BUGS below for a number of minor limitations of the
1671 pathName search command.
1672 pathName see index
1674 Adjusts the view in the window so that the character given by
1675 index is completely visible. If index is already visible then
1676 the command does nothing. If index is a short distance out of
1677 view, the command adjusts the view just enough to make index
1678 visible at the edge of the window. If index is far out of view,
1679 then the command centers index in the window.
1680 pathName sync ?-command command?
1682 Controls the synchronization of the view of the text widget.
1683 pathName sync
1685 Immediately brings the line metrics up-to-date by forcing
1686 computation of any outdated line heights. The command re‐
1687 turns immediately if there is no such outdated line
1688 heights, otherwise it returns only at the end of the com‐
1689 putation. The command returns an empty string.
1690 pathName sync -command command
1692 Schedules command to be executed (by the event loop) ex‐
1693 actly once as soon as all line heights are up-to-date. If
1694 there are no pending line metrics calculations, the
1695 scheduling is immediate. The command returns the empty
1696 string. bgerror is called on command failure.
1697 pathName tag option ?arg arg ...?
1699 This command is used to manipulate tags. The exact behavior of
1700 the command depends on the option argument that follows the tag
1701 argument. The following forms of the command are currently sup‐
1702 ported:
1703 pathName tag add tagName index1 ?index2 index1 index2 ...?
1705 Associate the tag tagName with all of the characters
1706 starting with index1 and ending just before index2 (the
1707 character at index2 is not tagged). A single command may
1708 contain any number of index1-index2 pairs. If the last
1709 index2 is omitted then the single character at index1 is
1710 tagged. If there are no characters in the specified range
1711 (e.g. index1 is past the end of the file or index2 is
1712 less than or equal to index1) then the command has no ef‐
1713 fect.
1714 pathName tag bind tagName ?sequence? ?script?
1716 This command associates script with the tag given by tag‐
1717 Name. Whenever the event sequence given by sequence oc‐
1718 curs for a character that has been tagged with tagName,
1719 the script will be invoked. This widget command is simi‐
1720 lar to the bind command except that it operates on char‐
1721 acters in a text rather than entire widgets. See the bind
1722 manual entry for complete details on the syntax of se‐
1723 quence and the substitutions performed on script before
1724 invoking it. If all arguments are specified then a new
1725 binding is created, replacing any existing binding for
1726 the same sequence and tagName (if the first character of
1727 script is “+” then script augments an existing binding
1728 rather than replacing it). In this case the return value
1729 is an empty string. If script is omitted then the command
1730 returns the script associated with tagName and sequence
1731 (an error occurs if there is no such binding). If both
1732 script and sequence are omitted then the command returns
1733 a list of all the sequences for which bindings have been
1734 defined for tagName.
1735 The only events for which bindings may be specified are
1737 those related to the mouse and keyboard (such as Enter,
1738 Leave, ButtonPress, Motion, and KeyPress) or virtual
1739 events. Event bindings for a text widget use the current
1740 mark described under MARKS above. An Enter event triggers
1741 for a tag when the tag first becomes present on the cur‐
1742 rent character, and a Leave event triggers for a tag when
1743 it ceases to be present on the current character. Enter
1744 and Leave events can happen either because the current
1745 mark moved or because the character at that position
1746 changed. Note that these events are different than Enter
1747 and Leave events for windows. Mouse and keyboard events
1748 are directed to the current character. If a virtual event
1749 is used in a binding, that binding can trigger only if
1750 the virtual event is defined by an underlying mouse-re‐
1751 lated or keyboard-related event.
1752 It is possible for the current character to have multiple
1754 tags, and for each of them to have a binding for a par‐
1755 ticular event sequence. When this occurs, one binding is
1756 invoked for each tag, in order from lowest-priority to
1757 highest priority. If there are multiple matching bindings
1758 for a single tag, then the most specific binding is cho‐
1759 sen (see the manual entry for the bind command for de‐
1760 tails). continue and break commands within binding
1761 scripts are processed in the same way as for bindings
1762 created with the bind command.
1763 If bindings are created for the widget as a whole using
1765 the bind command, then those bindings will supplement the
1766 tag bindings. The tag bindings will be invoked first,
1767 followed by bindings for the window as a whole.
1768 pathName tag cget tagName option
1770 This command returns the current value of the option
1771 named option associated with the tag given by tagName.
1772 Option may have any of the values accepted by the path‐
1773 Name tag configure widget command.
1774 pathName tag configure tagName ?option? ?value? ?option value
1776 ...?
1777 This command is similar to the pathName configure widget
1778 command except that it modifies options associated with
1779 the tag given by tagName instead of modifying options for
1780 the overall text widget. If no option is specified, the
1781 command returns a list describing all of the available
1782 options for tagName (see Tk_ConfigureInfo for information
1783 on the format of this list). If option is specified with
1784 no value, then the command returns a list describing the
1785 one named option (this list will be identical to the cor‐
1786 responding sublist of the value returned if no option is
1787 specified). If one or more option-value pairs are speci‐
1788 fied, then the command modifies the given option(s) to
1789 have the given value(s) in tagName; in this case the com‐
1790 mand returns an empty string. See TAGS above for details
1791 on the options available for tags.
1792 pathName tag delete tagName ?tagName ...?
1794 Deletes all tag information for each of the tagName argu‐
1795 ments. The command removes the tags from all characters
1796 in the file and also deletes any other information asso‐
1797 ciated with the tags, such as bindings and display infor‐
1798 mation. The command returns an empty string.
1799 pathName tag lower tagName ?belowThis?
1801 Changes the priority of tag tagName so that it is just
1802 lower in priority than the tag whose name is belowThis.
1803 If belowThis is omitted, then tagName's priority is
1804 changed to make it lowest priority of all tags.
1805 pathName tag names ?index?
1807 Returns a list whose elements are the names of all the
1808 tags that are active at the character position given by
1809 index. If index is omitted, then the return value will
1810 describe all of the tags that exist for the text (this
1811 includes all tags that have been named in a “pathName
1812 tag” widget command but have not been deleted by a “path‐
1813 Name tag delete” widget command, even if no characters
1814 are currently marked with the tag). The list will be
1815 sorted in order from lowest priority to highest priority.
1816 pathName tag nextrange tagName index1 ?index2?
1818 This command searches the text for a range of characters
1819 tagged with tagName where the first character of the
1820 range is no earlier than the character at index1 and no
1821 later than the character just before index2 (a range
1822 starting at index2 will not be considered). If several
1823 matching ranges exist, the first one is chosen. The com‐
1824 mand's return value is a list containing two elements,
1825 which are the index of the first character of the range
1826 and the index of the character just after the last one in
1827 the range. If no matching range is found then the return
1828 value is an empty string. If index2 is not given then it
1829 defaults to the end of the text.
1830 pathName tag prevrange tagName index1 ?index2?
1832 This command searches the text for a range of characters
1833 tagged with tagName where the first character of the
1834 range is before the character at index1 and no earlier
1835 than the character at index2 (a range starting at index2
1836 will be considered). If several matching ranges exist,
1837 the one closest to index1 is chosen. The command's return
1838 value is a list containing two elements, which are the
1839 index of the first character of the range and the index
1840 of the character just after the last one in the range. If
1841 no matching range is found then the return value is an
1842 empty string. If index2 is not given then it defaults to
1843 the beginning of the text.
1844 pathName tag raise tagName ?aboveThis?
1846 Changes the priority of tag tagName so that it is just
1847 higher in priority than the tag whose name is aboveThis.
1848 If aboveThis is omitted, then tagName's priority is
1849 changed to make it highest priority of all tags.
1850 pathName tag ranges tagName
1852 Returns a list describing all of the ranges of text that
1853 have been tagged with tagName. The first two elements of
1854 the list describe the first tagged range in the text, the
1855 next two elements describe the second range, and so on.
1856 The first element of each pair contains the index of the
1857 first character of the range, and the second element of
1858 the pair contains the index of the character just after
1859 the last one in the range. If there are no characters
1860 tagged with tag then an empty string is returned.
1861 pathName tag remove tagName index1 ?index2 index1 index2 ...?
1863 Remove the tag tagName from all of the characters start‐
1864 ing at index1 and ending just before index2 (the charac‐
1865 ter at index2 is not affected). A single command may con‐
1866 tain any number of index1-index2 pairs. If the last in‐
1867 dex2 is omitted then the tag is removed from the single
1868 character at index1. If there are no characters in the
1869 specified range (e.g. index1 is past the end of the file
1870 or index2 is less than or equal to index1) then the com‐
1871 mand has no effect. This command returns an empty string.
1872 pathName window option ?arg arg ...?
1874 This command is used to manipulate embedded windows. The behav‐
1875 ior of the command depends on the option argument that follows
1876 the window argument. The following forms of the command are cur‐
1877 rently supported:
1878 pathName window cget index option
1880 Returns the value of a configuration option for an embed‐
1881 ded window. Index identifies the embedded window, and
1882 option specifies a particular configuration option, which
1883 must be one of the ones listed in the section EMBEDDED
1884 WINDOWS.
1885 pathName window configure index ?option value ...?
1887 Query or modify the configuration options for an embedded
1888 window. If no option is specified, returns a list de‐
1889 scribing all of the available options for the embedded
1890 window at index (see Tk_ConfigureInfo for information on
1891 the format of this list). If option is specified with no
1892 value, then the command returns a list describing the one
1893 named option (this list will be identical to the corre‐
1894 sponding sublist of the value returned if no option is
1895 specified). If one or more option-value pairs are speci‐
1896 fied, then the command modifies the given option(s) to
1897 have the given value(s); in this case the command returns
1898 an empty string. See EMBEDDED WINDOWS for information on
1899 the options that are supported.
1900 pathName window create index ?option value ...?
1902 This command creates a new window annotation, which will
1903 appear in the text at the position given by index. Any
1904 number of option-value pairs may be specified to config‐
1905 ure the annotation. See EMBEDDED WINDOWS for information
1906 on the options that are supported. Returns an empty
1907 string.
1908 pathName window names
1910 Returns a list whose elements are the names of all win‐
1911 dows currently embedded in window.
1912 pathName xview option args
1914 This command is used to query and change the horizontal position
1915 of the text in the widget's window. It can take any of the fol‐
1916 lowing forms:
1917 pathName xview
1919 Returns a list containing two elements. Each element is a
1920 real fraction between 0 and 1; together they describe the
1921 portion of the document's horizontal span that is visible
1922 in the window. For example, if the first element is .2
1923 and the second element is .6, 20% of the text is off-
1924 screen to the left, the middle 40% is visible in the win‐
1925 dow, and 40% of the text is off-screen to the right. The
1926 fractions refer only to the lines that are actually visi‐
1927 ble in the window: if the lines in the window are all
1928 very short, so that they are entirely visible, the re‐
1929 turned fractions will be 0 and 1, even if there are other
1930 lines in the text that are much wider than the window.
1931 These are the same values passed to scrollbars via the
1932 -xscrollcommand option.
1933 pathName xview moveto fraction
1935 Adjusts the view in the window so that fraction of the
1936 horizontal span of the text is off-screen to the left.
1937 Fraction is a fraction between 0 and 1.
1938 pathName xview scroll number what
1940 This command shifts the view in the window left or right
1941 according to number and what. What must be units, pages
1942 or pixels. If what is units or pages then number must be
1943 an integer, otherwise number may be specified in any of
1944 the forms acceptable to Tk_GetPixels, such as “2.0c” or
1945 “1i” (the result is rounded to the nearest integer value.
1946 If no units are given, pixels are assumed). If what is
1947 units, the view adjusts left or right by number average-
1948 width characters on the display; if it is pages then the
1949 view adjusts by number screenfuls; if it is pixels then
1950 the view adjusts by number pixels. If number is negative
1951 then characters farther to the left become visible; if it
1952 is positive then characters farther to the right become
1953 visible.
1954 pathName yview ?args?
1956 This command is used to query and change the vertical position
1957 of the text in the widget's window. It can take any of the fol‐
1958 lowing forms:
1959 pathName yview
1961 Returns a list containing two elements, both of which are
1962 real fractions between 0 and 1. The first element gives
1963 the position of the first visible pixel of the first
1964 character (or image, etc) in the top line in the window,
1965 relative to the text as a whole (0.5 means it is halfway
1966 through the text, for example). The second element gives
1967 the position of the first pixel just after the last visi‐
1968 ble one in the bottom line of the window, relative to the
1969 text as a whole. These are the same values passed to
1970 scrollbars via the -yscrollcommand option.
1971 pathName yview moveto fraction
1973 Adjusts the view in the window so that the pixel given by
1974 fraction appears at the top of the top line of the win‐
1975 dow. Fraction is a fraction between 0 and 1; 0 indicates
1976 the first pixel of the first character in the text, 0.33
1977 indicates the pixel that is one-third the way through the
1978 text; and so on. Values close to 1 will indicate values
1979 close to the last pixel in the text (1 actually refers to
1980 one pixel beyond the last pixel), but in such cases the
1981 widget will never scroll beyond the last pixel, and so a
1982 value of 1 will effectively be rounded back to whatever
1983 fraction ensures the last pixel is at the bottom of the
1984 window, and some other pixel is at the top.
1985 pathName yview scroll number what
1987 This command adjust the view in the window up or down ac‐
1988 cording to number and what. What must be units, pages or
1989 pixels. If what is units or pages then number must be an
1990 integer, otherwise number may be specified in any of the
1991 forms acceptable to Tk_GetPixels, such as “2.0c” or “1i”
1992 (the result is rounded to the nearest integer value. If
1993 no units are given, pixels are assumed). If what is
1994 units, the view adjusts up or down by number lines on the
1995 display; if it is pages then the view adjusts by number
1996 screenfuls; if it is pixels then the view adjusts by num‐
1997 ber pixels. If number is negative then earlier positions
1998 in the text become visible; if it is positive then later
1999 positions in the text become visible.
2000 pathName yview ?-pickplace? index
2002 Changes the view in the widget's window to make index
2003 visible. If the -pickplace option is not specified then
2004 index will appear at the top of the window. If -pickplace
2005 is specified then the widget chooses where index appears
2006 in the window:
2007 [1] If index is already visible somewhere in the win‐
2009 dow then the command does nothing.
2010 [2] If index is only a few lines off-screen above the
2012 window then it will be positioned at the top of
2013 the window.
2014 [3] If index is only a few lines off-screen below the
2016 window then it will be positioned at the bottom of
2017 the window.
2018 [4] Otherwise, index will be centered in the window.
2020 The -pickplace option has been obsoleted by the pathName
2022 see widget command (pathName see handles both x- and y-
2023 motion to make a location visible, whereas the -pickplace
2024 mode only handles motion in y).
2025 pathName yview number
2027 This command makes the first character on the line after
2028 the one given by number visible at the top of the window.
2029 Number must be an integer. This command used to be used
2030 for scrolling, but now it is obsolete.
2031
2033 Tk automatically creates class bindings for texts that give them the
2034 following default behavior. In the descriptions below, “word” is de‐
2035 pendent on the value of the tcl_wordchars variable. See tclvars(n).
2036 [1] Clicking mouse button 1 positions the insertion cursor at the
2038 closest edge of the character underneath the mouse cursor, sets
2039 the input focus to this widget, and clears any selection in the
2040 widget. Dragging with mouse button 1 strokes out a selection be‐
2041 tween the insertion cursor and the character under the mouse.
2042 [2] Double-clicking with mouse button 1 selects the word under the
2044 mouse and positions the insertion cursor at the start of the
2045 word. Dragging after a double click will stroke out a selection
2046 consisting of whole words.
2047 [3] Triple-clicking with mouse button 1 selects the line under the
2049 mouse and positions the insertion cursor at the start of the
2050 line. Dragging after a triple click will stroke out a selection
2051 consisting of whole lines.
2052 [4] The ends of the selection can be adjusted by dragging with mouse
2054 button 1 while the Shift key is down; this will adjust the end
2055 of the selection that was nearest to the mouse cursor when but‐
2056 ton 1 was pressed. If the button is double-clicked before drag‐
2057 ging then the selection will be adjusted in units of whole
2058 words; if it is triple-clicked then the selection will be ad‐
2059 justed in units of whole lines.
2060 [5] Clicking mouse button 1 with the Control key down will reposi‐
2062 tion the insertion cursor without affecting the selection.
2063 [6] If any normal printing characters are typed, they are inserted
2065 at the point of the insertion cursor.
2066 [7] The view in the widget can be adjusted by dragging with the mid‐
2068 dle mouse button (button 2, or button 3 in TkAqua). If the mid‐
2069 dle mouse button is clicked without moving the mouse, the selec‐
2070 tion is copied into the text at the position of the mouse cur‐
2071 sor. The Insert key also inserts the selection, but at the posi‐
2072 tion of the insertion cursor.
2073 [8] If the mouse is dragged out of the widget while button 1 is
2075 pressed, the entry will automatically scroll to make more text
2076 visible (if there is more text off-screen on the side where the
2077 mouse left the window).
2078 [9] The Left and Right keys move the insertion cursor one character
2080 to the left or right; they also clear any selection in the text.
2081 If Left or Right is typed with the Shift key down, then the in‐
2082 sertion cursor moves and the selection is extended to include
2083 the new character. Control-Left and Control-Right move the in‐
2084 sertion cursor by words, and Control-Shift-Left and Control-
2085 Shift-Right move the insertion cursor by words and also extend
2086 the selection. Control-b and Control-f behave the same as Left
2087 and Right, respectively. Meta-b and Meta-f behave the same as
2088 Control-Left and Control-Right, respectively.
2089 [10] The Up and Down keys move the insertion cursor one line up or
2091 down and clear any selection in the text. If Up or Right is
2092 typed with the Shift key down, then the insertion cursor moves
2093 and the selection is extended to include the new character. Con‐
2094 trol-Up and Control-Down move the insertion cursor by paragraphs
2095 (groups of lines separated by blank lines), and Control-Shift-Up
2096 and Control-Shift-Down move the insertion cursor by paragraphs
2097 and also extend the selection. Control-p and Control-n behave
2098 the same as Up and Down, respectively.
2099 [11] The Next and Prior keys move the insertion cursor forward or
2101 backwards by one screenful and clear any selection in the text.
2102 If the Shift key is held down while Next or Prior is typed, then
2103 the selection is extended to include the new character.
2104 [12] Control-Next and Control-Prior scroll the view right or left by
2106 one page without moving the insertion cursor or affecting the
2107 selection.
2108 [13] Home and Control-a move the insertion cursor to the beginning of
2110 its display line and clear any selection in the widget. Shift-
2111 Home moves the insertion cursor to the beginning of the display
2112 line and also extends the selection to that point.
2113 [14] End and Control-e move the insertion cursor to the end of the
2115 display line and clear any selection in the widget. Shift-End
2116 moves the cursor to the end of the display line and extends the
2117 selection to that point.
2118 [15] Control-Home and Meta-< move the insertion cursor to the begin‐
2120 ning of the text and clear any selection in the widget. Control-
2121 Shift-Home moves the insertion cursor to the beginning of the
2122 text and also extends the selection to that point.
2123 [16] Control-End and Meta-> move the insertion cursor to the end of
2125 the text and clear any selection in the widget. Control-Shift-
2126 End moves the cursor to the end of the text and extends the se‐
2127 lection to that point.
2128 [17] The Select key and Control-Space set the selection anchor to the
2130 position of the insertion cursor. They do not affect the current
2131 selection. Shift-Select and Control-Shift-Space adjust the se‐
2132 lection to the current position of the insertion cursor, select‐
2133 ing from the anchor to the insertion cursor if there was not any
2134 selection previously.
2135 [18] Control-/ selects the entire contents of the widget.
2137 [19] Control-\ clears any selection in the widget.
2139 [20] The F16 key (labelled Copy on many Sun workstations) or Meta-w
2141 copies the selection in the widget to the clipboard, if there is
2142 a selection. This action is carried out by the command
2143 tk_textCopy.
2144 [21] The F20 key (labelled Cut on many Sun workstations) or Control-w
2146 copies the selection in the widget to the clipboard and deletes
2147 the selection. This action is carried out by the command
2148 tk_textCut. If there is no selection in the widget then these
2149 keys have no effect.
2150 [22] The F18 key (labelled Paste on many Sun workstations) or Con‐
2152 trol-y inserts the contents of the clipboard at the position of
2153 the insertion cursor. This action is carried out by the command
2154 tk_textPaste.
2155 [23] The Delete key deletes the selection, if there is one in the
2157 widget. If there is no selection, it deletes the character to
2158 the right of the insertion cursor.
2159 [24] Backspace and Control-h delete the selection, if there is one in
2161 the widget. If there is no selection, they delete the character
2162 to the left of the insertion cursor.
2163 [25] Control-d deletes the character to the right of the insertion
2165 cursor.
2166 [26] Meta-d deletes the word to the right of the insertion cursor.
2168 [27] Control-k deletes from the insertion cursor to the end of its
2170 line; if the insertion cursor is already at the end of a line,
2171 then Control-k deletes the newline character.
2172 [28] Control-o opens a new line by inserting a newline character in
2174 front of the insertion cursor without moving the insertion cur‐
2175 sor.
2176 [29] Meta-backspace and Meta-Delete delete the word to the left of
2178 the insertion cursor.
2179 [30] Control-x deletes whatever is selected in the text widget after
2181 copying it to the clipboard.
2182 [31] Control-t reverses the order of the two characters to the right
2184 of the insertion cursor.
2185 [32] Control-z undoes the last edit action if the -undo option is
2187 true. Does nothing otherwise.
2188 [33] Control-Z (or Control-y on Windows) reapplies the last undone
2190 edit action if the -undo option is true. Does nothing otherwise.
2191 If the widget is disabled using the -state option, then its view can
2193 still be adjusted and text can still be selected, but no insertion cur‐
2194 sor will be displayed and no text modifications will take place.
2195 The behavior of texts can be changed by defining new bindings for indi‐
2197 vidual widgets or by redefining the class bindings.
2198
2200 ISSUES CONCERNING CHARS AND INDICES
2201 Before Tk 8.5, the widget used the string “chars” to refer to index po‐
2202 sitions (which included characters, embedded windows and embedded im‐
2203 ages). As of Tk 8.5 the text widget deals separately and correctly with
2204 “chars” and “indices”. For backwards compatibility, however, the index
2205 modifiers “+N chars” and “-N chars” continue to refer to indices. One
2206 must use any of the full forms “+N any chars” or “-N any chars” etc. to
2207 refer to actual character indices. This confusion may be fixed in a fu‐
2208 ture release by making the widget correctly interpret “+N chars” as a
2209 synonym for “+N any chars”.
2210 PERFORMANCE ISSUES
2212 Text widgets should run efficiently under a variety of conditions. The
2213 text widget uses about 2-3 bytes of main memory for each byte of text,
2214 so texts containing a megabyte or more should be practical on most
2215 workstations. Text is represented internally with a modified B-tree
2216 structure that makes operations relatively efficient even with large
2217 texts. Tags are included in the B-tree structure in a way that allows
2218 tags to span large ranges or have many disjoint smaller ranges without
2219 loss of efficiency. Marks are also implemented in a way that allows
2220 large numbers of marks. In most cases it is fine to have large numbers
2221 of unique tags, or a tag that has many distinct ranges.
2222 One performance problem can arise if you have hundreds or thousands of
2224 different tags that all have the following characteristics: the first
2225 and last ranges of each tag are near the beginning and end of the text,
2226 respectively, or a single tag range covers most of the text widget. The
2227 cost of adding and deleting tags like this is proportional to the num‐
2228 ber of other tags with the same properties. In contrast, there is no
2229 problem with having thousands of distinct tags if their overall ranges
2230 are localized and spread uniformly throughout the text.
2231 Very long text lines can be expensive, especially if they have many
2233 marks and tags within them.
2234 The display line with the insert cursor is redrawn each time the cursor
2236 blinks, which causes a steady stream of graphics traffic. Set the -in‐
2237 sertofftime attribute to 0 avoid this.
2238 KNOWN BUGS
2240 The pathName search -regexp sub-command attempts to perform sophisti‐
2241 cated regexp matching across multiple lines in an efficient fashion
2242 (since Tk 8.5), examining each line individually, and then in small
2243 groups of lines, whether searching forwards or backwards. Under certain
2244 conditions the search result might differ from that obtained by apply‐
2245 ing the same regexp to the entire text from the widget in one go. For
2246 example, when searching with a greedy regexp, the widget will continue
2247 to attempt to add extra lines to the match as long as one of two condi‐
2248 tions are true: either Tcl's regexp library returns a code to indicate
2249 a longer match is possible (but there are known bugs in Tcl which mean
2250 this code is not always correctly returned); or if each extra line
2251 added results in at least a partial match with the pattern. This means
2252 in the case where the first extra line added results in no match and
2253 Tcl's regexp system returns the incorrect code and adding a second ex‐
2254 tra line would actually match, the text widget will return the wrong
2255 result. In practice this is a rare problem, but it can occur, for exam‐
2256 ple:
2257 pack [text .t]
2258 .t insert 1.0 "aaaa\nbbbb\ncccc\nbbbb\naaaa\n"
2259 .t search -regexp -- {(a+|b+\nc+\nb+)+\na+} 1.0
2260 will not find a match when one exists of 19 characters starting from
2261 the first “b”.
2262 Whenever one possible match is fully enclosed in another, the search
2264 command will attempt to ensure only the larger match is returned. When
2265 performing backwards regexp searches it is possible that Tcl will not
2266 always achieve this, in the case where a match is preceded by one or
2267 more short, non-overlapping matches, all of which are preceded by a
2268 large match which actually encompasses all of them. The search algo‐
2269 rithm used by the widget does not look back arbitrarily far for a pos‐
2270 sible match which might cover large portions of the widget. For exam‐
2271 ple:
2272 pack [text .t]
2273 .t insert 1.0 "aaaa\nbbbb\nbbbb\nbbbb\nbbbb\n"
2274 .t search -regexp -backward -- {b+\n|a+\n(b+\n)+} end
2275 matches at “5.0” when a true greedy match would match at “1.0”. Simi‐
2276 larly if we add -all to this case, it matches at all of “5.0”, “4.0”,
2277 “3.0” and “1.0”, when really it should only match at “1.0” since that
2278 match encloses all the others.
2279
2281 entry(n), scrollbar(n)
2282
2284 text, widget, tkvars
2285Tk 8.5 text(n)