1text(n) Tk Built-In Commands text(n)
2______________________________________________________________________________
6
8 text, tk_textCopy, tk_textCut, tk_textPaste - Create and manipulate
9 text 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 [-autoseparators autoSeparators] Specifies a boolean that says whether
31 separators are automatically inserted in the undo stack. Only meaning‐
32 ful when the -undo option is true. [-blockcursor blockCursor] Speci‐ │
33 fies a boolean that says whether the blinking insertion cursor should │
34 be drawn as a character-sized rectangular block. If false (the │
35 default) a thin vertical line is used for the insertion cursor. [-end‐
36 line endLine] Specifies an integer line index representing the line of │
37 the underlying textual data store that should be just after the last │
38 line contained in the widget. This allows a text widget to reflect │
39 only a portion of a larger piece of text. Instead of an integer, the │
40 empty string can be provided to this configuration option, which will │
41 configure the widget to end at the very last line in the textual data │
42 store. [-height height] Specifies the desired height for the window,
43 in units of characters in the font given by the -font option. Must be
44 at least one. [-inactiveselectbackground inactiveSelectBackground] │
45 Specifies the colour to use for the selection (the sel tag) when the │
46 window does not have the input focus. If empty, {}, then no selection │
47 is shown when the window does not have the focus. [-maxundo maxUndo]
48 Specifies the maximum number of compound undo actions on the undo
49 stack. A zero or a negative value imply an unlimited undo stack.
50 [-spacing1 spacing1] Requests additional space above each text line in
51 the widget, using any of the standard forms for screen distances. If a
52 line wraps, this option only applies to the first line on the display.
53 This option may be overridden with -spacing1 options in tags. [-spac‐
54 ing2 spacing2] For lines that wrap (so that they cover more than one
55 line on the display) this option specifies additional space to provide
56 between the display lines that represent a single line of text. The
57 value may have any of the standard forms for screen distances. This
58 option may be overridden with -spacing2 options in tags. [-spac‐
59 ing3 spacing3] Requests additional space below each text line in the
60 widget, using any of the standard forms for screen distances. If a
61 line wraps, this option only applies to the last line on the display.
62 This option may be overridden with -spacing3 options in tags. [-start‐
63 line startLine] Specifies an integer line index representing the first │
64 line of the underlying textual data store that should be contained in │
65 the widget. This allows a text widget to reflect only a portion of a │
66 larger piece of text. Instead of an integer, the empty string can be │
67 provided to this configuration option, which will configure the widget │
68 to start at the very first line in the textual data store.
69 [-state state] Specifies one of two states for the text: normal or
70 disabled. If the text is disabled then characters may not be inserted
71 or deleted and no insertion cursor will be displayed, even if the input
72 focus is in the widget. [-tabs tabs] Specifies a set of tab stops for
73 the window. The option's value consists of a list of screen distances
74 giving the positions of the tab stops, each of which is a distance rel‐
75 ative to the left edge of the widget (excluding borders, padding, etc).
76 Each position may optionally be followed in the next list element by
77 one of the keywords left, right, center, or numeric, which specifies
78 how to justify text relative to the tab stop. Left is the default; it
79 causes the text following the tab character to be positioned with its
80 left edge at the tab position. Right means that the right edge of the
81 text following the tab character is positioned at the tab position, and
82 center means that the text is centered at the tab position. Numeric
83 means that the decimal point in the text is positioned at the tab posi‐
84 tion; if there is no decimal point then the least significant digit of
85 the number is positioned just to the left of the tab position; if
86 there is no number in the text then the text is right-justified at the
87 tab position. For example, “-tabs {2c left 4c 6c center}” creates
88 three tab stops at two-centimeter intervals; the first two use left
89 justification and the third uses center justification.
90 If the list of tab stops does not have enough elements to cover
92 all of the tabs in a text line, then Tk extrapolates new tab
93 stops using the spacing and alignment from the last tab stop in
94 the list. Tab distances must be strictly positive, and must
95 always increase from one tab stop to the next (if not, an error
96 is thrown). The value of the tabs option may be overridden by
97 -tabs options in tags.
98 If no -tabs option is specified, or if it is specified as an
100 empty list, then Tk uses default tabs spaced every eight (aver‐
101 age size) characters. To achieve a different standard spacing,
102 for example every 4 characters, simply configure the widget with
103 “-tabs "[expr {4 * [font measure $font 0]}] left" -tabstyle
104 wordprocessor”.
105 [-tabstyle tabStyle] Specifies how to interpret the relationship
106 between tab stops on a line and tabs in the text of that line. The
107 value must be tabular (the default) or wordprocessor. Note that tabs
108 are interpreted as they are encountered in the text. If the tab style
109 is tabular then the n'th tab character in the line's text will be asso‐
110 ciated with the n'th tab stop defined for that line. If the tab char‐
111 acter's x coordinate falls to the right of the n'th tab stop, then a
112 gap of a single space will be inserted as a fallback. If the tab style
113 is wordprocessor then any tab character being laid out will use (and be
114 defined by) the first tab stop to the right of the preceding characters
115 already laid out on that line. The value of the tabstyle option may be
116 overridden by -tabstyle options in tags. [-undo undo] Specifies a
117 boolean that says whether the undo mechanism is active or not.
118 [-width width] Specifies the desired width for the window in units of
119 characters in the font given by the -font option. If the font does not
120 have a uniform width then the width of the character “0” is used in
121 translating from character units to screen units. [-wrap wrap] Speci‐
122 fies how to handle lines in the text that are too long to be displayed
123 in a single line of the text's window. The value must be none or char
124 or word. A wrap mode of none means that each line of text appears as
125 exactly one line on the screen; extra characters that do not fit on
126 the screen are not displayed. In the other modes each line of text
127 will be broken up into several screen lines if necessary to keep all
128 the characters visible. In char mode a screen line break may occur
129 after any character; in word mode a line break will only be made at
130 word boundaries.
131_________________________________________________________________
132
135 The text command creates a new window (given by the pathName argument)
136 and makes it into a text widget. Additional options, described above,
137 may be specified on the command line or in the option database to con‐
138 figure aspects of the text such as its default background color and
139 relief. The text command returns the path name of the new window.
140 A text widget displays one or more lines of text and allows that text
142 to be edited. Text widgets support four different kinds of annotations
143 on the text, called tags, marks, embedded windows or embedded images.
144 Tags allow different portions of the text to be displayed with differ‐
145 ent fonts and colors. In addition, Tcl commands can be associated with
146 tags so that scripts are invoked when particular actions such as key‐
147 strokes and mouse button presses occur in particular ranges of the
148 text. See TAGS below for more details.
149 The second form of annotation consists of floating markers in the text
151 called “marks”. Marks are used to keep track of various interesting
152 positions in the text as it is edited. See MARKS below for more
153 details.
154 The third form of annotation allows arbitrary windows to be embedded in
156 a text widget. See EMBEDDED WINDOWS below for more details.
157 The fourth form of annotation allows Tk images to be embedded in a text
159 widget. See EMBEDDED IMAGES below for more details.
160 The text widget also has a built-in undo/redo mechanism. See THE UNDO
162 MECHANISM below for more details.
163 The text widget allows for the creation of peer widgets. These are │
165 other text widgets which share the same underlying data (text, marks, │
166 tags, images, etc). See PEER WIDGETS below for more details.
167
169 Many of the widget commands for texts take one or more indices as argu‐
170 ments. An index is a string used to indicate a particular place within
171 a text, such as a place to insert characters or one endpoint of a range
172 of characters to delete. Indices have the syntax
173 base modifier modifier modifier ...
174 Where base gives a starting point and the modifiers adjust the index
175 from the starting point (e.g. move forward or backward one character).
176 Every index must contain a base, but the modifiers are optional. Most │
177 modifiers (as documented below) allow an optional submodifier. Valid │
178 submodifiers are any and display. If the submodifier is abbreviated, │
179 then it must be followed by whitespace, but otherwise there need be no │
180 space between the submodifier and the following modifier. Typically │
181 the display submodifier adjusts the meaning of the following modifier │
182 to make it refer to visual or non-elided units rather than logical │
183 units, but this is explained for each relevant case below. Lastly, │
184 where count is used as part of a modifier, it can be positive or nega‐ │
185 tive, so “base - -3 lines” is perfectly valid (and equivalent to “base │
186 +3lines”).
187 The base for an index must have one of the following forms:
189 line.char Indicates char'th character on line line. Lines are num‐
191 bered from 1 for consistency with other UNIX programs that
192 use this numbering scheme. Within a line, characters are
193 numbered from 0. If char is end then it refers to the new‐
194 line character that ends the line.
195 @x,y Indicates the character that covers the pixel whose x and y
197 coordinates within the text's window are x and y.
198 end Indicates the end of the text (the character just after the
200 last newline).
201 mark Indicates the character just after the mark whose name is
203 mark.
204 tag.first Indicates the first character in the text that has been
206 tagged with tag. This form generates an error if no char‐
207 acters are currently tagged with tag.
208 tag.last Indicates the character just after the last one in the text
210 that has been tagged with tag. This form generates an
211 error if no characters are currently tagged with tag.
212 pathName Indicates the position of the embedded window whose name is
214 pathName. This form generates an error if there is no
215 embedded window by the given name.
216 imageName Indicates the position of the embedded image whose name is
218 imageName. This form generates an error if there is no
219 embedded image by the given name.
220 If the base could match more than one of the above forms, such as a
222 mark and imageName both having the same value, then the form earlier in
223 the above list takes precedence. If modifiers follow the base index,
224 each one of them must have one of the forms listed below. Keywords
225 such as chars and wordend may be abbreviated as long as the abbrevia‐
226 tion is unambiguous.
227 + count ?submodifier? chars
229 Adjust the index forward by count characters, moving to later │
230 lines in the text if necessary. If there are fewer than count │
231 characters in the text after the current index, then set the │
232 index to the last index in the text. Spaces on either side of │
233 count are optional. If the display submodifier is given, elided │
234 characters are skipped over without being counted. If any is │
235 given, then all characters are counted. For historical reasons, │
236 if neither modifier is given then the count actually takes place │
237 in units of index positions (see indices for details). This be‐ │
238 haviour may be changed in a future major release, so if you need │
239 an index count, you are encouraged to use indices instead wher‐ │
240 ever possible.
241 - count ?submodifier? chars
243 Adjust the index backward by count characters, moving to earlier
244 lines in the text if necessary. If there are fewer than count
245 characters in the text before the current index, then set the
246 index to the first index in the text (1.0). Spaces on either │
247 side of count are optional. If the display submodifier is │
248 given, elided characters are skipped over without being counted. │
249 If any is given, then all characters are counted. For histori‐ │
250 cal reasons, if neither modifier is given then the count actu‐ │
251 ally takes place in units of index positions (see indices for │
252 details). This behaviour may be changed in a future major │
253 release, so if you need an index count, you are encouraged to │
254 use indices instead wherever possible.
255 + count ?submodifier? indices
257 Adjust the index forward by count index positions, moving to │
258 later lines in the text if necessary. If there are fewer than │
259 count index positions in the text after the current index, then │
260 set the index to the last index position in the text. Spaces on │
261 either side of count are optional. Note that an index position │
262 is either a single character or a single embedded image or │
263 embedded window. If the display submodifier is given, elided │
264 indices are skipped over without being counted. If any is │
265 given, then all indices are counted; this is also the default │
266 behaviour if no modifier is given.
267 - count ?submodifier? indices
269 Adjust the index backward by count index positions, moving to │
270 earlier lines in the text if necessary. If there are fewer than │
271 count index positions in the text before the current index, then │
272 set the index to the first index position (1.0) in the text. │
273 Spaces on either side of count are optional. If the display │
274 submodifier is given, elided indices are skipped over without │
275 being counted. If any is given, then all indices are counted; │
276 this is also the default behaviour if no modifier is given.
277 + count ?submodifier? lines
279 Adjust the index forward by count lines, retaining the same │
280 character position within the line. If there are fewer than │
281 count lines after the line containing the current index, then │
282 set the index to refer to the same character position on the │
283 last line of the text. Then, if the line is not long enough to │
284 contain a character at the indicated character position, adjust │
285 the character position to refer to the last character of the │
286 line (the newline). Spaces on either side of count are │
287 optional. If the display submodifier is given, then each visual │
288 display line is counted separately. Otherwise, if any (or no │
289 modifier) is given, then each logical line (no matter how many │
290 times it is visually wrapped) counts just once. If the relevant │
291 lines are not wrapped, then these two methods of counting are │
292 equivalent.
293 - count ?submodifier? lines
295 Adjust the index backward by count logical lines, retaining the │
296 same character position within the line. If there are fewer │
297 than count lines before the line containing the current index, │
298 then set the index to refer to the same character position on │
299 the first line of the text. Then, if the line is not long │
300 enough to contain a character at the indicated character posi‐ │
301 tion, adjust the character position to refer to the last charac‐ │
302 ter of the line (the newline). Spaces on either side of count │
303 are optional. If the display submodifier is given, then each │
304 visual display line is counted separately. Otherwise, if any │
305 (or no modifier) is given, then each logical line (no matter how │
306 many times it is visually wrapped) counts just once. If the │
307 relevant lines are not wrapped, then these two methods of count‐ │
308 ing are equivalent.
309 ?submodifier? linestart
311 Adjust the index to refer to the first index on the line. If │
312 the display submodifier is given, this is the first index on the │
313 display line, otherwise on the logical line.
314 ?submodifier? lineend
316 Adjust the index to refer to the last index on the line (the │
317 newline). If the display submodifier is given, this is the last │
318 index on the display line, otherwise on the logical line.
319 ?submodifier? wordstart
321 Adjust the index to refer to the first character of the word │
322 containing the current index. A word consists of any number of │
323 adjacent characters that are letters, digits, or underscores, or │
324 a single character that is not one of these. If the display │
325 submodifier is given, this only examines non-elided characters, │
326 otherwise all characters (elided or not) are examined.
327 ?submodifier? wordend
329 Adjust the index to refer to the character just after the last │
330 one of the word containing the current index. If the current │
331 index refers to the last character of the text then it is not │
332 modified. If the display submodifier is given, this only exam‐ │
333 ines non-elided characters, otherwise all characters (elided or │
334 not) are examined. │
335 If more than one modifier is present then they are applied in left-to- │
337 right order. For example, the index “end - 1 chars” refers to the │
338 next-to-last character in the text and “insert wordstart - 1 c” refers │
339 to the character just before the first one in the word containing the │
340 insertion cursor. Modifiers are applied one by one in this left to │
341 right order, and after each step the resulting index is constrained to │
342 be a valid index in the text widget. So, for example, the index “1.0 │
343 -1c +1c” refers to the index “2.0”. │
344 Where modifiers result in index changes by display lines, display chars │
346 or display indices, and the base refers to an index inside an elided │
347 tag, that base index is considered to be equivalent to the first fol‐ │
348 lowing non-elided index.
349
351 The first form of annotation in text widgets is a tag. A tag is a tex‐
352 tual string that is associated with some of the characters in a text.
353 Tags may contain arbitrary characters, but it is probably best to avoid
354 using the characters “ ” (space), +, or -: these characters have spe‐
355 cial meaning in indices, so tags containing them cannot be used as
356 indices. There may be any number of tags associated with characters in
357 a text. Each tag may refer to a single character, a range of charac‐
358 ters, or several ranges of characters. An individual character may
359 have any number of tags associated with it.
360 A priority order is defined among tags, and this order is used in
362 implementing some of the tag-related functions described below. When a
363 tag is defined (by associating it with characters or setting its dis‐
364 play options or binding commands to it), it is given a priority higher
365 than any existing tag. The priority order of tags may be redefined
366 using the “pathName tag raise” and “pathName tag lower” widget com‐
367 mands.
368 Tags serve three purposes in text widgets. First, they control the way
370 information is displayed on the screen. By default, characters are
371 displayed as determined by the -background, -font, and -foreground
372 options for the text widget. However, display options may be associ‐
373 ated with individual tags using the “pathName tag configure” widget
374 command. If a character has been tagged, then the display options
375 associated with the tag override the default display style. The fol‐
376 lowing options are currently supported for tags:
377 -background color
379 Color specifies the background color to use for characters asso‐
380 ciated with the tag. It may have any of the forms accepted by
381 Tk_GetColor.
382 -bgstipple bitmap
384 Bitmap specifies a bitmap that is used as a stipple pattern for
385 the background. It may have any of the forms accepted by
386 Tk_GetBitmap. If bitmap has not been specified, or if it is
387 specified as an empty string, then a solid fill will be used for
388 the background.
389 -borderwidth pixels
391 Pixels specifies the width of a 3-D border to draw around the
392 background. It may have any of the forms accepted by Tk_GetPix‐
393 els. This option is used in conjunction with the -relief option
394 to give a 3-D appearance to the background for characters; it is
395 ignored unless the -background option has been set for the tag.
396 -elide boolean
398 Elide specifies whether the data should be elided. Elided data
399 (characters, images, embedded windows, etc) is not displayed and
400 takes no space on screen, but further on behaves just as normal
401 data.
402 -fgstipple bitmap
404 Bitmap specifies a bitmap that is used as a stipple pattern when
405 drawing text and other foreground information such as under‐
406 lines. It may have any of the forms accepted by Tk_GetBitmap.
407 If bitmap has not been specified, or if it is specified as an
408 empty string, then a solid fill will be used.
409 -font fontName
411 FontName is the name of a font to use for drawing characters.
412 It may have any of the forms accepted by Tk_GetFont.
413 -foreground color
415 Color specifies the color to use when drawing text and other
416 foreground information such as underlines. It may have any of
417 the forms accepted by Tk_GetColor.
418 -justify justify
420 If the first non-elided character of a display line has a tag
421 for which this option has been specified, then justify deter‐
422 mines how to justify the line. It must be one of left, right,
423 or center. If a line wraps, then the justification for each
424 line on the display is determined by the first non-elided char‐
425 acter of that display line.
426 -lmargin1 pixels
428 If the first non-elided character of a text line has a tag for
429 which this option has been specified, then pixels specifies how
430 much the line should be indented from the left edge of the win‐
431 dow. Pixels may have any of the standard forms for screen dis‐
432 tances. If a line of text wraps, this option only applies to
433 the first line on the display; the -lmargin2 option controls
434 the indentation for subsequent lines.
435 -lmargin2 pixels
437 If the first non-elided character of a display line has a tag
438 for which this option has been specified, and if the display
439 line is not the first for its text line (i.e., the text line has
440 wrapped), then pixels specifies how much the line should be
441 indented from the left edge of the window. Pixels may have any
442 of the standard forms for screen distances. This option is only
443 used when wrapping is enabled, and it only applies to the second
444 and later display lines for a text line.
445 -offset pixels
447 Pixels specifies an amount by which the text's baseline should
448 be offset vertically from the baseline of the overall line, in
449 pixels. For example, a positive offset can be used for super‐
450 scripts and a negative offset can be used for subscripts. Pix‐
451 els may have any of the standard forms for screen distances.
452 -overstrike boolean
454 Specifies whether or not to draw a horizontal rule through the
455 middle of characters. Boolean may have any of the forms
456 accepted by Tcl_GetBoolean.
457 -relief relief
459 Relief specifies the 3-D relief to use for drawing backgrounds,
460 in any of the forms accepted by Tk_GetRelief. This option is
461 used in conjunction with the -borderwidth option to give a 3-D
462 appearance to the background for characters; it is ignored
463 unless the -background option has been set for the tag.
464 -rmargin pixels
466 If the first non-elided character of a display line has a tag
467 for which this option has been specified, then pixels specifies
468 how wide a margin to leave between the end of the line and the
469 right edge of the window. Pixels may have any of the standard
470 forms for screen distances. This option is only used when wrap‐
471 ping is enabled. If a text line wraps, the right margin for
472 each line on the display is determined by the first non-elided
473 character of that display line.
474 -spacing1 pixels
476 Pixels specifies how much additional space should be left above
477 each text line, using any of the standard forms for screen dis‐
478 tances. If a line wraps, this option only applies to the first
479 line on the display.
480 -spacing2 pixels
482 For lines that wrap, this option specifies how much additional
483 space to leave between the display lines for a single text line.
484 Pixels may have any of the standard forms for screen distances.
485 -spacing3 pixels
487 Pixels specifies how much additional space should be left below
488 each text line, using any of the standard forms for screen dis‐
489 tances. If a line wraps, this option only applies to the last
490 line on the display.
491 -tabs tabList
493 TabList specifies a set of tab stops in the same form as for the
494 -tabs option for the text widget. This option only applies to a
495 display line if it applies to the first non-elided character on
496 that display line. If this option is specified as an empty
497 string, it cancels the option, leaving it unspecified for the
498 tag (the default). If the option is specified as a non-empty
499 string that is an empty list, such as -tags { }, then it
500 requests default 8-character tabs as described for the -tags
501 widget option.
502 -tabstyle style
504 Style specifies either the tabular or wordprocessor style of
505 tabbing to use for the text widget. This option only applies to
506 a display line if it applies to the first non-elided character
507 on that display line. If this option is specified as an empty
508 string, it cancels the option, leaving it unspecified for the
509 tag (the default).
510 -underline boolean
512 Boolean specifies whether or not to draw an underline underneath
513 characters. It may have any of the forms accepted by Tcl_Get‐
514 Boolean.
515 -wrap mode
517 Mode specifies how to handle lines that are wider than the
518 text's window. It has the same legal values as the -wrap option
519 for the text widget: none, char, or word. If this tag option
520 is specified, it overrides the -wrap option for the text widget.
521 If a character has several tags associated with it, and if their dis‐
523 play options conflict, then the options of the highest priority tag are
524 used. If a particular display option has not been specified for a par‐
525 ticular tag, or if it is specified as an empty string, then that option
526 will never be used; the next-highest-priority tag's option will used
527 instead. If no tag specifies a particular display option, then the
528 default style for the widget will be used.
529 The second purpose for tags is event bindings. You can associate bind‐
531 ings with a tag in much the same way you can associate bindings with a
532 widget class: whenever particular X events occur on characters with
533 the given tag, a given Tcl command will be executed. Tag bindings can
534 be used to give behaviors to ranges of characters; among other things,
535 this allows hypertext-like features to be implemented. For details,
536 see the description of the “pathName tag bind” widget command below. │
537 Tag bindings are shared between all peer widgets (including any bind‐ │
538 ings for the special sel tag).
539 The third use for tags is in managing the selection. See THE SELECTION
541 below. With the exception of the special sel tag, all tags are shared │
542 between peer text widgets, and may be manipulated on an equal basis │
543 from any such widget. The sel tag exists separately and independently │
544 in each peer text widget (but any tag bindings to sel are shared).
545
547 The second form of annotation in text widgets is a mark. Marks are
548 used for remembering particular places in a text. They are something
549 like tags, in that they have names and they refer to places in the
550 file, but a mark is not associated with particular characters.
551 Instead, a mark is associated with the gap between two characters.
552 Only a single position may be associated with a mark at any given time.
553 If the characters around a mark are deleted the mark will still remain;
554 it will just have new neighbor characters. In contrast, if the charac‐
555 ters containing a tag are deleted then the tag will no longer have an
556 association with characters in the file. Marks may be manipulated with
557 the “pathName mark” widget command, and their current locations may be
558 determined by using the mark name as an index in widget commands.
559 Each mark also has a “gravity”, which is either left or right. The
561 gravity for a mark specifies what happens to the mark when text is
562 inserted at the point of the mark. If a mark has left gravity, then
563 the mark is treated as if it were attached to the character on its
564 left, so the mark will remain to the left of any text inserted at the
565 mark position. If the mark has right gravity, new text inserted at the
566 mark position will appear to the left of the mark (so that the mark
567 remains rightmost). The gravity for a mark defaults to right.
568 The name space for marks is different from that for tags: the same
570 name may be used for both a mark and a tag, but they will refer to dif‐
571 ferent things.
572 Two marks have special significance. First, the mark insert is associ‐
574 ated with the insertion cursor, as described under THE INSERTION CURSOR
575 below. Second, the mark current is associated with the character clos‐
576 est to the mouse and is adjusted automatically to track the mouse posi‐
577 tion and any changes to the text in the widget (one exception: current
578 is not updated in response to mouse motions if a mouse button is down;
579 the update will be deferred until all mouse buttons have been
580 released). Neither of these special marks may be deleted. With the │
581 exception of these two special marks, all marks are shared between peer │
582 text widgets, and may be manipulated on an equal basis from any peer.
583
585 The third form of annotation in text widgets is an embedded window.
586 Each embedded window annotation causes a window to be displayed at a
587 particular point in the text. There may be any number of embedded
588 windows in a text widget, and any widget may be used as an embedded
589 window (subject to the usual rules for geometry management, which
590 require the text window to be the parent of the embedded window or a
591 descendant of its parent). The embedded window's position on the
592 screen will be updated as the text is modified or scrolled, and it will
593 be mapped and unmapped as it moves into and out of the visible area of
594 the text widget. Each embedded window occupies one unit's worth of │
595 index space in the text widget, and it may be referred to either by the
596 name of its embedded window or by its position in the widget's index
597 space. If the range of text containing the embedded window is deleted
598 then the window is destroyed. Similarly if the text widget as a whole │
599 is deleted, then the window is destroyed.
600 When an embedded window is added to a text widget with the pathName
602 window create widget command, several configuration options may be
603 associated with it. These options may be modified later with the
604 pathName window configure widget command. The following options are
605 currently supported:
606 -align where
608 If the window is not as tall as the line in which it is dis‐
609 played, this option determines where the window is displayed in
610 the line. Where must have one of the values top (align the top
611 of the window with the top of the line), center (center the win‐
612 dow within the range of the line), bottom (align the bottom of
613 the window with the bottom of the line's area), or baseline
614 (align the bottom of the window with the baseline of the line).
615 -create script
617 Specifies a Tcl script that may be evaluated to create the win‐
618 dow for the annotation. If no -window option has been specified
619 for the annotation this script will be evaluated when the anno‐
620 tation is about to be displayed on the screen. Script must cre‐
621 ate a window for the annotation and return the name of that win‐
622 dow as its result. Two substitutions will be performed in │
623 script before evaluation. %W will be substituted by the name of │
624 the parent text widget, and %% will be substituted by a single │
625 %. If the annotation's window should ever be deleted, script
626 will be evaluated again the next time the annotation is dis‐
627 played.
628 -padx pixels
630 Pixels specifies the amount of extra space to leave on each side
631 of the embedded window. It may have any of the usual forms
632 defined for a screen distance.
633 -pady pixels
635 Pixels specifies the amount of extra space to leave on the top
636 and on the bottom of the embedded window. It may have any of
637 the usual forms defined for a screen distance.
638 -stretch boolean
640 If the requested height of the embedded window is less than the
641 height of the line in which it is displayed, this option can be
642 used to specify whether the window should be stretched verti‐
643 cally to fill its line. If the -pady option has been specified
644 as well, then the requested padding will be retained even if the
645 window is stretched.
646 -window pathName
648 Specifies the name of a window to display in the annotation. │
649 Note that if a pathName has been set, then later configuring a │
650 window to the empty string will not delete the widget corre‐ │
651 sponding to the old pathName. Rather it will remove the associa‐ │
652 tion between the old pathName and the text widget. If multiple │
653 peer widgets are in use, it is usually simpler to use the -cre‐ │
654 ate option if embedded windows are desired in each peer.
655
657 The final form of annotation in text widgets is an embedded image.
658 Each embedded image annotation causes an image to be displayed at a
659 particular point in the text. There may be any number of embedded
660 images in a text widget, and a particular image may be embedded in mul‐
661 tiple places in the same text widget. The embedded image's position on
662 the screen will be updated as the text is modified or scrolled. Each
663 embedded image occupies one unit's worth of index space in the text │
664 widget, and it may be referred to either by its position in the wid‐
665 get's index space, or the name it is assigned when the image is
666 inserted into the text widget with pathName image create. If the range
667 of text containing the embedded image is deleted then that copy of the
668 image is removed from the screen.
669 When an embedded image is added to a text widget with the pathName
671 image create widget command, a name unique to this instance of the
672 image is returned. This name may then be used to refer to this image
673 instance. The name is taken to be the value of the -name option
674 (described below). If the -name option is not provided, the -image
675 name is used instead. If the imageName is already in use in the text
676 widget, then #nn is added to the end of the imageName, where nn is an
677 arbitrary integer. This insures the imageName is unique. Once this
678 name is assigned to this instance of the image, it does not change,
679 even though the -image or -name values can be changed with pathName
680 image configure.
681 When an embedded image is added to a text widget with the pathName
683 image create widget command, several configuration options may be asso‐
684 ciated with it. These options may be modified later with the pathName
685 image configure widget command. The following options are currently
686 supported:
687 -align where
689 If the image is not as tall as the line in which it is dis‐
690 played, this option determines where the image is displayed in
691 the line. Where must have one of the values top (align the top
692 of the image with the top of the line), center (center the image
693 within the range of the line), bottom (align the bottom of the
694 image with the bottom of the line's area), or baseline (align
695 the bottom of the image with the baseline of the line).
696 -image image
698 Specifies the name of the Tk image to display in the annotation.
699 If image is not a valid Tk image, then an error is returned.
700 -name ImageName
702 Specifies the name by which this image instance may be refer‐
703 enced in the text widget. If ImageName is not supplied, then the
704 name of the Tk image is used instead. If the imageName is
705 already in use, #nn is appended to the end of the name as
706 described above.
707 -padx pixels
709 Pixels specifies the amount of extra space to leave on each side
710 of the embedded image. It may have any of the usual forms
711 defined for a screen distance.
712 -pady pixels
714 Pixels specifies the amount of extra space to leave on the top
715 and on the bottom of the embedded image. It may have any of the
716 usual forms defined for a screen distance.
717
719 Selection support is implemented via tags. If the exportSelection
720 option for the text widget is true then the sel tag will be associated
721 with the selection:
722 [1] Whenever characters are tagged with sel the text widget will
724 claim ownership of the selection.
725 [2] Attempts to retrieve the selection will be serviced by the text
727 widget, returning all the characters with the sel tag.
728 [3] If the selection is claimed away by another application or by
730 another window within this application, then the sel tag will be
731 removed from all characters in the text.
732 [4] Whenever the sel tag range changes a virtual event <<Selection>>
734 is generated.
735 The sel tag is automatically defined when a text widget is created, and
737 it may not be deleted with the “pathName tag delete” widget command.
738 Furthermore, the selectBackground, selectBorderWidth, and selectFore‐
739 ground options for the text widget are tied to the -background, -bor‐
740 derwidth, and -foreground options for the sel tag: changes in either
741 will automatically be reflected in the other. Also the -inactivese‐ │
742 lectbackground option for the text widget is used instead of -select‐ │
743 background when the text widget does not have the focus. This allows │
744 programmatic control over the visualization of the sel tag for fore‐ │
745 ground and background windows, or to have sel not shown at all (when │
746 -inactiveselectbackground is empty) for background windows. Each peer │
747 text widget has its own sel tag which can be separately configured and │
748 set.
749
751 The mark named insert has special significance in text widgets. It is
752 defined automatically when a text widget is created and it may not be
753 unset with the “pathName mark unset” widget command. The insert mark
754 represents the position of the insertion cursor, and the insertion cur‐
755 sor will automatically be drawn at this point whenever the text widget
756 has the input focus.
757
759 The text widget can keep track of changes to the content of the widget
760 by means of the modified flag. Inserting or deleting text will set this
761 flag. The flag can be queried, set and cleared programmatically as
762 well. Whenever the flag changes state a <<Modified>> virtual event is
763 generated. See the pathName edit modified widget command for more
764 details.
765
767 The text widget has an unlimited undo and redo mechanism (when the
768 -undo widget option is true) which records every insert and delete
769 action on a stack.
770 Boundaries (called “separators”) are inserted between edit actions.
772 The purpose of these separators is to group inserts, deletes and
773 replaces into one compound edit action. When undoing a change every‐
774 thing between two separators will be undone. The undone changes are
775 then moved to the redo stack, so that an undone edit can be redone
776 again. The redo stack is cleared whenever new edit actions are
777 recorded on the undo stack. The undo and redo stacks can be cleared to
778 keep their depth under control.
779 Separators are inserted automatically when the -autoseparators widget
781 option is true. You can insert separators programmatically as well.
782 If a separator is already present at the top of the undo stack no other
783 will be inserted. That means that two separators on the undo stack are
784 always separated by at least one insert or delete action.
785 The undo mechanism is also linked to the modified flag. This means
787 that undoing or redoing changes can take a modified text widget back to
788 the unmodified state or vice versa. The modified flag will be set
789 automatically to the appropriate state. This automatic coupling does
790 not work when the modified flag has been set by the user, until the
791 flag has been reset again.
792 See below for the pathName edit widget command that controls the undo
794 mechanism.
795
797 The text widget has a separate store of all its data concerning each │
798 line's textual contents, marks, tags, images and windows, and the undo │
799 stack. │
800 While this data store cannot be accessed directly (i.e. without a text │
802 widget as an intermediary), multiple text widgets can be created, each │
803 of which present different views on the same underlying data. Such │
804 text widgets are known as peer text widgets. │
805 As text is added, deleted, edited and coloured in any one widget, and │
807 as images, marks, tags are adjusted, all such changes will be reflected │
808 in all peers. │
809 All data and markup is shared, except for a few small details. First, │
811 the sel tag may be set and configured (in its display style) differ‐ │
812 ently for each peer. Second, each peer has its own insert and current │
813 mark positions (but all other marks are shared). Third, embedded win‐ │
814 dows, which are arbitrary other widgets, cannot be shared between │
815 peers. This means the -window option of embedded windows is indepen‐ │
816 dently set for each peer (it is advisable to use the -create script │
817 capabilities to allow each peer to create its own embedded windows as │
818 needed). Fourth, all of the configuration options of each peer (e.g. │
819 -font, etc) can be set independently, with the exception of -undo, │
820 -maxUndo, -autoSeparators (i.e. all undo, redo and modified state │
821 issues are shared). │
822 Finally any single peer need not contain all lines from the underlying │
824 data store. When creating a peer, a contiguous range of lines (e.g. │
825 only lines 52 through 125) may be specified. This allows a peer to │
826 contain just a small portion of the overall text. The range of lines │
827 will expand and contract as text is inserted or deleted. The peer will │
828 only ever display complete lines of text (one cannot share just part of │
829 a line). If the peer's contents contracts to nothing (i.e. all com‐ │
830 plete lines in the peer widget have been deleted from another widget), │
831 then it is impossible for new lines to be inserted. The peer will sim‐ │
832 ply become an empty shell on which the background can be configured, │
833 but which will never show any content (without manual reconfiguration │
834 of the start and end lines). Note that a peer which does not contain │
835 all of the underlying data store still has indices numbered from “1.0” │
836 to “end”. It is simply that those indices reflect a subset of the │
837 total data, and data outside the contained range is not accessible to │
838 the peer. This means that the command peerName index end may return │
839 quite different values in different peers. Similarly, commands like │
840 peerName tag ranges will not return index ranges outside that which is │
841 meaningful to the peer. The configuration options -startline and -end‐ │
842 line may be used to control how much of the underlying data is con‐ │
843 tained in any given text widget. │
844 Note that peers are really peers. Deleting the “original” text widget │
846 will not cause any other peers to be deleted, or otherwise affected. │
847 See below for the pathName peer widget command that controls the cre‐ │
849 ation of peer widgets.
850
852 The text command creates a new Tcl command whose name is the same as
853 the path name of the text's window. This command may be used to invoke
854 various operations on the widget. It has the following general form:
855 pathName option ?arg arg ...?
856 PathName is the name of the command, which is the same as the text wid‐
857 get's path name. Option and the args determine the exact behavior of
858 the command. The following commands are possible for text widgets:
859 pathName bbox index
861 Returns a list of four elements describing the screen area of
862 the character given by index. The first two elements of the
863 list give the x and y coordinates of the upper-left corner of
864 the area occupied by the character, and the last two elements
865 give the width and height of the area. If the character is only
866 partially visible on the screen, then the return value reflects
867 just the visible part. If the character is not visible on the
868 screen then the return value is an empty list.
869 pathName cget option
871 Returns the current value of the configuration option given by
872 option. Option may have any of the values accepted by the text
873 command.
874 pathName compare index1 op index2
876 Compares the indices given by index1 and index2 according to the
877 relational operator given by op, and returns 1 if the relation‐
878 ship is satisfied and 0 if it is not. Op must be one of the
879 operators <, <=, ==, >=, >, or !=. If op is == then 1 is
880 returned if the two indices refer to the same character, if op
881 is < then 1 is returned if index1 refers to an earlier character
882 in the text than index2, and so on.
883 pathName configure ?option? ?value option value ...?
885 Query or modify the configuration options of the widget. If no
886 option is specified, returns a list describing all of the avail‐
887 able options for pathName (see Tk_ConfigureInfo for information
888 on the format of this list). If option is specified with no
889 value, then the command returns a list describing the one named
890 option (this list will be identical to the corresponding sublist
891 of the value returned if no option is specified). If one or
892 more option-value pairs are specified, then the command modifies
893 the given widget option(s) to have the given value(s); in this
894 case the command returns an empty string. Option may have any
895 of the values accepted by the text command. │
896 pathName count ?options? index1 index2 │
898 Counts the number of relevant things between the two indices. │
899 If index1 is after index2, the result will be a negative number │
900 (and this holds for each of the possible options). The actual │
901 items which are counted depend on the options given. The result │
902 is a list of integers, one for the result of each counting │
903 option given. Valid counting options are -chars, -displaychars, │
904 -displayindices, -displaylines, -indices, -lines, -xpixels and │
905 -ypixels. The default value, if no option is specified, is │
906 -indices. There is an additional possible option -update which │
907 is a modifier. If given, then all subsequent options ensure │
908 that any possible out of date information is recalculated. This │
909 currently only has any effect for the -ypixels count (which, if │
910 -update is not given, will use the text widget's current cached │
911 value for each line). The count options are interpreted as fol‐ │
912 lows: │
913 -chars │
915 count all characters, whether elided or not. Do not │
916 count embedded windows or images. │
917 -displaychars │
919 count all non-elided characters. │
920 -displayindices │
922 count all non-elided characters, windows and images. │
923 -displaylines │
925 count all display lines (i.e. counting one for each time │
926 a line wraps) from the line of the first index up to, but │
927 not including the display line of the second index. │
928 Therefore if they are both on the same display line, zero │
929 will be returned. By definition displaylines are visible │
930 and therefore this only counts portions of actual visible │
931 lines. │
932 -indices │
934 count all characters and embedded windows or images (i.e. │
935 everything which counts in text-widget index space), │
936 whether they are elided or not. │
937 -lines │
939 count all logical lines (irrespective of wrapping) from │
940 the line of the first index up to, but not including the │
941 line of the second index. Therefore if they are both on │
942 the same line, zero will be returned. Logical lines are │
943 counted whether they are currently visible (non-elided) │
944 or not. │
945 -xpixels │
947 count the number of horizontal pixels from the first │
948 pixel of the first index to (but not including) the first │
949 pixel of the second index. To count the total desired │
950 width of the text widget (assuming wrapping is not │
951 enabled), first find the longest line and then use “.text │
952 count -xpixels "${line}.0" "${line}.0 lineend"”. │
953 -ypixels │
955 count the number of vertical pixels from the first pixel │
956 of the first index to (but not including) the first pixel │
957 of the second index. If both indices are on the same │
958 display line, zero will be returned. To count the total │
959 number of vertical pixels in the text widget, use “.text │
960 count -ypixels 1.0 end”, and to ensure this is up to │
961 date, use “.text count -update -ypixels 1.0 end”. │
962 The command returns a positive or negative integer corresponding │
964 to the number of items counted between the two indices. One │
965 such integer is returned for each counting option given, so a │
966 list is returned if more than one option was supplied. For │
967 example “.text count -xpixels -ypixels 1.3 4.5” is perfectly │
968 valid and will return a list of two elements. │
969 pathName debug ?boolean?
971 If boolean is specified, then it must have one of the true or
972 false values accepted by Tcl_GetBoolean. If the value is a true
973 one then internal consistency checks will be turned on in the B-
974 tree code associated with text widgets. If boolean has a false
975 value then the debugging checks will be turned off. In either
976 case the command returns an empty string. If boolean is not
977 specified then the command returns on or off to indicate whether
978 or not debugging is turned on. There is a single debugging
979 switch shared by all text widgets: turning debugging on or off
980 in any widget turns it on or off for all widgets. For widgets
981 with large amounts of text, the consistency checks may cause a
982 noticeable slow-down.
983 When debugging is turned on, the drawing routines of the text
985 widget set the global variables tk_textRedraw and tk_textRelay‐
986 out to the lists of indices that are redrawn. The values of
987 these variables are tested by Tk's test suite.
988 pathName delete index1 ?index2 ...?
990 Delete a range of characters from the text. If both index1 and
991 index2 are specified, then delete all the characters starting
992 with the one given by index1 and stopping just before index2
993 (i.e. the character at index2 is not deleted). If index2 does
994 not specify a position later in the text than index1 then no
995 characters are deleted. If index2 is not specified then the
996 single character at index1 is deleted. It is not allowable to
997 delete characters in a way that would leave the text without a
998 newline as the last character. The command returns an empty
999 string. If more indices are given, multiple ranges of text will
1000 be deleted. All indices are first checked for validity before
1001 any deletions are made. They are sorted and the text is removed
1002 from the last range to the first range so deleted text does not
1003 cause an undesired index shifting side-effects. If multiple
1004 ranges with the same start index are given, then the longest
1005 range is used. If overlapping ranges are given, then they will
1006 be merged into spans that do not cause deletion of text outside
1007 the given ranges due to text shifted during deletion.
1008 pathName dlineinfo index
1010 Returns a list with five elements describing the area occupied
1011 by the display line containing index. The first two elements of
1012 the list give the x and y coordinates of the upper-left corner
1013 of the area occupied by the line, the third and fourth elements
1014 give the width and height of the area, and the fifth element
1015 gives the position of the baseline for the line, measured down
1016 from the top of the area. All of this information is measured
1017 in pixels. If the current wrap mode is none and the line
1018 extends beyond the boundaries of the window, the area returned
1019 reflects the entire area of the line, including the portions
1020 that are out of the window. If the line is shorter than the
1021 full width of the window then the area returned reflects just
1022 the portion of the line that is occupied by characters and
1023 embedded windows. If the display line containing index is not
1024 visible on the screen then the return value is an empty list.
1025 pathName dump ?switches? index1 ?index2?
1027 Return the contents of the text widget from index1 up to, but
1028 not including index2, including the text and information about
1029 marks, tags, and embedded windows. If index2 is not specified,
1030 then it defaults to one character past index1. The information
1031 is returned in the following format:
1032 key1 value1 index1 key2 value2 index2 ...
1034 The possible key values are text, mark, tagon, tagoff, image,
1036 and window. The corresponding value is the text, mark name, tag
1037 name, image name, or window name. The index information is the
1038 index of the start of the text, mark, tag transition, image or
1039 window. One or more of the following switches (or abbreviations
1040 thereof) may be specified to control the dump:
1041 -all Return information about all elements: text, marks, tags,
1043 images and windows. This is the default.
1044 -command command
1046 Instead of returning the information as the result of the
1047 dump operation, invoke the command on each element of the
1048 text widget within the range. The command has three
1049 arguments appended to it before it is evaluated: the key,
1050 value, and index.
1051 -image Include information about images in the dump results.
1053 -mark Include information about marks in the dump results.
1055 -tag Include information about tag transitions in the dump
1057 results. Tag information is returned as tagon and tagoff
1058 elements that indicate the begin and end of each range of
1059 each tag, respectively.
1060 -text Include information about text in the dump results. The
1062 value is the text up to the next element or the end of
1063 range indicated by index2. A text element does not span
1064 newlines. A multi-line block of text that contains no
1065 marks or tag transitions will still be dumped as a set of
1066 text segments that each end with a newline. The newline
1067 is part of the value.
1068 -window
1070 Include information about embedded windows in the dump
1071 results. The value of a window is its Tk pathname,
1072 unless the window has not been created yet. (It must
1073 have a create script.) In this case an empty string is
1074 returned, and you must query the window by its index
1075 position to get more information.
1076 pathName edit option ?arg arg ...?
1078 This command controls the undo mechanism and the modified flag.
1079 The exact behavior of the command depends on the option argument
1080 that follows the edit argument. The following forms of the com‐
1081 mand are currently supported:
1082 pathName edit modified ?boolean?
1084 If boolean is not specified, returns the modified flag of
1085 the widget. The insert, delete, edit undo and edit redo
1086 commands or the user can set or clear the modified flag.
1087 If boolean is specified, sets the modified flag of the
1088 widget to boolean.
1089 pathName edit redo
1091 When the -undo option is true, reapplies the last undone
1092 edits provided no other edits were done since then. Gen‐
1093 erates an error when the redo stack is empty. Does noth‐
1094 ing when the -undo option is false.
1095 pathName edit reset
1097 Clears the undo and redo stacks.
1098 pathName edit separator
1100 Inserts a separator (boundary) on the undo stack. Does
1101 nothing when the -undo option is false.
1102 pathName edit undo
1104 Undoes the last edit action when the -undo option is
1105 true. An edit action is defined as all the insert and
1106 delete commands that are recorded on the undo stack in
1107 between two separators. Generates an error when the undo
1108 stack is empty. Does nothing when the -undo option is
1109 false.
1110 pathName get ?-displaychars? -- index1 ?index2 ...?
1112 Return a range of characters from the text. The return value
1113 will be all the characters in the text starting with the one
1114 whose index is index1 and ending just before the one whose index
1115 is index2 (the character at index2 will not be returned). If
1116 index2 is omitted then the single character at index1 is
1117 returned. If there are no characters in the specified range
1118 (e.g. index1 is past the end of the file or index2 is less than
1119 or equal to index1) then an empty string is returned. If the
1120 specified range contains embedded windows, no information about
1121 them is included in the returned string. If multiple index
1122 pairs are given, multiple ranges of text will be returned in a
1123 list. Invalid ranges will not be represented with empty strings
1124 in the list. The ranges are returned in the order passed to
1125 pathName get. If the -displaychars option is given, then, │
1126 within each range, only those characters which are not elided │
1127 will be returned. This may have the effect that some of the │
1128 returned ranges are empty strings.
1129 pathName image option ?arg arg ...?
1131 This command is used to manipulate embedded images. The behav‐
1132 ior of the command depends on the option argument that follows
1133 the tag argument. The following forms of the command are cur‐
1134 rently supported:
1135 pathName image cget index option
1137 Returns the value of a configuration option for an embed‐
1138 ded image. Index identifies the embedded image, and
1139 option specifies a particular configuration option, which
1140 must be one of the ones listed in the section EMBEDDED
1141 IMAGES.
1142 pathName image configure index ?option value ...?
1144 Query or modify the configuration options for an embedded
1145 image. If no option is specified, returns a list
1146 describing all of the available options for the embedded
1147 image at index (see Tk_ConfigureInfo for information on
1148 the format of this list). If option is specified with no
1149 value, then the command returns a list describing the one
1150 named option (this list will be identical to the corre‐
1151 sponding sublist of the value returned if no option is
1152 specified). If one or more option-value pairs are speci‐
1153 fied, then the command modifies the given option(s) to
1154 have the given value(s); in this case the command
1155 returns an empty string. See EMBEDDED IMAGES for infor‐
1156 mation on the options that are supported.
1157 pathName image create index ?option value ...?
1159 This command creates a new image annotation, which will
1160 appear in the text at the position given by index. Any
1161 number of option-value pairs may be specified to config‐
1162 ure the annotation. Returns a unique identifier that may
1163 be used as an index to refer to this image. See EMBEDDED
1164 IMAGES for information on the options that are supported,
1165 and a description of the identifier returned.
1166 pathName image names
1168 Returns a list whose elements are the names of all image
1169 instances currently embedded in window.
1170 pathName index index
1172 Returns the position corresponding to index in the form
1173 line.char where line is the line number and char is the charac‐
1174 ter number. Index may have any of the forms described under
1175 INDICES above.
1176 pathName insert index chars ?tagList chars tagList ...?
1178 Inserts all of the chars arguments just before the character at
1179 index. If index refers to the end of the text (the character
1180 after the last newline) then the new text is inserted just
1181 before the last newline instead. If there is a single chars
1182 argument and no tagList, then the new text will receive any tags
1183 that are present on both the character before and the character
1184 after the insertion point; if a tag is present on only one of
1185 these characters then it will not be applied to the new text.
1186 If tagList is specified then it consists of a list of tag names;
1187 the new characters will receive all of the tags in this list and
1188 no others, regardless of the tags present around the insertion
1189 point. If multiple chars-tagList argument pairs are present,
1190 they produce the same effect as if a separate pathName insert
1191 widget command had been issued for each pair, in order. The
1192 last tagList argument may be omitted.
1193 pathName mark option ?arg arg ...?
1195 This command is used to manipulate marks. The exact behavior of
1196 the command depends on the option argument that follows the mark
1197 argument. The following forms of the command are currently sup‐
1198 ported:
1199 pathName mark gravity markName ?direction?
1201 If direction is not specified, returns left or right to
1202 indicate which of its adjacent characters markName is
1203 attached to. If direction is specified, it must be left
1204 or right; the gravity of markName is set to the given
1205 value.
1206 pathName mark names
1208 Returns a list whose elements are the names of all the
1209 marks that are currently set.
1210 pathName mark next index
1212 Returns the name of the next mark at or after index. If
1213 index is specified in numerical form, then the search for
1214 the next mark begins at that index. If index is the name
1215 of a mark, then the search for the next mark begins imme‐
1216 diately after that mark. This can still return a mark at
1217 the same position if there are multiple marks at the same
1218 index. These semantics mean that the mark next operation
1219 can be used to step through all the marks in a text wid‐
1220 get in the same order as the mark information returned by
1221 the pathName dump operation. If a mark has been set to
1222 the special end index, then it appears to be after end
1223 with respect to the pathName mark next operation. An
1224 empty string is returned if there are no marks after
1225 index.
1226 pathName mark previous index
1228 Returns the name of the mark at or before index. If
1229 index is specified in numerical form, then the search for
1230 the previous mark begins with the character just before
1231 that index. If index is the name of a mark, then the
1232 search for the next mark begins immediately before that
1233 mark. This can still return a mark at the same position
1234 if there are multiple marks at the same index. These
1235 semantics mean that the pathName mark previous operation
1236 can be used to step through all the marks in a text wid‐
1237 get in the reverse order as the mark information returned
1238 by the pathName dump operation. An empty string is
1239 returned if there are no marks before index.
1240 pathName mark set markName index
1242 Sets the mark named markName to a position just before
1243 the character at index. If markName already exists, it
1244 is moved from its old position; if it does not exist, a
1245 new mark is created. This command returns an empty
1246 string.
1247 pathName mark unset markName ?markName markName ...?
1249 Remove the mark corresponding to each of the markName
1250 arguments. The removed marks will not be usable in
1251 indices and will not be returned by future calls to
1252 “pathName mark names”. This command returns an empty
1253 string.
1254 pathName peer option args
1256 This command is used to create and query widget peers. It has │
1257 two forms, depending on option: │
1258 pathName peer create newPathName ?options? │
1260 Creates a peer text widget with the given newPathName, │
1261 and any optional standard configuration options (as for │
1262 the text command). By default the peer will have the │
1263 same start and end line as the parent widget, but these │
1264 can be overridden with the standard configuration │
1265 options. │
1266 pathName peer names │
1268 Returns a list of peers of this widget (this does not │
1269 include the widget itself). The order within this list │
1270 is undefined. │
1271 pathName replace index1 index2 chars ?tagList chars tagList ...? │
1273 Replaces the range of characters between index1 and index2 with │
1274 the given characters and tags. See the section on pathName │
1275 insert for an explanation of the handling of the tagList... │
1276 arguments, and the section on pathName delete for an explanation │
1277 of the handling of the indices. If index2 corresponds to an │
1278 index earlier in the text than index1, an error will be gener‐ │
1279 ated. │
1280 The deletion and insertion are arranged so that no unnecessary │
1282 scrolling of the window or movement of insertion cursor occurs. │
1283 In addition the undo/redo stack are correctly modified, if undo │
1284 operations are active in the text widget. The command returns │
1285 an empty string. │
1286 pathName scan option args
1288 This command is used to implement scanning on texts. It has two
1289 forms, depending on option:
1290 pathName scan mark x y
1292 Records x and y and the current view in the text window,
1293 for use in conjunction with later pathName scan dragto
1294 commands. Typically this command is associated with a
1295 mouse button press in the widget. It returns an empty
1296 string.
1297 pathName scan dragto x y
1299 This command computes the difference between its x and y
1300 arguments and the x and y arguments to the last pathName
1301 scan mark command for the widget. It then adjusts the
1302 view by 10 times the difference in coordinates. This
1303 command is typically associated with mouse motion events
1304 in the widget, to produce the effect of dragging the text
1305 at high speed through the window. The return value is an
1306 empty string.
1307 pathName search ?switches? pattern index ?stopIndex?
1309 Searches the text in pathName starting at index for a range of
1310 characters that matches pattern. If a match is found, the index
1311 of the first character in the match is returned as result; oth‐
1312 erwise an empty string is returned. One or more of the follow‐
1313 ing switches (or abbreviations thereof) may be specified to con‐
1314 trol the search:
1315 -forwards
1317 The search will proceed forward through the text, finding
1318 the first matching range starting at or after the posi‐
1319 tion given by index. This is the default.
1320 -backwards
1322 The search will proceed backward through the text, find‐
1323 ing the matching range closest to index whose first char‐
1324 acter is before index (it is not allowed to be at index). │
1325 Note that, for a variety of reasons, backwards searches │
1326 can be substantially slower than forwards searches (par‐ │
1327 ticularly when using -regexp), so it is recommended that │
1328 performance-critical code use forward searches.
1329 -exact Use exact matching: the characters in the matching range
1331 must be identical to those in pattern. This is the
1332 default.
1333 -regexp
1335 Treat pattern as a regular expression and match it
1336 against the text using the rules for regular expressions
1337 (see the regexp command for details). The default match‐ │
1338 ing automatically passes both the -lineanchor and │
1339 -linestop options to the regexp engine (unless │
1340 -nolinestop is used), so that ^$ match beginning and end │
1341 of line, and ., [^ sequences will never match the newline │
1342 character \n.
1343 -nolinestop
1345 This allows . and [^ sequences to match the newline char‐ │
1346 acter \n, which they will otherwise not do (see the reg‐ │
1347 exp command for details). This option is only meaningful │
1348 if -regexp is also given, and an error will be thrown │
1349 otherwise. For example, to match the entire text, use │
1350 “pathName search -nolinestop -regexp ".*" 1.0”.
1351 -nocase
1353 Ignore case differences between the pattern and the text.
1354 -count varName
1356 The argument following -count gives the name of a vari‐
1357 able; if a match is found, the number of index positions
1358 between beginning and end of the matching range will be
1359 stored in the variable. If there are no embedded images
1360 or windows in the matching range (and there are no elided
1361 characters if -elide is not given), this is equivalent to
1362 the number of characters matched. In either case, the
1363 range matchIdx to matchIdx + $count chars will return the
1364 entire matched text.
1365 -all Find all matches in the given range and return a list of │
1367 the indices of the first character of each match. If a │
1368 -count varName switch is given, then varName is also set │
1369 to a list containing one element for each successful │
1370 match. Note that, even for exact searches, the elements │
1371 of this list may be different, if there are embedded │
1372 images, windows or hidden text. Searches with -all │
1373 behave very similarly to the Tcl command regexp -all, in │
1374 that overlapping matches are not normally returned. For │
1375 example, applying an -all search of the pattern “\w+” │
1376 against “hello there” will just match twice, once for │
1377 each word, and matching “Z[a-z]+Z” against “ZooZooZoo” │
1378 will just match once.
1379 -overlap
1381 When performing -all searches, the normal behaviour is │
1382 that matches which overlap an already-found match will │
1383 not be returned. This switch changes that behaviour so │
1384 that all matches which are not totally enclosed within │
1385 another match are returned. For example, applying an │
1386 -overlap search of the pattern “\w+” against “hello │
1387 there” will just match twice (i.e. no different to just │
1388 -all), but matching “Z[a-z]+Z” against “ZooZooZoo” will │
1389 now match twice. An error will be thrown if this switch │
1390 is used without -all.
1391 -strictlimits
1393 When performing any search, the normal behaviour is that │
1394 the start and stop limits are checked with respect to the │
1395 start of the matching text. With the -strictlimits flag, │
1396 the entire matching range must lie inside the start and │
1397 stop limits specified for the match to be valid.
1398 -elide Find elided (hidden) text as well. By default only dis‐
1400 played text is searched.
1401 -- This switch has no effect except to terminate the list of
1403 switches: the next argument will be treated as pattern
1404 even if it starts with -.
1405 The matching range may be within a single line of text, or run │
1407 across multiple lines (if parts of the pattern can match a new- │
1408 line). For regular expression matching one can use the various │
1409 newline-matching features such as $ to match the end of a line, │
1410 ^ to match the beginning of a line, and to control whether . is │
1411 allowed to match a new-line. If stopIndex is specified, the
1412 search stops at that index: for forward searches, no match at or
1413 after stopIndex will be considered; for backward searches, no
1414 match earlier in the text than stopIndex will be considered. If
1415 stopIndex is omitted, the entire text will be searched: when the
1416 beginning or end of the text is reached, the search continues at
1417 the other end until the starting location is reached again; if
1418 stopIndex is specified, no wrap-around will occur. This means
1419 that, for example, if the search is -forwards but stopIndex is
1420 earlier in the text than startIndex, nothing will ever be found.
1421 See KNOWN BUGS below for a number of minor limitations of the
1422 pathName search command.
1423 pathName see index
1425 Adjusts the view in the window so that the character given by
1426 index is completely visible. If index is already visible then
1427 the command does nothing. If index is a short distance out of
1428 view, the command adjusts the view just enough to make index
1429 visible at the edge of the window. If index is far out of view,
1430 then the command centers index in the window.
1431 pathName tag option ?arg arg ...?
1433 This command is used to manipulate tags. The exact behavior of
1434 the command depends on the option argument that follows the tag
1435 argument. The following forms of the command are currently sup‐
1436 ported:
1437 pathName tag add tagName index1 ?index2 index1 index2 ...?
1439 Associate the tag tagName with all of the characters
1440 starting with index1 and ending just before index2 (the
1441 character at index2 is not tagged). A single command may
1442 contain any number of index1-index2 pairs. If the last
1443 index2 is omitted then the single character at index1 is
1444 tagged. If there are no characters in the specified
1445 range (e.g. index1 is past the end of the file or index2
1446 is less than or equal to index1) then the command has no
1447 effect.
1448 pathName tag bind tagName ?sequence? ?script?
1450 This command associates script with the tag given by tag‐
1451 Name. Whenever the event sequence given by sequence
1452 occurs for a character that has been tagged with tagName,
1453 the script will be invoked. This widget command is simi‐
1454 lar to the bind command except that it operates on char‐
1455 acters in a text rather than entire widgets. See the
1456 bind manual entry for complete details on the syntax of
1457 sequence and the substitutions performed on script before
1458 invoking it. If all arguments are specified then a new
1459 binding is created, replacing any existing binding for
1460 the same sequence and tagName (if the first character of
1461 script is “+” then script augments an existing binding
1462 rather than replacing it). In this case the return value
1463 is an empty string. If script is omitted then the com‐
1464 mand returns the script associated with tagName and
1465 sequence (an error occurs if there is no such binding).
1466 If both script and sequence are omitted then the command
1467 returns a list of all the sequences for which bindings
1468 have been defined for tagName.
1469 The only events for which bindings may be specified are
1471 those related to the mouse and keyboard (such as Enter,
1472 Leave, ButtonPress, Motion, and KeyPress) or virtual
1473 events. Event bindings for a text widget use the current
1474 mark described under MARKS above. An Enter event trig‐
1475 gers for a tag when the tag first becomes present on the
1476 current character, and a Leave event triggers for a tag
1477 when it ceases to be present on the current character.
1478 Enter and Leave events can happen either because the cur‐
1479 rent mark moved or because the character at that position
1480 changed. Note that these events are different than Enter
1481 and Leave events for windows. Mouse and keyboard events
1482 are directed to the current character. If a virtual
1483 event is used in a binding, that binding can trigger only
1484 if the virtual event is defined by an underlying mouse-
1485 related or keyboard-related event.
1486 It is possible for the current character to have multiple
1488 tags, and for each of them to have a binding for a par‐
1489 ticular event sequence. When this occurs, one binding is
1490 invoked for each tag, in order from lowest-priority to
1491 highest priority. If there are multiple matching bind‐
1492 ings for a single tag, then the most specific binding is
1493 chosen (see the manual entry for the bind command for
1494 details). continue and break commands within binding
1495 scripts are processed in the same way as for bindings
1496 created with the bind command.
1497 If bindings are created for the widget as a whole using
1499 the bind command, then those bindings will supplement the
1500 tag bindings. The tag bindings will be invoked first,
1501 followed by bindings for the window as a whole.
1502 pathName tag cget tagName option
1504 This command returns the current value of the option
1505 named option associated with the tag given by tagName.
1506 Option may have any of the values accepted by the path‐
1507 Name tag configure widget command.
1508 pathName tag configure tagName ?option? ?value? ?option value
1510 ...?
1511 This command is similar to the pathName configure widget
1512 command except that it modifies options associated with
1513 the tag given by tagName instead of modifying options for
1514 the overall text widget. If no option is specified, the
1515 command returns a list describing all of the available
1516 options for tagName (see Tk_ConfigureInfo for information
1517 on the format of this list). If option is specified with
1518 no value, then the command returns a list describing the
1519 one named option (this list will be identical to the cor‐
1520 responding sublist of the value returned if no option is
1521 specified). If one or more option-value pairs are speci‐
1522 fied, then the command modifies the given option(s) to
1523 have the given value(s) in tagName; in this case the com‐
1524 mand returns an empty string. See TAGS above for details
1525 on the options available for tags.
1526 pathName tag delete tagName ?tagName ...?
1528 Deletes all tag information for each of the tagName argu‐
1529 ments. The command removes the tags from all characters
1530 in the file and also deletes any other information asso‐
1531 ciated with the tags, such as bindings and display infor‐
1532 mation. The command returns an empty string.
1533 pathName tag lower tagName ?belowThis?
1535 Changes the priority of tag tagName so that it is just
1536 lower in priority than the tag whose name is belowThis.
1537 If belowThis is omitted, then tagName's priority is
1538 changed to make it lowest priority of all tags.
1539 pathName tag names ?index?
1541 Returns a list whose elements are the names of all the
1542 tags that are active at the character position given by
1543 index. If index is omitted, then the return value will
1544 describe all of the tags that exist for the text (this
1545 includes all tags that have been named in a “pathName
1546 tag” widget command but have not been deleted by a “path‐
1547 Name tag delete” widget command, even if no characters
1548 are currently marked with the tag). The list will be
1549 sorted in order from lowest priority to highest priority.
1550 pathName tag nextrange tagName index1 ?index2?
1552 This command searches the text for a range of characters
1553 tagged with tagName where the first character of the
1554 range is no earlier than the character at index1 and no
1555 later than the character just before index2 (a range
1556 starting at index2 will not be considered). If several
1557 matching ranges exist, the first one is chosen. The com‐
1558 mand's return value is a list containing two elements,
1559 which are the index of the first character of the range
1560 and the index of the character just after the last one in
1561 the range. If no matching range is found then the return
1562 value is an empty string. If index2 is not given then it
1563 defaults to the end of the text.
1564 pathName tag prevrange tagName index1 ?index2?
1566 This command searches the text for a range of characters
1567 tagged with tagName where the first character of the
1568 range is before the character at index1 and no earlier
1569 than the character at index2 (a range starting at index2
1570 will be considered). If several matching ranges exist,
1571 the one closest to index1 is chosen. The command's
1572 return value is a list containing two elements, which are
1573 the index of the first character of the range and the
1574 index of the character just after the last one in the
1575 range. If no matching range is found then the return
1576 value is an empty string. If index2 is not given then it
1577 defaults to the beginning of the text.
1578 pathName tag raise tagName ?aboveThis?
1580 Changes the priority of tag tagName so that it is just
1581 higher in priority than the tag whose name is aboveThis.
1582 If aboveThis is omitted, then tagName's priority is
1583 changed to make it highest priority of all tags.
1584 pathName tag ranges tagName
1586 Returns a list describing all of the ranges of text that
1587 have been tagged with tagName. The first two elements of
1588 the list describe the first tagged range in the text, the
1589 next two elements describe the second range, and so on.
1590 The first element of each pair contains the index of the
1591 first character of the range, and the second element of
1592 the pair contains the index of the character just after
1593 the last one in the range. If there are no characters
1594 tagged with tag then an empty string is returned.
1595 pathName tag remove tagName index1 ?index2 index1 index2 ...?
1597 Remove the tag tagName from all of the characters start‐
1598 ing at index1 and ending just before index2 (the charac‐
1599 ter at index2 is not affected). A single command may
1600 contain any number of index1-index2 pairs. If the last
1601 index2 is omitted then the tag is removed from the single
1602 character at index1. If there are no characters in the
1603 specified range (e.g. index1 is past the end of the file
1604 or index2 is less than or equal to index1) then the com‐
1605 mand has no effect. This command returns an empty
1606 string.
1607 pathName window option ?arg arg ...?
1609 This command is used to manipulate embedded windows. The behav‐
1610 ior of the command depends on the option argument that follows
1611 the tag argument. The following forms of the command are cur‐
1612 rently supported:
1613 pathName window cget index option
1615 Returns the value of a configuration option for an embed‐
1616 ded window. Index identifies the embedded window, and
1617 option specifies a particular configuration option, which
1618 must be one of the ones listed in the section EMBEDDED
1619 WINDOWS.
1620 pathName window configure index ?option value ...?
1622 Query or modify the configuration options for an embedded
1623 window. If no option is specified, returns a list
1624 describing all of the available options for the embedded
1625 window at index (see Tk_ConfigureInfo for information on
1626 the format of this list). If option is specified with no
1627 value, then the command returns a list describing the one
1628 named option (this list will be identical to the corre‐
1629 sponding sublist of the value returned if no option is
1630 specified). If one or more option-value pairs are speci‐
1631 fied, then the command modifies the given option(s) to
1632 have the given value(s); in this case the command
1633 returns an empty string. See EMBEDDED WINDOWS for infor‐
1634 mation on the options that are supported.
1635 pathName window create index ?option value ...?
1637 This command creates a new window annotation, which will
1638 appear in the text at the position given by index. Any
1639 number of option-value pairs may be specified to config‐
1640 ure the annotation. See EMBEDDED WINDOWS for information
1641 on the options that are supported. Returns an empty
1642 string.
1643 pathName window names
1645 Returns a list whose elements are the names of all win‐
1646 dows currently embedded in window.
1647 pathName xview option args
1649 This command is used to query and change the horizontal position
1650 of the text in the widget's window. It can take any of the fol‐
1651 lowing forms:
1652 pathName xview
1654 Returns a list containing two elements. Each element is
1655 a real fraction between 0 and 1; together they describe
1656 the portion of the document's horizontal span that is
1657 visible in the window. For example, if the first element
1658 is .2 and the second element is .6, 20% of the text is
1659 off-screen to the left, the middle 40% is visible in the
1660 window, and 40% of the text is off-screen to the right.
1661 The fractions refer only to the lines that are actually
1662 visible in the window: if the lines in the window are
1663 all very short, so that they are entirely visible, the
1664 returned fractions will be 0 and 1, even if there are
1665 other lines in the text that are much wider than the win‐
1666 dow. These are the same values passed to scrollbars via
1667 the -xscrollcommand option.
1668 pathName xview moveto fraction
1670 Adjusts the view in the window so that fraction of the
1671 horizontal span of the text is off-screen to the left.
1672 Fraction is a fraction between 0 and 1.
1673 pathName xview scroll number what
1675 This command shifts the view in the window left or right
1676 according to number and what. What must be units, pages
1677 or pixels. If what is units or pages then number must be │
1678 an integer, otherwise number may be specified in any of │
1679 the forms acceptable to Tk_GetPixels, such as “2.0c” or │
1680 “1i” (the result is rounded to the nearest integer value. │
1681 If no units are given, pixels are assumed). If what is │
1682 units, the view adjusts left or right by number average- │
1683 width characters on the display; if it is pages then the │
1684 view adjusts by number screenfuls; if it is pixels then │
1685 the view adjusts by number pixels. If number is negative
1686 then characters farther to the left become visible; if it
1687 is positive then characters farther to the right become
1688 visible.
1689 pathName yview ?args?
1691 This command is used to query and change the vertical position
1692 of the text in the widget's window. It can take any of the fol‐
1693 lowing forms:
1694 pathName yview
1696 Returns a list containing two elements, both of which are
1697 real fractions between 0 and 1. The first element gives
1698 the position of the first visible pixel of the first
1699 character (or image, etc) in the top line in the window,
1700 relative to the text as a whole (0.5 means it is halfway
1701 through the text, for example). The second element gives
1702 the position of the first pixel just after the last visi‐
1703 ble one in the bottom line of the window, relative to the
1704 text as a whole. These are the same values passed to
1705 scrollbars via the -yscrollcommand option.
1706 pathName yview moveto fraction
1708 Adjusts the view in the window so that the pixel given by
1709 fraction appears at the top of the top line of the win‐
1710 dow. Fraction is a fraction between 0 and 1; 0 indi‐
1711 cates the first pixel of the first character in the text,
1712 0.33 indicates the pixel that is one-third the way
1713 through the text; and so on. Values close to 1 will │
1714 indicate values close to the last pixel in the text (1 │
1715 actually refers to one pixel beyond the last pixel), but │
1716 in such cases the widget will never scroll beyond the │
1717 last pixel, and so a value of 1 will effectively be │
1718 rounded back to whatever fraction ensures the last pixel │
1719 is at the bottom of the window, and some other pixel is │
1720 at the top.
1721 pathName yview scroll number what
1723 This command adjust the view in the window up or down
1724 according to number and what. What must be units, pages
1725 or pixels. If what is units or pages then number must be │
1726 an integer, otherwise number may be specified in any of │
1727 the forms acceptable to Tk_GetPixels, such as “2.0c” or │
1728 “1i” (the result is rounded to the nearest integer value. │
1729 If no units are given, pixels are assumed). If what is │
1730 units, the view adjusts up or down by number lines on the │
1731 display; if it is pages then the view adjusts by number │
1732 screenfuls; if it is pixels then the view adjusts by num‐ │
1733 ber pixels. If number is negative then earlier positions
1734 in the text become visible; if it is positive then later
1735 positions in the text become visible.
1736 pathName yview ?-pickplace? index
1738 Changes the view in the widget's window to make index
1739 visible. If the -pickplace option is not specified then
1740 index will appear at the top of the window. If -pick‐
1741 place is specified then the widget chooses where index
1742 appears in the window:
1743 [1] If index is already visible somewhere in the win‐
1745 dow then the command does nothing.
1746 [2] If index is only a few lines off-screen above the
1748 window then it will be positioned at the top of
1749 the window.
1750 [3] If index is only a few lines off-screen below the
1752 window then it will be positioned at the bottom of
1753 the window.
1754 [4] Otherwise, index will be centered in the window.
1756 The -pickplace option has been obsoleted by the pathName
1758 see widget command (pathName see handles both x- and y-
1759 motion to make a location visible, whereas the -pickplace
1760 mode only handles motion in y).
1761 pathName yview number
1763 This command makes the first character on the line after
1764 the one given by number visible at the top of the window.
1765 Number must be an integer. This command used to be used
1766 for scrolling, but now it is obsolete.
1767
1769 Tk automatically creates class bindings for texts that give them the
1770 following default behavior. In the descriptions below, “word” is
1771 dependent on the value of the tcl_wordchars variable. See tclvars(n).
1772 [1] Clicking mouse button 1 positions the insertion cursor just
1774 before the character underneath the mouse cursor, sets the input
1775 focus to this widget, and clears any selection in the widget.
1776 Dragging with mouse button 1 strokes out a selection between the
1777 insertion cursor and the character under the mouse.
1778 [2] Double-clicking with mouse button 1 selects the word under the
1780 mouse and positions the insertion cursor at the start of the
1781 word. Dragging after a double click will stroke out a selection
1782 consisting of whole words.
1783 [3] Triple-clicking with mouse button 1 selects the line under the
1785 mouse and positions the insertion cursor at the start of the
1786 line. Dragging after a triple click will stroke out a selection
1787 consisting of whole lines.
1788 [4] The ends of the selection can be adjusted by dragging with mouse
1790 button 1 while the Shift key is down; this will adjust the end
1791 of the selection that was nearest to the mouse cursor when but‐
1792 ton 1 was pressed. If the button is double-clicked before drag‐
1793 ging then the selection will be adjusted in units of whole
1794 words; if it is triple-clicked then the selection will be
1795 adjusted in units of whole lines.
1796 [5] Clicking mouse button 1 with the Control key down will reposi‐
1798 tion the insertion cursor without affecting the selection.
1799 [6] If any normal printing characters are typed, they are inserted
1801 at the point of the insertion cursor.
1802 [7] The view in the widget can be adjusted by dragging with mouse
1804 button 2. If mouse button 2 is clicked without moving the
1805 mouse, the selection is copied into the text at the position of
1806 the mouse cursor. The Insert key also inserts the selection,
1807 but at the position of the insertion cursor.
1808 [8] If the mouse is dragged out of the widget while button 1 is
1810 pressed, the entry will automatically scroll to make more text
1811 visible (if there is more text off-screen on the side where the
1812 mouse left the window).
1813 [9] The Left and Right keys move the insertion cursor one character
1815 to the left or right; they also clear any selection in the
1816 text. If Left or Right is typed with the Shift key down, then
1817 the insertion cursor moves and the selection is extended to
1818 include the new character. Control-Left and Control-Right move
1819 the insertion cursor by words, and Control-Shift-Left and Con‐
1820 trol-Shift-Right move the insertion cursor by words and also
1821 extend the selection. Control-b and Control-f behave the same
1822 as Left and Right, respectively. Meta-b and Meta-f behave the
1823 same as Control-Left and Control-Right, respectively.
1824 [10] The Up and Down keys move the insertion cursor one line up or
1826 down and clear any selection in the text. If Up or Right is
1827 typed with the Shift key down, then the insertion cursor moves
1828 and the selection is extended to include the new character.
1829 Control-Up and Control-Down move the insertion cursor by para‐
1830 graphs (groups of lines separated by blank lines), and Control-
1831 Shift-Up and Control-Shift-Down move the insertion cursor by
1832 paragraphs and also extend the selection. Control-p and Con‐
1833 trol-n behave the same as Up and Down, respectively.
1834 [11] The Next and Prior keys move the insertion cursor forward or
1836 backwards by one screenful and clear any selection in the text.
1837 If the Shift key is held down while Next or Prior is typed, then
1838 the selection is extended to include the new character.
1839 [12] Control-Next and Control-Prior scroll the view right or left by
1841 one page without moving the insertion cursor or affecting the
1842 selection.
1843 [13] Home and Control-a move the insertion cursor to the beginning of
1845 its display line and clear any selection in the widget. Shift-
1846 Home moves the insertion cursor to the beginning of the display
1847 line and also extends the selection to that point.
1848 [14] End and Control-e move the insertion cursor to the end of the
1850 display line and clear any selection in the widget. Shift-End
1851 moves the cursor to the end of the display line and extends the
1852 selection to that point.
1853 [15] Control-Home and Meta-< move the insertion cursor to the begin‐
1855 ning of the text and clear any selection in the widget. Con‐
1856 trol-Shift-Home moves the insertion cursor to the beginning of
1857 the text and also extends the selection to that point.
1858 [16] Control-End and Meta-> move the insertion cursor to the end of
1860 the text and clear any selection in the widget. Control-Shift-
1861 End moves the cursor to the end of the text and extends the
1862 selection to that point.
1863 [17] The Select key and Control-Space set the selection anchor to the
1865 position of the insertion cursor. They do not affect the cur‐
1866 rent selection. Shift-Select and Control-Shift-Space adjust the
1867 selection to the current position of the insertion cursor,
1868 selecting from the anchor to the insertion cursor if there was
1869 not any selection previously.
1870 [18] Control-/ selects the entire contents of the widget.
1872 [19] Control-\ clears any selection in the widget.
1874 [20] The F16 key (labelled Copy on many Sun workstations) or Meta-w
1876 copies the selection in the widget to the clipboard, if there is
1877 a selection. This action is carried out by the command
1878 tk_textCopy.
1879 [21] The F20 key (labelled Cut on many Sun workstations) or Control-w
1881 copies the selection in the widget to the clipboard and deletes
1882 the selection. This action is carried out by the command
1883 tk_textCut. If there is no selection in the widget then these
1884 keys have no effect.
1885 [22] The F18 key (labelled Paste on many Sun workstations) or Con‐
1887 trol-y inserts the contents of the clipboard at the position of
1888 the insertion cursor. This action is carried out by the command
1889 tk_textPaste.
1890 [23] The Delete key deletes the selection, if there is one in the
1892 widget. If there is no selection, it deletes the character to
1893 the right of the insertion cursor.
1894 [24] Backspace and Control-h delete the selection, if there is one in
1896 the widget. If there is no selection, they delete the character
1897 to the left of the insertion cursor.
1898 [25] Control-d deletes the character to the right of the insertion
1900 cursor.
1901 [26] Meta-d deletes the word to the right of the insertion cursor.
1903 [27] Control-k deletes from the insertion cursor to the end of its
1905 line; if the insertion cursor is already at the end of a line,
1906 then Control-k deletes the newline character.
1907 [28] Control-o opens a new line by inserting a newline character in
1909 front of the insertion cursor without moving the insertion cur‐
1910 sor.
1911 [29] Meta-backspace and Meta-Delete delete the word to the left of
1913 the insertion cursor.
1914 [30] Control-x deletes whatever is selected in the text widget after
1916 copying it to the clipboard.
1917 [31] Control-t reverses the order of the two characters to the right
1919 of the insertion cursor.
1920 [32] Control-z (and Control-underscore on UNIX when tk_strictMotif is
1922 true) undoes the last edit action if the -undo option is true.
1923 Does nothing otherwise.
1924 [33] Control-Z (or Control-y on Windows) reapplies the last undone
1926 edit action if the -undo option is true. Does nothing otherwise.
1927 If the widget is disabled using the -state option, then its view can
1929 still be adjusted and text can still be selected, but no insertion cur‐
1930 sor will be displayed and no text modifications will take place.
1931 The behavior of texts can be changed by defining new bindings for indi‐
1933 vidual widgets or by redefining the class bindings.
1934
1936 ISSUES CONCERNING CHARS AND INDICES
1937 Before Tk 8.5, the widget used the string “chars” to refer to index │
1938 positions (which included characters, embedded windows and embedded │
1939 images). As of Tk 8.5 the text widget deals separately and correctly │
1940 with “chars” and “indices”. For backwards compatibility, however, the │
1941 index modifiers “+N chars” and “-N chars” continue to refer to indices. │
1942 One must use any of the full forms “+N any chars” or “-N any chars” │
1943 etc. to refer to actual character indices. This confusion may be fixed │
1944 in a future release by making the widget correctly interpret “+N chars” │
1945 as a synonym for “+N any chars”.
1946 PERFORMANCE ISSUES
1948 Text widgets should run efficiently under a variety of conditions. The
1949 text widget uses about 2-3 bytes of main memory for each byte of text,
1950 so texts containing a megabyte or more should be practical on most
1951 workstations. Text is represented internally with a modified B-tree
1952 structure that makes operations relatively efficient even with large
1953 texts. Tags are included in the B-tree structure in a way that allows
1954 tags to span large ranges or have many disjoint smaller ranges without
1955 loss of efficiency. Marks are also implemented in a way that allows
1956 large numbers of marks. In most cases it is fine to have large numbers
1957 of unique tags, or a tag that has many distinct ranges.
1958 One performance problem can arise if you have hundreds or thousands of
1960 different tags that all have the following characteristics: the first
1961 and last ranges of each tag are near the beginning and end of the text,
1962 respectively, or a single tag range covers most of the text widget.
1963 The cost of adding and deleting tags like this is proportional to the
1964 number of other tags with the same properties. In contrast, there is
1965 no problem with having thousands of distinct tags if their overall
1966 ranges are localized and spread uniformly throughout the text.
1967 Very long text lines can be expensive, especially if they have many
1969 marks and tags within them.
1970 The display line with the insert cursor is redrawn each time the cursor
1972 blinks, which causes a steady stream of graphics traffic. Set the
1973 insertOffTime attribute to 0 avoid this.
1974 KNOWN BUGS
1976 The pathName search -regexp sub-command attempts to perform sophisti‐ │
1977 cated regexp matching across multiple lines in an efficient fashion │
1978 (since Tk 8.5), examining each line individually, and then in small │
1979 groups of lines, whether searching forwards or backwards. Under cer‐ │
1980 tain conditions the search result might differ from that obtained by │
1981 applying the same regexp to the entire text from the widget in one go. │
1982 For example, when searching with a greedy regexp, the widget will con‐ │
1983 tinue to attempt to add extra lines to the match as long as one of two │
1984 conditions are true: either Tcl's regexp library returns a code to │
1985 indicate a longer match is possible (but there are known bugs in Tcl │
1986 which mean this code is not always correctly returned); or if each │
1987 extra line added results in at least a partial match with the pattern. │
1988 This means in the case where the first extra line added results in no │
1989 match and Tcl's regexp system returns the incorrect code and adding a │
1990 second extra line would actually match, the text widget will return the │
1991 wrong result. In practice this is a rare problem, but it can occur, │
1992 for example: │
1993 pack [text .t] │
1994 .t insert 1.0 "aaaa\nbbbb\ncccc\nbbbb\naaaa\n" │
1995 .t search -regexp -- {(a+|b+\nc+\nb+)+\na+} 1.0 │
1996 will not find a match when one exists of 19 characters starting from │
1997 the first “b”. │
1998 Whenever one possible match is fully enclosed in another, the search │
2000 command will attempt to ensure only the larger match is returned. When │
2001 performing backwards regexp searches it is possible that Tcl will not │
2002 always achieve this, in the case where a match is preceded by one or │
2003 more short, non-overlapping matches, all of which are preceded by a │
2004 large match which actually encompasses all of them. The search algo‐ │
2005 rithm used by the widget does not look back arbitrarily far for a pos‐ │
2006 sible match which might cover large portions of the widget. For exam‐ │
2007 ple: │
2008 pack [text .t] │
2009 .t insert 1.0 "aaaa\nbbbb\nbbbb\nbbbb\nbbbb\n" │
2010 .t search -regexp -backward -- {b+\n|a+\n(b+\n)+} end │
2011 matches at “5.0” when a true greedy match would match at “1.0”. Simi‐ │
2012 larly if we add -all to this case, it matches at all of “5.0”, “4.0”, │
2013 “3.0” and “1.0”, when really it should only match at “1.0” since that │
2014 match encloses all the others.
2015
2017 entry(n), scrollbar(n)
2018
2020 text, widget, tkvars
2021Tk 8.5 text(n)