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. [-height height] Specifies the
33 desired height for the window, in units of characters in the font given
34 by the -font option. Must be at least one. [-maxundo maxUndo] Speci‐ │
35 fies the maximum number of compound undo actions on the undo stack. A │
36 zero or a negative value imply an unlimited undo stack. [-spac‐
37 ing1 spacing1] Requests additional space above each text line in the
38 widget, using any of the standard forms for screen distances. If a
39 line wraps, this option only applies to the first line on the display.
40 This option may be overridden with -spacing1 options in tags. [-spac‐
41 ing2 spacing2] For lines that wrap (so that they cover more than one
42 line on the display) this option specifies additional space to provide
43 between the display lines that represent a single line of text. The
44 value may have any of the standard forms for screen distances. This
45 option may be overridden with -spacing2 options in tags. [-spac‐
46 ing3 spacing3] Requests additional space below each text line in the
47 widget, using any of the standard forms for screen distances. If a
48 line wraps, this option only applies to the last line on the display.
49 This option may be overridden with -spacing3 options in tags.
50 [-state state] Specifies one of two states for the text: normal or
51 disabled. If the text is disabled then characters may not be inserted
52 or deleted and no insertion cursor will be displayed, even if the input
53 focus is in the widget. [-tabs tabs] Specifies a set of tab stops for
54 the window. The option's value consists of a list of screen distances
55 giving the positions of the tab stops, each of which is a distance rel‐
56 ative to the left edge of the widget (excluding borders, padding, etc).
57 Each position may optionally be followed in the next list element by
58 one of the keywords left, right, center, or numeric, which specifies
59 how to justify text relative to the tab stop. Left is the default; it
60 causes the text following the tab character to be positioned with its
61 left edge at the tab position. Right means that the right edge of the
62 text following the tab character is positioned at the tab position, and
63 center means that the text is centered at the tab position. Numeric
64 means that the decimal point in the text is positioned at the tab posi‐
65 tion; if there is no decimal point then the least significant digit of
66 the number is positioned just to the left of the tab position; if
67 there is no number in the text then the text is right-justified at the
68 tab position. For example, -tabs {2c left 4c 6c center} creates three
69 tab stops at two-centimeter intervals; the first two use left justifi‐
70 cation and the third uses center justification. If the list of tab
71 stops does not have enough elements to cover all of the tabs in a text
72 line, then Tk extrapolates new tab stops using the spacing and align‐
73 ment from the last tab stop in the list. Tab distances must be
74 strictly positive, and must always increase from one tab stop to the
75 next (if not, an error is thrown). The value of the tabs option may be
76 overridden by -tabs options in tags. If no -tabs option is specified,
77 or if it is specified as an empty list, then Tk uses default tabs
78 spaced every eight (average size) characters. [-undo undo] Specifies a │
79 boolean that says whether the undo mechanism is active or not.
80 [-width width] Specifies the desired width for the window in units of
81 characters in the font given by the -font option. If the font doesn't
82 have a uniform width then the width of the character ``0'' is used in
83 translating from character units to screen units. [-wrap wrap] Speci‐
84 fies how to handle lines in the text that are too long to be displayed
85 in a single line of the text's window. The value must be none or char
86 or word. A wrap mode of none means that each line of text appears as
87 exactly one line on the screen; extra characters that don't fit on the
88 screen are not displayed. In the other modes each line of text will be
89 broken up into several screen lines if necessary to keep all the char‐
90 acters visible. In char mode a screen line break may occur after any
91 character; in word mode a line break will only be made at word bound‐
92 aries.
93_________________________________________________________________
94
97 The text command creates a new window (given by the pathName argument)
98 and makes it into a text widget. Additional options, described above,
99 may be specified on the command line or in the option database to con‐
100 figure aspects of the text such as its default background color and
101 relief. The text command returns the path name of the new window.
102 A text widget displays one or more lines of text and allows that text
104 to be edited. Text widgets support four different kinds of annotations
105 on the text, called tags, marks, embedded windows or embedded images.
106 Tags allow different portions of the text to be displayed with differ‐
107 ent fonts and colors. In addition, Tcl commands can be associated with
108 tags so that scripts are invoked when particular actions such as key‐
109 strokes and mouse button presses occur in particular ranges of the
110 text. See TAGS below for more details.
111 The second form of annotation consists of floating markers in the text
113 called "marks". Marks are used to keep track of various interesting
114 positions in the text as it is edited. See MARKS below for more
115 details.
116 The third form of annotation allows arbitrary windows to be embedded in
118 a text widget. See EMBEDDED WINDOWS below for more details.
119 The fourth form of annotation allows Tk images to be embedded in a text
121 widget. See EMBEDDED IMAGES below for more details.
122 The text widget also has a built-in undo/redo mechanism. See THE UNDO │
124 MECHANISM below for more details.
125
127 Many of the widget commands for texts take one or more indices as argu‐
128 ments. An index is a string used to indicate a particular place within
129 a text, such as a place to insert characters or one endpoint of a range
130 of characters to delete. Indices have the syntax
131 base modifier modifier modifier ...
132 Where base gives a starting point and the modifiers adjust the index
133 from the starting point (e.g. move forward or backward one character).
134 Every index must contain a base, but the modifiers are optional.
135 The base for an index must have one of the following forms:
137 line.char Indicates char'th character on line line. Lines are num‐
139 bered from 1 for consistency with other UNIX programs that
140 use this numbering scheme. Within a line, characters are
141 numbered from 0. If char is end then it refers to the new‐
142 line character that ends the line.
143 @x,y Indicates the character that covers the pixel whose x and y
145 coordinates within the text's window are x and y.
146 end Indicates the end of the text (the character just after the
148 last newline).
149 mark Indicates the character just after the mark whose name is
151 mark.
152 tag.first Indicates the first character in the text that has been
154 tagged with tag. This form generates an error if no char‐
155 acters are currently tagged with tag.
156 tag.last Indicates the character just after the last one in the text
158 that has been tagged with tag. This form generates an
159 error if no characters are currently tagged with tag.
160 pathName Indicates the position of the embedded window whose name is
162 pathName. This form generates an error if there is no
163 embedded window by the given name.
164 imageName Indicates the position of the embedded image whose name is
166 imageName. This form generates an error if there is no
167 embedded image by the given name.
168 If the base could match more than one of the above forms, such as a
170 mark and imageName both having the same value, then the form earlier in
171 the above list takes precedence. If modifiers follow the base index,
172 each one of them must have one of the forms listed below. Keywords
173 such as chars and wordend may be abbreviated as long as the abbrevia‐
174 tion is unambiguous.
175 + count chars
177 Adjust the index forward by count characters, moving to later
178 lines in the text if necessary. If there are fewer than count
179 characters in the text after the current index, then set the
180 index to the last character in the text. Spaces on either side
181 of count are optional.
182 - count chars
184 Adjust the index backward by count characters, moving to earlier
185 lines in the text if necessary. If there are fewer than count
186 characters in the text before the current index, then set the
187 index to the first character in the text. Spaces on either side
188 of count are optional.
189 + count lines
191 Adjust the index forward by count lines, retaining the same
192 character position within the line. If there are fewer than
193 count lines after the line containing the current index, then
194 set the index to refer to the same character position on the
195 last line of the text. Then, if the line is not long enough to
196 contain a character at the indicated character position, adjust
197 the character position to refer to the last character of the
198 line (the newline). Spaces on either side of count are
199 optional.
200 - count lines
202 Adjust the index backward by count lines, retaining the same
203 character position within the line. If there are fewer than
204 count lines before the line containing the current index, then
205 set the index to refer to the same character position on the
206 first line of the text. Then, if the line is not long enough to
207 contain a character at the indicated character position, adjust
208 the character position to refer to the last character of the
209 line (the newline). Spaces on either side of count are
210 optional.
211 linestart
213 Adjust the index to refer to the first character on the line.
214 lineend
216 Adjust the index to refer to the last character on the line (the
217 newline).
218 wordstart
220 Adjust the index to refer to the first character of the word
221 containing the current index. A word consists of any number of
222 adjacent characters that are letters, digits, or underscores, or
223 a single character that is not one of these.
224 wordend
226 Adjust the index to refer to the character just after the last
227 one of the word containing the current index. If the current
228 index refers to the last character of the text then it is not
229 modified.
230 If more than one modifier is present then they are applied in left-to-
232 right order. For example, the index ``end - 1 chars'' refers to the
233 next-to-last character in the text and ``insert wordstart - 1 c''
234 refers to the character just before the first one in the word contain‐
235 ing the insertion cursor. Modifiers are applied one by one in this
236 left to right order, and after each step the resulting index is con‐
237 strained to be a valid index in the text widget. So, for example, the
238 index ``1.0 -1c +1c'' refers to the index ``2.0''.
239
241 The first form of annotation in text widgets is a tag. A tag is a tex‐
242 tual string that is associated with some of the characters in a text.
243 Tags may contain arbitrary characters, but it is probably best to avoid
244 using the characters `` '' (space), +, or -: these characters have spe‐
245 cial meaning in indices, so tags containing them can't be used as
246 indices. There may be any number of tags associated with characters in
247 a text. Each tag may refer to a single character, a range of charac‐
248 ters, or several ranges of characters. An individual character may
249 have any number of tags associated with it.
250 A priority order is defined among tags, and this order is used in
252 implementing some of the tag-related functions described below. When a
253 tag is defined (by associating it with characters or setting its dis‐
254 play options or binding commands to it), it is given a priority higher
255 than any existing tag. The priority order of tags may be redefined
256 using the ``pathName tag raise'' and ``pathName tag lower'' widget com‐
257 mands.
258 Tags serve three purposes in text widgets. First, they control the way
260 information is displayed on the screen. By default, characters are
261 displayed as determined by the background, font, and foreground options
262 for the text widget. However, display options may be associated with
263 individual tags using the ``pathName tag configure'' widget command.
264 If a character has been tagged, then the display options associated
265 with the tag override the default display style. The following options
266 are currently supported for tags:
267 -background color
269 Color specifies the background color to use for characters asso‐
270 ciated with the tag. It may have any of the forms accepted by
271 Tk_GetColor.
272 -bgstipple bitmap
274 Bitmap specifies a bitmap that is used as a stipple pattern for
275 the background. It may have any of the forms accepted by
276 Tk_GetBitmap. If bitmap hasn't been specified, or if it is
277 specified as an empty string, then a solid fill will be used for
278 the background.
279 -borderwidth pixels
281 Pixels specifies the width of a 3-D border to draw around the
282 background. It may have any of the forms accepted by Tk_GetPix‐
283 els. This option is used in conjunction with the -relief option
284 to give a 3-D appearance to the background for characters; it is
285 ignored unless the -background option has been set for the tag.
286 -elide boolean
288 Elide specifies whether the data should be elided. Elided data
289 is not displayed and takes no space on screen, but further on
290 behaves just as normal data.
291 -fgstipple bitmap
293 Bitmap specifies a bitmap that is used as a stipple pattern when
294 drawing text and other foreground information such as under‐
295 lines. It may have any of the forms accepted by Tk_GetBitmap.
296 If bitmap hasn't been specified, or if it is specified as an
297 empty string, then a solid fill will be used.
298 -font fontName
300 FontName is the name of a font to use for drawing characters.
301 It may have any of the forms accepted by Tk_GetFont.
302 -foreground color
304 Color specifies the color to use when drawing text and other
305 foreground information such as underlines. It may have any of
306 the forms accepted by Tk_GetColor.
307 -justify justify
309 If the first character of a display line has a tag for which
310 this option has been specified, then justify determines how to
311 justify the line. It must be one of left, right, or center. If
312 a line wraps, then the justification for each line on the dis‐
313 play is determined by the first character of that display line.
314 -lmargin1 pixels
316 If the first character of a text line has a tag for which this
317 option has been specified, then pixels specifies how much the
318 line should be indented from the left edge of the window. Pix‐
319 els may have any of the standard forms for screen distances. If
320 a line of text wraps, this option only applies to the first line
321 on the display; the -lmargin2 option controls the indentation
322 for subsequent lines.
323 -lmargin2 pixels
325 If the first character of a display line has a tag for which
326 this option has been specified, and if the display line is not
327 the first for its text line (i.e., the text line has wrapped),
328 then pixels specifies how much the line should be indented from
329 the left edge of the window. Pixels may have any of the stan‐
330 dard forms for screen distances. This option is only used when
331 wrapping is enabled, and it only applies to the second and later
332 display lines for a text line.
333 -offset pixels
335 Pixels specifies an amount by which the text's baseline should
336 be offset vertically from the baseline of the overall line, in
337 pixels. For example, a positive offset can be used for super‐
338 scripts and a negative offset can be used for subscripts. Pix‐
339 els may have any of the standard forms for screen distances.
340 -overstrike boolean
342 Specifies whether or not to draw a horizontal rule through the
343 middle of characters. Boolean may have any of the forms
344 accepted by Tcl_GetBoolean.
345 -relief relief
347 Relief specifies the 3-D relief to use for drawing backgrounds,
348 in any of the forms accepted by Tk_GetRelief. This option is
349 used in conjunction with the -borderwidth option to give a 3-D
350 appearance to the background for characters; it is ignored
351 unless the -background option has been set for the tag.
352 -rmargin pixels
354 If the first character of a display line has a tag for which
355 this option has been specified, then pixels specifies how wide a
356 margin to leave between the end of the line and the right edge
357 of the window. Pixels may have any of the standard forms for
358 screen distances. This option is only used when wrapping is
359 enabled. If a text line wraps, the right margin for each line
360 on the display is determined by the first character of that dis‐
361 play line.
362 -spacing1 pixels
364 Pixels specifies how much additional space should be left above
365 each text line, using any of the standard forms for screen dis‐
366 tances. If a line wraps, this option only applies to the first
367 line on the display.
368 -spacing2 pixels
370 For lines that wrap, this option specifies how much additional
371 space to leave between the display lines for a single text line.
372 Pixels may have any of the standard forms for screen distances.
373 -spacing3 pixels
375 Pixels specifies how much additional space should be left below
376 each text line, using any of the standard forms for screen dis‐
377 tances. If a line wraps, this option only applies to the last
378 line on the display.
379 -tabs tabList
381 TabList specifies a set of tab stops in the same form as for the
382 -tabs option for the text widget. This option only applies to a
383 display line if it applies to the first character on that dis‐
384 play line. If this option is specified as an empty string, it
385 cancels the option, leaving it unspecified for the tag (the
386 default). If the option is specified as a non-empty string that
387 is an empty list, such as -tags { }, then it requests default
388 8-character tabs as described for the tags widget option.
389 -underline boolean
391 Boolean specifies whether or not to draw an underline underneath
392 characters. It may have any of the forms accepted by Tcl_Get‐
393 Boolean.
394 -wrap mode
396 Mode specifies how to handle lines that are wider than the
397 text's window. It has the same legal values as the -wrap option
398 for the text widget: none, char, or word. If this tag option
399 is specified, it overrides the -wrap option for the text widget.
400 If a character has several tags associated with it, and if their dis‐
402 play options conflict, then the options of the highest priority tag are
403 used. If a particular display option hasn't been specified for a par‐
404 ticular tag, or if it is specified as an empty string, then that option
405 will never be used; the next-highest-priority tag's option will used
406 instead. If no tag specifies a particular display option, then the
407 default style for the widget will be used.
408 The second purpose for tags is event bindings. You can associate bind‐
410 ings with a tag in much the same way you can associate bindings with a
411 widget class: whenever particular X events occur on characters with
412 the given tag, a given Tcl command will be executed. Tag bindings can
413 be used to give behaviors to ranges of characters; among other things,
414 this allows hypertext-like features to be implemented. For details,
415 see the description of the tag bind widget command below.
416 The third use for tags is in managing the selection. See THE SELECTION
418 below.
419
421 The second form of annotation in text widgets is a mark. Marks are
422 used for remembering particular places in a text. They are something
423 like tags, in that they have names and they refer to places in the
424 file, but a mark isn't associated with particular characters. Instead,
425 a mark is associated with the gap between two characters. Only a sin‐
426 gle position may be associated with a mark at any given time. If the
427 characters around a mark are deleted the mark will still remain; it
428 will just have new neighbor characters. In contrast, if the characters
429 containing a tag are deleted then the tag will no longer have an asso‐
430 ciation with characters in the file. Marks may be manipulated with the
431 ``pathName mark'' widget command, and their current locations may be
432 determined by using the mark name as an index in widget commands.
433 Each mark also has a "gravity", which is either left or right. The
435 gravity for a mark specifies what happens to the mark when text is
436 inserted at the point of the mark. If a mark has left gravity, then
437 the mark is treated as if it were attached to the character on its
438 left, so the mark will remain to the left of any text inserted at the
439 mark position. If the mark has right gravity, new text inserted at the
440 mark position will appear to the left of the mark (so that the mark
441 remains rightmost). The gravity for a mark defaults to right.
442 The name space for marks is different from that for tags: the same
444 name may be used for both a mark and a tag, but they will refer to dif‐
445 ferent things.
446 Two marks have special significance. First, the mark insert is associ‐
448 ated with the insertion cursor, as described under THE INSERTION CURSOR
449 below. Second, the mark current is associated with the character clos‐
450 est to the mouse and is adjusted automatically to track the mouse posi‐
451 tion and any changes to the text in the widget (one exception: current
452 is not updated in response to mouse motions if a mouse button is down;
453 the update will be deferred until all mouse buttons have been
454 released). Neither of these special marks may be deleted.
455
457 The third form of annotation in text widgets is an embedded window.
458 Each embedded window annotation causes a window to be displayed at a
459 particular point in the text. There may be any number of embedded
460 windows in a text widget, and any widget may be used as an embedded
461 window (subject to the usual rules for geometry management, which
462 require the text window to be the parent of the embedded window or a
463 descendant of its parent). The embedded window's position on the
464 screen will be updated as the text is modified or scrolled, and it will
465 be mapped and unmapped as it moves into and out of the visible area of
466 the text widget. Each embedded window occupies one character's worth
467 of index space in the text widget, and it may be referred to either by
468 the name of its embedded window or by its position in the widget's
469 index space. If the range of text containing the embedded window is
470 deleted then the window is destroyed.
471 When an embedded window is added to a text widget with the window cre‐
473 ate widget command, several configuration options may be associated
474 with it. These options may be modified later with the window config‐
475 ure widget command. The following options are currently supported:
476 -align where
478 If the window is not as tall as the line in which it is dis‐
479 played, this option determines where the window is displayed in
480 the line. Where must have one of the values top (align the top
481 of the window with the top of the line), center (center the win‐
482 dow within the range of the line), bottom (align the bottom of
483 the window with the bottom of the line's area), or baseline
484 (align the bottom of the window with the baseline of the line).
485 -create script
487 Specifies a Tcl script that may be evaluated to create the win‐
488 dow for the annotation. If no -window option has been specified
489 for the annotation this script will be evaluated when the anno‐
490 tation is about to be displayed on the screen. Script must cre‐
491 ate a window for the annotation and return the name of that win‐
492 dow as its result. If the annotation's window should ever be
493 deleted, script will be evaluated again the next time the anno‐
494 tation is displayed.
495 -padx pixels
497 Pixels specifies the amount of extra space to leave on each side
498 of the embedded window. It may have any of the usual forms
499 defined for a screen distance.
500 -pady pixels
502 Pixels specifies the amount of extra space to leave on the top
503 and on the bottom of the embedded window. It may have any of
504 the usual forms defined for a screen distance.
505 -stretch boolean
507 If the requested height of the embedded window is less than the
508 height of the line in which it is displayed, this option can be
509 used to specify whether the window should be stretched verti‐
510 cally to fill its line. If the -pady option has been specified
511 as well, then the requested padding will be retained even if the
512 window is stretched.
513 -window pathName
515 Specifies the name of a window to display in the annotation.
516
518 The final form of annotation in text widgets is an embedded image.
519 Each embedded image annotation causes an image to be displayed at a
520 particular point in the text. There may be any number of embedded
521 images in a text widget, and a particular image may be embedded in mul‐
522 tiple places in the same text widget. The embedded image's position on
523 the screen will be updated as the text is modified or scrolled. Each
524 embedded image occupies one character's worth of index space in the
525 text widget, and it may be referred to either by its position in the
526 widget's index space, or the name it is assigned when the image is
527 inserted into the text widget with image create. If the range of text
528 containing the embedded image is deleted then that copy of the image is
529 removed from the screen.
530 When an embedded image is added to a text widget with the image create
532 widget command, a name unique to this instance of the image is
533 returned. This name may then be used to refer to this image instance.
534 The name is taken to be the value of the -name option (described
535 below). If the -name option is not provided, the -image name is used
536 instead. If the imageName is already in use in the text widget, then
537 #nn is added to the end of the imageName, where nn is an arbitrary
538 integer. This insures the imageName is unique. Once this name is
539 assigned to this instance of the image, it does not change, even though
540 the -image or -name values can be changed with image configure.
541 When an embedded image is added to a text widget with the image create
543 widget command, several configuration options may be associated with
544 it. These options may be modified later with the image configure wid‐
545 get command. The following options are currently supported:
546 -align where
548 If the image is not as tall as the line in which it is dis‐
549 played, this option determines where the image is displayed in
550 the line. Where must have one of the values top (align the top
551 of the image with the top of the line), center (center the image
552 within the range of the line), bottom (align the bottom of the
553 image with the bottom of the line's area), or baseline (align
554 the bottom of the image with the baseline of the line).
555 -image image
557 Specifies the name of the Tk image to display in the annotation.
558 If image is not a valid Tk image, then an error is returned.
559 -name ImageName
561 Specifies the name by which this image instance may be refer‐
562 enced in the text widget. If ImageName is not supplied, then the
563 name of the Tk image is used instead. If the imageName is
564 already in use, #nn is appended to the end of the name as
565 described above.
566 -padx pixels
568 Pixels specifies the amount of extra space to leave on each side
569 of the embedded image. It may have any of the usual forms
570 defined for a screen distance.
571 -pady pixels
573 Pixels specifies the amount of extra space to leave on the top
574 and on the bottom of the embedded image. It may have any of the
575 usual forms defined for a screen distance.
576
578 Selection support is implemented via tags. If the exportSelection
579 option for the text widget is true then the sel tag will be associated
580 with the selection:
581 [1] Whenever characters are tagged with sel the text widget will
583 claim ownership of the selection.
584 [2] Attempts to retrieve the selection will be serviced by the text
586 widget, returning all the characters with the sel tag.
587 [3] If the selection is claimed away by another application or by
589 another window within this application, then the sel tag will be
590 removed from all characters in the text.
591 [4] Whenever the sel tag range changes a virtual event <<Selection>>
593 is generated.
594 The sel tag is automatically defined when a text widget is created, and
596 it may not be deleted with the ``pathName tag delete'' widget command.
597 Furthermore, the selectBackground, selectBorderWidth, and selectFore‐
598 ground options for the text widget are tied to the -background, -bor‐
599 derwidth, and -foreground options for the sel tag: changes in either
600 will automatically be reflected in the other.
601
603 The mark named insert has special significance in text widgets. It is
604 defined automatically when a text widget is created and it may not be
605 unset with the ``pathName mark unset'' widget command. The insert mark
606 represents the position of the insertion cursor, and the insertion cur‐
607 sor will automatically be drawn at this point whenever the text widget
608 has the input focus.
609
611 The text widget can keep track of changes to the content of the widget
612 by means of the modified flag. Inserting or deleting text will set this
613 flag. The flag can be queried, set and cleared programmatically as
614 well. Whenever the flag changes state a <<Modified>> virtual event is
615 generated. See the edit modified widget command for more details.
616
618 The text widget has an unlimited undo and redo mechanism (when the │
619 -undo widget option is true) which records every insert and delete │
620 action on a stack. │
621 Boundaries (called "separators") are inserted between edit actions. │
623 The purpose of these separators is to group inserts, deletes and │
624 replaces into one compound edit action. When undoing a change every‐ │
625 thing between two separators will be undone. The undone changes are │
626 then moved to the redo stack, so that an undone edit can be redone │
627 again. The redo stack is cleared whenever new edit actions are │
628 recorded on the undo stack. The undo and redo stacks can be cleared to │
629 keep their depth under control. │
630 Separators are inserted automatically when the -autoseparators widget │
632 option is true. You can insert separators programmatically as well. │
633 If a separator is already present at the top of the undo stack no other │
634 will be inserted. That means that two separators on the undo stack are │
635 always separated by at least one insert or delete action. │
636 The undo mechanism is also linked to the modified flag. This means │
638 that undoing or redoing changes can take a modified text widget back to │
639 the unmodified state or vice versa. The modified flag will be set │
640 automatically to the appropriate state. This automatic coupling does │
641 not work when the modified flag has been set by the user, until the │
642 flag has been reset again. │
643 See below for the edit widget command that controls the undo mechanism.
645
647 The text command creates a new Tcl command whose name is the same as
648 the path name of the text's window. This command may be used to invoke
649 various operations on the widget. It has the following general form:
650 pathName option ?arg arg ...?
651 PathName is the name of the command, which is the same as the text wid‐
652 get's path name. Option and the args determine the exact behavior of
653 the command. The following commands are possible for text widgets:
654 pathName bbox index
656 Returns a list of four elements describing the screen area of
657 the character given by index. The first two elements of the
658 list give the x and y coordinates of the upper-left corner of
659 the area occupied by the character, and the last two elements
660 give the width and height of the area. If the character is only
661 partially visible on the screen, then the return value reflects
662 just the visible part. If the character is not visible on the
663 screen then the return value is an empty list.
664 pathName cget option
666 Returns the current value of the configuration option given by
667 option. Option may have any of the values accepted by the text
668 command.
669 pathName compare index1 op index2
671 Compares the indices given by index1 and index2 according to the
672 relational operator given by op, and returns 1 if the relation‐
673 ship is satisfied and 0 if it isn't. Op must be one of the
674 operators <, <=, ==, >=, >, or !=. If op is == then 1 is
675 returned if the two indices refer to the same character, if op
676 is < then 1 is returned if index1 refers to an earlier character
677 in the text than index2, and so on.
678 pathName configure ?option? ?value option value ...?
680 Query or modify the configuration options of the widget. If no
681 option is specified, returns a list describing all of the avail‐
682 able options for pathName (see Tk_ConfigureInfo for information
683 on the format of this list). If option is specified with no
684 value, then the command returns a list describing the one named
685 option (this list will be identical to the corresponding sublist
686 of the value returned if no option is specified). If one or
687 more option-value pairs are specified, then the command modifies
688 the given widget option(s) to have the given value(s); in this
689 case the command returns an empty string. Option may have any
690 of the values accepted by the text command.
691 pathName debug ?boolean?
693 If boolean is specified, then it must have one of the true or
694 false values accepted by Tcl_GetBoolean. If the value is a true
695 one then internal consistency checks will be turned on in the B-
696 tree code associated with text widgets. If boolean has a false
697 value then the debugging checks will be turned off. In either
698 case the command returns an empty string. If boolean is not
699 specified then the command returns on or off to indicate whether
700 or not debugging is turned on. There is a single debugging
701 switch shared by all text widgets: turning debugging on or off
702 in any widget turns it on or off for all widgets. For widgets
703 with large amounts of text, the consistency checks may cause a
704 noticeable slow-down.
705 When debugging is turned on, the drawing routines of the text widget │
707 set the global variables tk_textRedraw and tk_textRelayout to the lists │
708 of indices that are redrawn. The values of these variables are tested │
709 by Tk's test suite.
710 pathName delete index1 ?index2 ...?
712 Delete a range of characters from the text. If both index1 and
713 index2 are specified, then delete all the characters starting
714 with the one given by index1 and stopping just before index2
715 (i.e. the character at index2 is not deleted). If index2
716 doesn't specify a position later in the text than index1 then no
717 characters are deleted. If index2 isn't specified then the sin‐
718 gle character at index1 is deleted. It is not allowable to
719 delete characters in a way that would leave the text without a
720 newline as the last character. The command returns an empty
721 string. If more indices are given, multiple ranges of text will │
722 be deleted. All indices are first checked for validity before │
723 any deletions are made. They are sorted and the text is removed │
724 from the last range to the first range to deleted text does not │
725 cause an undesired index shifting side-effects. If multiple │
726 ranges with the same start index are given, then the longest │
727 range is used. If overlapping ranges are given, then they will │
728 be merged into spans that do not cause deletion of text outside │
729 the given ranges due to text shifted during deletion.
730 pathName dlineinfo index
732 Returns a list with five elements describing the area occupied
733 by the display line containing index. The first two elements of
734 the list give the x and y coordinates of the upper-left corner
735 of the area occupied by the line, the third and fourth elements
736 give the width and height of the area, and the fifth element
737 gives the position of the baseline for the line, measured down
738 from the top of the area. All of this information is measured
739 in pixels. If the current wrap mode is none and the line
740 extends beyond the boundaries of the window, the area returned
741 reflects the entire area of the line, including the portions
742 that are out of the window. If the line is shorter than the
743 full width of the window then the area returned reflects just
744 the portion of the line that is occupied by characters and
745 embedded windows. If the display line containing index is not
746 visible on the screen then the return value is an empty list.
747 pathName dump ?switches? index1 ?index2?
749 Return the contents of the text widget from index1 up to, but
750 not including index2, including the text and information about
751 marks, tags, and embedded windows. If index2 is not specified,
752 then it defaults to one character past index1. The information
753 is returned in the following format:
754 key1 value1 index1 key2 value2 index2 ...
756 The possible key values are text, mark, tagon, tagoff, image,
758 and window. The corresponding value is the text, mark name, tag
759 name, image name, or window name. The index information is the
760 index of the start of the text, mark, tag transition, image or
761 window. One or more of the following switches (or abbreviations
762 thereof) may be specified to control the dump:
763 -all Return information about all elements: text, marks, tags,
765 images and windows. This is the default.
766 -command command
768 Instead of returning the information as the result of the
769 dump operation, invoke the command on each element of the
770 text widget within the range. The command has three
771 arguments appended to it before it is evaluated: the key,
772 value, and index.
773 -image Include information about images in the dump results.
775 -mark Include information about marks in the dump results.
777 -tag Include information about tag transitions in the dump
779 results. Tag information is returned as tagon and tagoff
780 elements that indicate the begin and end of each range of
781 each tag, respectively.
782 -text Include information about text in the dump results. The
784 value is the text up to the next element or the end of
785 range indicated by index2. A text element does not span
786 newlines. A multi-line block of text that contains no
787 marks or tag transitions will still be dumped as a set of
788 text segments that each end with a newline. The newline
789 is part of the value.
790 -window
792 Include information about embedded windows in the dump
793 results. The value of a window is its Tk pathname,
794 unless the window has not been created yet. (It must
795 have a create script.) In this case an empty string is
796 returned, and you must query the window by its index
797 position to get more information.
798 pathName edit option ?arg arg ...?
800 This command controls the undo mechanism and the modified flag. │
801 The exact behavior of the command depends on the option argument │
802 that follows the edit argument. The following forms of the com‐ │
803 mand are currently supported: │
804 pathName edit modified ?boolean? │
806 If boolean is not specified, returns the modified flag of │
807 the widget. The insert, delete, edit undo and edit redo │
808 commands or the user can set or clear the modified flag. │
809 If boolean is specified, sets the modified flag of the │
810 widget to boolean. │
811 pathName edit redo │
813 When the -undo option is true, reapplies the last undone │
814 edits provided no other edits were done since then. Gen‐ │
815 erates an error when the redo stack is empty. Does noth‐ │
816 ing when the -undo option is false. │
817 pathName edit reset │
819 Clears the undo and redo stacks. │
820 pathName edit separator │
822 Inserts a separator (boundary) on the undo stack. Does │
823 nothing when the -undo option is false. │
824 pathName edit undo │
826 Undoes the last edit action when the -undo option is │
827 true. An edit action is defined as all the insert and │
828 delete commands that are recorded on the undo stack in │
829 between two separators. Generates an error when the undo │
830 stack is empty. Does nothing when the -undo option is │
831 false. │
832 pathName get index1 ?index2 ...?
834 Return a range of characters from the text. The return value
835 will be all the characters in the text starting with the one
836 whose index is index1 and ending just before the one whose index
837 is index2 (the character at index2 will not be returned). If
838 index2 is omitted then the single character at index1 is
839 returned. If there are no characters in the specified range
840 (e.g. index1 is past the end of the file or index2 is less than
841 or equal to index1) then an empty string is returned. If the
842 specified range contains embedded windows, no information about
843 them is included in the returned string. If multiple index │
844 pairs are given, multiple ranges of text will be returned in a │
845 list. Invalid ranges will not be represented with empty strings │
846 in the list. The ranges are returned in the order passed to │
847 get.
848 pathName image option ?arg arg ...?
850 This command is used to manipulate embedded images. The behav‐
851 ior of the command depends on the option argument that follows
852 the tag argument. The following forms of the command are cur‐
853 rently supported:
854 pathName image cget index option
856 Returns the value of a configuration option for an embed‐
857 ded image. Index identifies the embedded image, and
858 option specifies a particular configuration option, which
859 must be one of the ones listed in the section EMBEDDED
860 IMAGES.
861 pathName image configure index ?option value ...?
863 Query or modify the configuration options for an embedded
864 image. If no option is specified, returns a list
865 describing all of the available options for the embedded
866 image at index (see Tk_ConfigureInfo for information on
867 the format of this list). If option is specified with no
868 value, then the command returns a list describing the one
869 named option (this list will be identical to the corre‐
870 sponding sublist of the value returned if no option is
871 specified). If one or more option-value pairs are speci‐
872 fied, then the command modifies the given option(s) to
873 have the given value(s); in this case the command
874 returns an empty string. See EMBEDDED IMAGES for infor‐
875 mation on the options that are supported.
876 pathName image create index ?option value ...?
878 This command creates a new image annotation, which will
879 appear in the text at the position given by index. Any
880 number of option-value pairs may be specified to config‐
881 ure the annotation. Returns a unique identifier that may
882 be used as an index to refer to this image. See EMBEDDED
883 IMAGES for information on the options that are supported,
884 and a description of the identifier returned.
885 pathName image names
887 Returns a list whose elements are the names of all image
888 instances currently embedded in window.
889 pathName index index
891 Returns the position corresponding to index in the form
892 line.char where line is the line number and char is the charac‐
893 ter number. Index may have any of the forms described under
894 INDICES above.
895 pathName insert index chars ?tagList chars tagList ...?
897 Inserts all of the chars arguments just before the character at
898 index. If index refers to the end of the text (the character
899 after the last newline) then the new text is inserted just
900 before the last newline instead. If there is a single chars
901 argument and no tagList, then the new text will receive any tags
902 that are present on both the character before and the character
903 after the insertion point; if a tag is present on only one of
904 these characters then it will not be applied to the new text.
905 If tagList is specified then it consists of a list of tag names;
906 the new characters will receive all of the tags in this list and
907 no others, regardless of the tags present around the insertion
908 point. If multiple chars-tagList argument pairs are present,
909 they produce the same effect as if a separate insert widget com‐
910 mand had been issued for each pair, in order. The last tagList
911 argument may be omitted.
912 pathName mark option ?arg arg ...?
914 This command is used to manipulate marks. The exact behavior of
915 the command depends on the option argument that follows the mark
916 argument. The following forms of the command are currently sup‐
917 ported:
918 pathName mark gravity markName ?direction?
920 If direction is not specified, returns left or right to
921 indicate which of its adjacent characters markName is
922 attached to. If direction is specified, it must be left
923 or right; the gravity of markName is set to the given
924 value.
925 pathName mark names
927 Returns a list whose elements are the names of all the
928 marks that are currently set.
929 pathName mark next index
931 Returns the name of the next mark at or after index. If
932 index is specified in numerical form, then the search for
933 the next mark begins at that index. If index is the name
934 of a mark, then the search for the next mark begins imme‐
935 diately after that mark. This can still return a mark at
936 the same position if there are multiple marks at the same
937 index. These semantics mean that the mark next operation
938 can be used to step through all the marks in a text wid‐
939 get in the same order as the mark information returned by
940 the dump operation. If a mark has been set to the spe‐
941 cial end index, then it appears to be after end with
942 respect to the mark next operation. An empty string is
943 returned if there are no marks after index.
944 pathName mark previous index
946 Returns the name of the mark at or before index. If
947 index is specified in numerical form, then the search for
948 the previous mark begins with the character just before
949 that index. If index is the name of a mark, then the
950 search for the next mark begins immediately before that
951 mark. This can still return a mark at the same position
952 if there are multiple marks at the same index. These
953 semantics mean that the mark previous operation can be
954 used to step through all the marks in a text widget in
955 the reverse order as the mark information returned by the
956 dump operation. An empty string is returned if there are
957 no marks before index.
958 pathName mark set markName index
960 Sets the mark named markName to a position just before
961 the character at index. If markName already exists, it
962 is moved from its old position; if it doesn't exist, a
963 new mark is created. This command returns an empty
964 string.
965 pathName mark unset markName ?markName markName ...?
967 Remove the mark corresponding to each of the markName
968 arguments. The removed marks will not be usable in
969 indices and will not be returned by future calls to
970 ``pathName mark names''. This command returns an empty
971 string.
972 pathName scan option args
974 This command is used to implement scanning on texts. It has two
975 forms, depending on option:
976 pathName scan mark x y
978 Records x and y and the current view in the text window,
979 for use in conjunction with later scan dragto commands.
980 Typically this command is associated with a mouse button
981 press in the widget. It returns an empty string.
982 pathName scan dragto x y
984 This command computes the difference between its x and y
985 arguments and the x and y arguments to the last scan mark
986 command for the widget. It then adjusts the view by 10
987 times the difference in coordinates. This command is
988 typically associated with mouse motion events in the wid‐
989 get, to produce the effect of dragging the text at high
990 speed through the window. The return value is an empty
991 string.
992 pathName search ?switches? pattern index ?stopIndex?
994 Searches the text in pathName starting at index for a range of
995 characters that matches pattern. If a match is found, the index
996 of the first character in the match is returned as result; oth‐
997 erwise an empty string is returned. One or more of the follow‐
998 ing switches (or abbreviations thereof) may be specified to con‐
999 trol the search:
1000 -forwards
1002 The search will proceed forward through the text, finding
1003 the first matching range starting at or after the posi‐
1004 tion given by index. This is the default.
1005 -backwards
1007 The search will proceed backward through the text, find‐
1008 ing the matching range closest to index whose first char‐
1009 acter is before index.
1010 -exact Use exact matching: the characters in the matching range
1012 must be identical to those in pattern. This is the
1013 default.
1014 -regexp
1016 Treat pattern as a regular expression and match it
1017 against the text using the rules for regular expressions
1018 (see the regexp command for details).
1019 -nocase
1021 Ignore case differences between the pattern and the text.
1022 -count varName
1024 The argument following -count gives the name of a vari‐
1025 able; if a match is found, the number of index positions
1026 between beginning and end of the matching range will be
1027 stored in the variable. If there are no embedded images
1028 or windows in the matching range (and there are no elided
1029 characters if -elide is not given), this is equivalent to
1030 the number of characters matched. In either case, the
1031 range matchIdx to matchIdx + $count chars will return the
1032 entire matched text.
1033 -elide Find elided (hidden) text as well. By default only dis‐
1035 played text is searched.
1036 -- This switch has no effect except to terminate the list of
1038 switches: the next argument will be treated as pattern
1039 even if it starts with -.
1040 The matching range must be entirely within a single line of
1042 text. For regular expression matching the newlines are removed
1043 from the ends of the lines before matching: use the $ feature
1044 in regular expressions to match the end of a line. For exact
1045 matching the newlines are retained. If stopIndex is specified,
1046 the search stops at that index: for forward searches, no match
1047 at or after stopIndex will be considered; for backward
1048 searches, no match earlier in the text than stopIndex will be
1049 considered. If stopIndex is omitted, the entire text will be
1050 searched: when the beginning or end of the text is reached, the
1051 search continues at the other end until the starting location is
1052 reached again; if stopIndex is specified, no wrap-around will
1053 occur.
1054 pathName see index
1056 Adjusts the view in the window so that the character given by
1057 index is completely visible. If index is already visible then
1058 the command does nothing. If index is a short distance out of
1059 view, the command adjusts the view just enough to make index
1060 visible at the edge of the window. If index is far out of view,
1061 then the command centers index in the window.
1062 pathName tag option ?arg arg ...?
1064 This command is used to manipulate tags. The exact behavior of
1065 the command depends on the option argument that follows the tag
1066 argument. The following forms of the command are currently sup‐
1067 ported:
1068 pathName tag add tagName index1 ?index2 index1 index2 ...?
1070 Associate the tag tagName with all of the characters
1071 starting with index1 and ending just before index2 (the
1072 character at index2 isn't tagged). A single command may
1073 contain any number of index1-index2 pairs. If the last
1074 index2 is omitted then the single character at index1 is
1075 tagged. If there are no characters in the specified
1076 range (e.g. index1 is past the end of the file or index2
1077 is less than or equal to index1) then the command has no
1078 effect.
1079 pathName tag bind tagName ?sequence? ?script?
1081 This command associates script with the tag given by tag‐
1082 Name. Whenever the event sequence given by sequence
1083 occurs for a character that has been tagged with tagName,
1084 the script will be invoked. This widget command is simi‐
1085 lar to the bind command except that it operates on char‐
1086 acters in a text rather than entire widgets. See the
1087 bind manual entry for complete details on the syntax of
1088 sequence and the substitutions performed on script before
1089 invoking it. If all arguments are specified then a new
1090 binding is created, replacing any existing binding for
1091 the same sequence and tagName (if the first character of
1092 script is ``+'' then script augments an existing binding
1093 rather than replacing it). In this case the return value
1094 is an empty string. If script is omitted then the com‐
1095 mand returns the script associated with tagName and
1096 sequence (an error occurs if there is no such binding).
1097 If both script and sequence are omitted then the command
1098 returns a list of all the sequences for which bindings
1099 have been defined for tagName.
1100 The only events for which bindings may be specified are │
1102 those related to the mouse and keyboard (such as Enter, │
1103 Leave, ButtonPress, Motion, and KeyPress) or virtual │
1104 events. Event bindings for a text widget use the current │
1105 mark described under MARKS above. An Enter event trig‐ │
1106 gers for a tag when the tag first becomes present on the │
1107 current character, and a Leave event triggers for a tag │
1108 when it ceases to be present on the current character. │
1109 Enter and Leave events can happen either because the cur‐ │
1110 rent mark moved or because the character at that position │
1111 changed. Note that these events are different than Enter │
1112 and Leave events for windows. Mouse and keyboard events │
1113 are directed to the current character. If a virtual │
1114 event is used in a binding, that binding can trigger only │
1115 if the virtual event is defined by an underlying mouse- │
1116 related or keyboard-related event.
1117 It is possible for the current character to have multiple
1119 tags, and for each of them to have a binding for a par‐
1120 ticular event sequence. When this occurs, one binding is
1121 invoked for each tag, in order from lowest-priority to
1122 highest priority. If there are multiple matching bind‐
1123 ings for a single tag, then the most specific binding is
1124 chosen (see the manual entry for the bind command for
1125 details). continue and break commands within binding
1126 scripts are processed in the same way as for bindings
1127 created with the bind command.
1128 If bindings are created for the widget as a whole using
1130 the bind command, then those bindings will supplement the
1131 tag bindings. The tag bindings will be invoked first,
1132 followed by bindings for the window as a whole.
1133 pathName tag cget tagName option
1135 This command returns the current value of the option
1136 named option associated with the tag given by tagName.
1137 Option may have any of the values accepted by the tag
1138 configure widget command.
1139 pathName tag configure tagName ?option? ?value? ?option value
1141 ...?
1142 This command is similar to the configure widget command
1143 except that it modifies options associated with the tag
1144 given by tagName instead of modifying options for the
1145 overall text widget. If no option is specified, the com‐
1146 mand returns a list describing all of the available
1147 options for tagName (see Tk_ConfigureInfo for information
1148 on the format of this list). If option is specified with
1149 no value, then the command returns a list describing the
1150 one named option (this list will be identical to the cor‐
1151 responding 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 tagName; in this case the com‐
1155 mand returns an empty string. See TAGS above for details
1156 on the options available for tags.
1157 pathName tag delete tagName ?tagName ...?
1159 Deletes all tag information for each of the tagName argu‐
1160 ments. The command removes the tags from all characters
1161 in the file and also deletes any other information asso‐
1162 ciated with the tags, such as bindings and display infor‐
1163 mation. The command returns an empty string.
1164 pathName tag lower tagName ?belowThis?
1166 Changes the priority of tag tagName so that it is just
1167 lower in priority than the tag whose name is belowThis.
1168 If belowThis is omitted, then tagName's priority is
1169 changed to make it lowest priority of all tags.
1170 pathName tag names ?index?
1172 Returns a list whose elements are the names of all the
1173 tags that are active at the character position given by
1174 index. If index is omitted, then the return value will
1175 describe all of the tags that exist for the text (this
1176 includes all tags that have been named in a ``pathName
1177 tag'' widget command but haven't been deleted by a
1178 ``pathName tag delete'' widget command, even if no char‐
1179 acters are currently marked with the tag). The list will
1180 be sorted in order from lowest priority to highest prior‐
1181 ity.
1182 pathName tag nextrange tagName index1 ?index2?
1184 This command searches the text for a range of characters
1185 tagged with tagName where the first character of the
1186 range is no earlier than the character at index1 and no
1187 later than the character just before index2 (a range
1188 starting at index2 will not be considered). If several
1189 matching ranges exist, the first one is chosen. The com‐
1190 mand's return value is a list containing two elements,
1191 which are the index of the first character of the range
1192 and the index of the character just after the last one in
1193 the range. If no matching range is found then the return
1194 value is an empty string. If index2 is not given then it
1195 defaults to the end of the text.
1196 pathName tag prevrange tagName index1 ?index2?
1198 This command searches the text for a range of characters
1199 tagged with tagName where the first character of the
1200 range is before the character at index1 and no earlier
1201 than the character at index2 (a range starting at index2
1202 will be considered). If several matching ranges exist,
1203 the one closest to index1 is chosen. The command's
1204 return value is a list containing two elements, which are
1205 the index of the first character of the range and the
1206 index of the character just after the last one in the
1207 range. If no matching range is found then the return
1208 value is an empty string. If index2 is not given then it
1209 defaults to the beginning of the text.
1210 pathName tag raise tagName ?aboveThis?
1212 Changes the priority of tag tagName so that it is just
1213 higher in priority than the tag whose name is aboveThis.
1214 If aboveThis is omitted, then tagName's priority is
1215 changed to make it highest priority of all tags.
1216 pathName tag ranges tagName
1218 Returns a list describing all of the ranges of text that
1219 have been tagged with tagName. The first two elements of
1220 the list describe the first tagged range in the text, the
1221 next two elements describe the second range, and so on.
1222 The first element of each pair contains the index of the
1223 first character of the range, and the second element of
1224 the pair contains the index of the character just after
1225 the last one in the range. If there are no characters
1226 tagged with tag then an empty string is returned.
1227 pathName tag remove tagName index1 ?index2 index1 index2 ...?
1229 Remove the tag tagName from all of the characters start‐
1230 ing at index1 and ending just before index2 (the charac‐
1231 ter at index2 isn't affected). A single command may con‐
1232 tain any number of index1-index2 pairs. If the last
1233 index2 is omitted then the single character at index1 is
1234 tagged. If there are no characters in the specified
1235 range (e.g. index1 is past the end of the file or index2
1236 is less than or equal to index1) then the command has no
1237 effect. This command returns an empty string.
1238 pathName window option ?arg arg ...?
1240 This command is used to manipulate embedded windows. The behav‐
1241 ior of the command depends on the option argument that follows
1242 the tag argument. The following forms of the command are cur‐
1243 rently supported:
1244 pathName window cget index option
1246 Returns the value of a configuration option for an embed‐
1247 ded window. Index identifies the embedded window, and
1248 option specifies a particular configuration option, which
1249 must be one of the ones listed in the section EMBEDDED
1250 WINDOWS.
1251 pathName window configure index ?option value ...?
1253 Query or modify the configuration options for an embedded
1254 window. If no option is specified, returns a list
1255 describing all of the available options for the embedded
1256 window at index (see Tk_ConfigureInfo for information on
1257 the format of this list). If option is specified with no
1258 value, then the command returns a list describing the one
1259 named option (this list will be identical to the corre‐
1260 sponding sublist of the value returned if no option is
1261 specified). If one or more option-value pairs are speci‐
1262 fied, then the command modifies the given option(s) to
1263 have the given value(s); in this case the command
1264 returns an empty string. See EMBEDDED WINDOWS for infor‐
1265 mation on the options that are supported.
1266 pathName window create index ?option value ...?
1268 This command creates a new window annotation, which will
1269 appear in the text at the position given by index. Any
1270 number of option-value pairs may be specified to config‐
1271 ure the annotation. See EMBEDDED WINDOWS for information
1272 on the options that are supported. Returns an empty
1273 string.
1274 pathName window names
1276 Returns a list whose elements are the names of all win‐
1277 dows currently embedded in window.
1278 pathName xview option args
1280 This command is used to query and change the horizontal position
1281 of the text in the widget's window. It can take any of the fol‐
1282 lowing forms:
1283 pathName xview
1285 Returns a list containing two elements. Each element is
1286 a real fraction between 0 and 1; together they describe
1287 the portion of the document's horizontal span that is
1288 visible in the window. For example, if the first element
1289 is .2 and the second element is .6, 20% of the text is
1290 off-screen to the left, the middle 40% is visible in the
1291 window, and 40% of the text is off-screen to the right.
1292 The fractions refer only to the lines that are actually
1293 visible in the window: if the lines in the window are
1294 all very short, so that they are entirely visible, the
1295 returned fractions will be 0 and 1, even if there are
1296 other lines in the text that are much wider than the win‐
1297 dow. These are the same values passed to scrollbars via
1298 the -xscrollcommand option.
1299 pathName xview moveto fraction
1301 Adjusts the view in the window so that fraction of the
1302 horizontal span of the text is off-screen to the left.
1303 Fraction is a fraction between 0 and 1.
1304 pathName xview scroll number what
1306 This command shifts the view in the window left or right
1307 according to number and what. Number must be an integer.
1308 What must be either units or pages or an abbreviation of
1309 one of these. If what is units, the view adjusts left or
1310 right by number average-width characters on the display;
1311 if it is pages then the view adjusts by number screen‐
1312 fuls. If number is negative then characters farther to
1313 the left become visible; if it is positive then charac‐
1314 ters farther to the right become visible.
1315 pathName yview ?args?
1317 This command is used to query and change the vertical position
1318 of the text in the widget's window. It can take any of the fol‐
1319 lowing forms:
1320 pathName yview
1322 Returns a list containing two elements, both of which are
1323 real fractions between 0 and 1. The first element gives
1324 the position of the first character in the top line in
1325 the window, relative to the text as a whole (0.5 means it
1326 is halfway through the text, for example). The second
1327 element gives the position of the character just after
1328 the last one in the bottom line of the window, relative
1329 to the text as a whole. These are the same values passed
1330 to scrollbars via the -yscrollcommand option.
1331 pathName yview moveto fraction
1333 Adjusts the view in the window so that the character
1334 given by fraction appears on the top line of the window.
1335 Fraction is a fraction between 0 and 1; 0 indicates the
1336 first character in the text, 0.33 indicates the character
1337 one-third the way through the text, and so on.
1338 pathName yview scroll number what
1340 This command adjust the view in the window up or down
1341 according to number and what. Number must be an integer.
1342 What must be either units or pages. If what is units,
1343 the view adjusts up or down by number lines on the dis‐
1344 play; if it is pages then the view adjusts by number
1345 screenfuls. If number is negative then earlier positions
1346 in the text become visible; if it is positive then later
1347 positions in the text become visible.
1348 pathName yview ?-pickplace? index
1350 Changes the view in the widget's window to make index
1351 visible. If the -pickplace option isn't specified then
1352 index will appear at the top of the window. If -pick‐
1353 place is specified then the widget chooses where index
1354 appears in the window:
1355 [1] If index is already visible somewhere in the win‐
1357 dow then the command does nothing.
1358 [2] If index is only a few lines off-screen above the
1360 window then it will be positioned at the top of
1361 the window.
1362 [3] If index is only a few lines off-screen below the
1364 window then it will be positioned at the bottom of
1365 the window.
1366 [4] Otherwise, index will be centered in the window.
1368 The -pickplace option has been obsoleted by the see wid‐
1370 get command (see handles both x- and y-motion to make a
1371 location visible, whereas -pickplace only handles motion
1372 in y).
1373 pathName yview number
1375 This command makes the first character on the line after
1376 the one given by number visible at the top of the window.
1377 Number must be an integer. This command used to be used
1378 for scrolling, but now it is obsolete.
1379
1381 Tk automatically creates class bindings for texts that give them the
1382 following default behavior. In the descriptions below, ``word'' is
1383 dependent on the value of the tcl_wordchars variable. See tclvars(n).
1384 [1] Clicking mouse button 1 positions the insertion cursor just
1386 before the character underneath the mouse cursor, sets the input
1387 focus to this widget, and clears any selection in the widget.
1388 Dragging with mouse button 1 strokes out a selection between the
1389 insertion cursor and the character under the mouse.
1390 [2] Double-clicking with mouse button 1 selects the word under the
1392 mouse and positions the insertion cursor at the end of the word.
1393 Dragging after a double click will stroke out a selection con‐
1394 sisting of whole words.
1395 [3] Triple-clicking with mouse button 1 selects the line under the
1397 mouse and positions the insertion cursor at the end of the line.
1398 Dragging after a triple click will stroke out a selection con‐
1399 sisting of whole lines.
1400 [4] The ends of the selection can be adjusted by dragging with mouse
1402 button 1 while the Shift key is down; this will adjust the end
1403 of the selection that was nearest to the mouse cursor when but‐
1404 ton 1 was pressed. If the button is double-clicked before drag‐
1405 ging then the selection will be adjusted in units of whole
1406 words; if it is triple-clicked then the selection will be
1407 adjusted in units of whole lines.
1408 [5] Clicking mouse button 1 with the Control key down will reposi‐
1410 tion the insertion cursor without affecting the selection.
1411 [6] If any normal printing characters are typed, they are inserted
1413 at the point of the insertion cursor.
1414 [7] The view in the widget can be adjusted by dragging with mouse
1416 button 2. If mouse button 2 is clicked without moving the
1417 mouse, the selection is copied into the text at the position of
1418 the mouse cursor. The Insert key also inserts the selection,
1419 but at the position of the insertion cursor.
1420 [8] If the mouse is dragged out of the widget while button 1 is
1422 pressed, the entry will automatically scroll to make more text
1423 visible (if there is more text off-screen on the side where the
1424 mouse left the window).
1425 [9] The Left and Right keys move the insertion cursor one character
1427 to the left or right; they also clear any selection in the
1428 text. If Left or Right is typed with the Shift key down, then
1429 the insertion cursor moves and the selection is extended to
1430 include the new character. Control-Left and Control-Right move
1431 the insertion cursor by words, and Control-Shift-Left and Con‐
1432 trol-Shift-Right move the insertion cursor by words and also
1433 extend the selection. Control-b and Control-f behave the same
1434 as Left and Right, respectively. Meta-b and Meta-f behave the
1435 same as Control-Left and Control-Right, respectively.
1436 [10] The Up and Down keys move the insertion cursor one line up or
1438 down and clear any selection in the text. If Up or Right is
1439 typed with the Shift key down, then the insertion cursor moves
1440 and the selection is extended to include the new character.
1441 Control-Up and Control-Down move the insertion cursor by para‐
1442 graphs (groups of lines separated by blank lines), and Control-
1443 Shift-Up and Control-Shift-Down move the insertion cursor by
1444 paragraphs and also extend the selection. Control-p and Con‐
1445 trol-n behave the same as Up and Down, respectively.
1446 [11] The Next and Prior keys move the insertion cursor forward or
1448 backwards by one screenful and clear any selection in the text.
1449 If the Shift key is held down while Next or Prior is typed, then
1450 the selection is extended to include the new character. Con‐
1451 trol-v moves the view down one screenful without moving the
1452 insertion cursor or adjusting the selection.
1453 [12] Control-Next and Control-Prior scroll the view right or left by
1455 one page without moving the insertion cursor or affecting the
1456 selection.
1457 [13] Home and Control-a move the insertion cursor to the beginning of
1459 its line and clear any selection in the widget. Shift-Home
1460 moves the insertion cursor to the beginning of the line and also
1461 extends the selection to that point.
1462 [14] End and Control-e move the insertion cursor to the end of the
1464 line and clear any selection in the widget. Shift-End moves the
1465 cursor to the end of the line and extends the selection to that
1466 point.
1467 [15] Control-Home and Meta-< move the insertion cursor to the begin‐
1469 ning of the text and clear any selection in the widget. Con‐
1470 trol-Shift-Home moves the insertion cursor to the beginning of
1471 the text and also extends the selection to that point.
1472 [16] Control-End and Meta-> move the insertion cursor to the end of
1474 the text and clear any selection in the widget. Control-Shift-
1475 End moves the cursor to the end of the text and extends the
1476 selection to that point.
1477 [17] The Select key and Control-Space set the selection anchor to the
1479 position of the insertion cursor. They don't affect the current
1480 selection. Shift-Select and Control-Shift-Space adjust the
1481 selection to the current position of the insertion cursor,
1482 selecting from the anchor to the insertion cursor if there was
1483 not any selection previously.
1484 [18] Control-/ selects the entire contents of the widget.
1486 [19] Control-\ clears any selection in the widget.
1488 [20] The F16 key (labelled Copy on many Sun workstations) or Meta-w
1490 copies the selection in the widget to the clipboard, if there is
1491 a selection. This action is carried out by the command │
1492 tk_textCopy.
1493 [21] The F20 key (labelled Cut on many Sun workstations) or Control-w
1495 copies the selection in the widget to the clipboard and deletes
1496 the selection. This action is carried out by the command │
1497 tk_textCut. If there is no selection in the widget then these
1498 keys have no effect.
1499 [22] The F18 key (labelled Paste on many Sun workstations) or Con‐
1501 trol-y inserts the contents of the clipboard at the position of
1502 the insertion cursor. This action is carried out by the command │
1503 tk_textPaste.
1504 [23] The Delete key deletes the selection, if there is one in the
1506 widget. If there is no selection, it deletes the character to
1507 the right of the insertion cursor.
1508 [24] Backspace and Control-h delete the selection, if there is one in
1510 the widget. If there is no selection, they delete the character
1511 to the left of the insertion cursor.
1512 [25] Control-d deletes the character to the right of the insertion
1514 cursor.
1515 [26] Meta-d deletes the word to the right of the insertion cursor.
1517 [27] Control-k deletes from the insertion cursor to the end of its
1519 line; if the insertion cursor is already at the end of a line,
1520 then Control-k deletes the newline character.
1521 [28] Control-o opens a new line by inserting a newline character in
1523 front of the insertion cursor without moving the insertion cur‐
1524 sor.
1525 [29] Meta-backspace and Meta-Delete delete the word to the left of
1527 the insertion cursor.
1528 [30] Control-x deletes whatever is selected in the text widget after
1530 copying it to the clipboard.
1531 [31] Control-t reverses the order of the two characters to the right
1533 of the insertion cursor.
1534 [32] Control-z (and Control-underscore on UNIX when tk_strictMotif is │
1536 true) undoes the last edit action if the -undo option is true. │
1537 Does nothing otherwise. │
1538 [33] │
1540 Control-Z (or Control-y on Windows) reapplies the last undone │
1541 edit action if the -undo option is true. Does nothing otherwise.
1542 If the widget is disabled using the -state option, then its view can
1544 still be adjusted and text can still be selected, but no insertion cur‐
1545 sor will be displayed and no text modifications will take place.
1546 The behavior of texts can be changed by defining new bindings for indi‐
1548 vidual widgets or by redefining the class bindings.
1549
1551 Text widgets should run efficiently under a variety of conditions. The
1552 text widget uses about 2-3 bytes of main memory for each byte of text,
1553 so texts containing a megabyte or more should be practical on most
1554 workstations. Text is represented internally with a modified B-tree
1555 structure that makes operations relatively efficient even with large
1556 texts. Tags are included in the B-tree structure in a way that allows
1557 tags to span large ranges or have many disjoint smaller ranges without
1558 loss of efficiency. Marks are also implemented in a way that allows
1559 large numbers of marks. In most cases it is fine to have large numbers
1560 of unique tags, or a tag that has many distinct ranges.
1561 One performance problem can arise if you have hundreds or thousands of
1563 different tags that all have the following characteristics: the first
1564 and last ranges of each tag are near the beginning and end of the text,
1565 respectively, or a single tag range covers most of the text widget.
1566 The cost of adding and deleting tags like this is proportional to the
1567 number of other tags with the same properties. In contrast, there is
1568 no problem with having thousands of distinct tags if their overall
1569 ranges are localized and spread uniformly throughout the text.
1570 Very long text lines can be expensive, especially if they have many
1572 marks and tags within them.
1573 The display line with the insert cursor is redrawn each time the cursor
1575 blinks, which causes a steady stream of graphics traffic. Set the
1576 insertOffTime attribute to 0 avoid this.
1577
1580 entry(n), scrollbar(n)
1581
1584 text, widget, tkvars
1585Tk 8.4 text(n)