1Text(3) User Contributed Perl Documentation Text(3)
2
6 Tk::Text - Create and manipulate Text widgets
7
9 text $text ?options?
10 -background -highlightbackground -insertontime -selectborder‐
12 width -borderwidth -highlightcolor -insertwidth -selectfore‐
13 ground -cursor -highlightthickness -padx -setgrid -exportselec‐
14 tion -insertbackground -pady -takefocus -font -insertbor‐
15 derwidth -relief -xscrollcommand -foreground -insertoff‐
16 time -selectbackground -yscrollcommand
17
19 Name: height
20 Class: Height
21 Switch: -height
22 Specifies the desired height for the window, in units of characters
23 in the font given by the -font option. Must be at least one.
24 Name: spacing1
26 Class: Spacing1
27 Switch: -spacing1
28 Requests additional space above each text line in the widget, using
29 any of the standard forms for screen distances. If a line wraps,
30 this option only applies to the first line on the display. This
31 option may be overriden with -spacing1 options in tags.
32 Name: spacing2
34 Class: Spacing2
35 Switch: -spacing2
36 For lines that wrap (so that they cover more than one line on the
37 display) this option specifies additional space to provide between
38 the display lines that represent a single line of text. The value
39 may have any of the standard forms for screen distances. This
40 option may be overriden with -spacing2 options in tags.
41 Name: spacing3
43 Class: Spacing3
44 Switch: -spacing3
45 Requests additional space below each text line in the widget, using
46 any of the standard forms for screen distances. If a line wraps,
47 this option only applies to the last line on the display. This
48 option may be overriden with -spacing3 options in tags.
49 Name: state
51 Class: State
52 Switch: -state
53 Specifies one of two states for the text: normal or disabled. If
54 the text is disabled then characters may not be inserted or deleted
55 and no insertion cursor will be displayed, even if the input focus
56 is in the widget.
57 Name: tabs
59 Class: Tabs
60 Switch: -tabs
61 Specifies a set of tab stops for the window. The option's value
62 consists of a list of screen distances giving the positions of the
63 tab stops. Each position may optionally be followed in the next
64 list element by one of the keywords left, right, center, or
65 numeric, which specifies how to justify text relative to the tab
66 stop. Left is the default; it causes the text following the tab
67 character to be positioned with its left edge at the tab position.
68 Right means that the right edge of the text following the tab char‐
69 acter is positioned at the tab position, and center means that the
70 text is centered at the tab position. Numeric means that the deci‐
71 mal point in the text is positioned at the tab position; if there
72 is no decimal point then the least significant digit of the number
73 is positioned just to the left of the tab position; if there is no
74 number in the text then the text is right-justified at the tab
75 position. For example, -tabs => [qw/2c left 4c 6c center/] creates
76 three tab stops at two-centimeter intervals; the first two use
77 left justification and the third uses center justification. If the
78 list of tab stops does not have enough elements to cover all of the
79 tabs in a text line, then Tk extrapolates new tab stops using the
80 spacing and alignment from the last tab stop in the list. The
81 value of the tabs option may be overridden by -tabs options in
82 tags. If no -tabs option is specified, or if it is specified as an
83 empty list, then Tk uses default tabs spaced every eight (average
84 size) characters.
85 Name: width
87 Class: Width
88 Switch: -width
89 Specifies the desired width for the window in units of characters
90 in the font given by the -font option. If the font doesn't have a
91 uniform width then the width of the character ``0'' is used in
92 translating from character units to screen units.
93 Name: wrap
95 Class: Wrap
96 Switch: -wrap
97 Specifies how to handle lines in the text that are too long to be
98 displayed in a single line of the text's window. The value must be
99 none or char or word. A wrap mode of none means that each line of
100 text appears as exactly one line on the screen; extra characters
101 that don't fit on the screen are not displayed. In the other modes
102 each line of text will be broken up into several screen lines if
103 necessary to keep all the characters visible. In char mode a
104 screen line break may occur after any character; in word mode a
105 line break will only be made at word boundaries.
106
108 The Text method creates a new window (given by the $text argument) and
109 makes it into a text widget. Additional options, described above, may
110 be specified on the command line or in the option database to configure
111 aspects of the text such as its default background color and relief.
112 The text command returns the path name of the new window.
113 A text widget displays one or more lines of text and allows that text
115 to be edited. Text widgets support four different kinds of annotations
116 on the text, called tags, marks, embedded windows or embedded images.
117 Tags allow different portions of the text to be displayed with differ‐
118 ent fonts and colors. In addition, perl/Tk callbacks can be associated
119 with tags so that scripts are invoked when particular actions such as
120 keystrokes and mouse button presses occur in particular ranges of the
121 text. See "TAGS" below for more details.
122 The second form of annotation consists of marks, which are floating
124 markers in the text. Marks are used to keep track of various interest‐
125 ing positions in the text as it is edited. See "MARKS" below for more
126 details.
127 The third form of annotation allows arbitrary windows to be embedded in
129 a text widget. See "EMBEDDED WINDOWS" below for more details.
130 The fourth form of annotation allows Tk images to be embedded in a text
132 widget. See "EMBEDDED IMAGES" below for more details.
133 The Perl/Tk Text widget does not support undo/redo, use the TextUndo
135 widget instead.
136
138 Many of the methods for texts take one or more indices as arguments.
139 An index is a string used to indicate a particular place within a text,
140 such as a place to insert characters or one endpoint of a range of
141 characters to delete. Indices have the syntax
142 base modifier modifier modifier ...
144 Where base gives a starting point and the modifiers adjust the index
146 from the starting point (e.g. move forward or backward one character).
147 Every index must contain a base, but the modifiers are optional.
148 The base for an index must have one of the following forms:
150 line.char
152 Indicates char'th character on line line. Lines are numbered from
153 1 for consistency with other UNIX programs that use this numbering
154 scheme. Within a line, characters are numbered from 0. If char is
155 end then it refers to the newline character that ends the line.
156 @x,y
158 Indicates the character that covers the pixel whose x and y coordi‐
159 nates within the text's window are x and y.
160 end Indicates the end of the text (the character just after the last
162 newline).
163 mark
165 Indicates the character just after the mark whose name is mark.
166 tag.first
168 Indicates the first character in the text that has been tagged with
169 tag. This form generates an error if no characters are currently
170 tagged with tag.
171 tag.last
173 Indicates the character just after the last one in the text that
174 has been tagged with tag. This form generates an error if no char‐
175 acters are currently tagged with tag.
176 $widget
178 Indicates the position of the embedded window referenced by $wid‐
179 get. This form generates an error if $widget does not reference to
180 an embedded window.
181 imageName
183 Indicates the position of the embedded image whose name is image‐
184 Name. This form generates an error if there is no embedded image
185 by the given name.
186 If the base could match more than one of the above forms, such as a
188 mark and imageName both having the same value, then the form ear‐
189 lier in the above list takes precedence. If modifiers follow the
190 base index, each one of them must have one of the forms listed
191 below. Keywords such as chars and wordend may be abbreviated as
192 long as the abbreviation is unambiguous.
193 + count chars
195 Adjust the index forward by count characters, moving to later lines
196 in the text if necessary. If there are fewer than count characters
197 in the text after the current index, then set the index to the last
198 character in the text. Spaces on either side of count are
199 optional.
200 - count chars
202 Adjust the index backward by count characters, moving to earlier
203 lines in the text if necessary. If there are fewer than count
204 characters in the text before the current index, then set the index
205 to the first character in the text. Spaces on either side of count
206 are optional.
207 + count lines
209 Adjust the index forward by count lines, retaining the same charac‐
210 ter position within the line. If there are fewer than count lines
211 after the line containing the current index, then set the index to
212 refer to the same character position on the last line of the text.
213 Then, if the line is not long enough to contain a character at the
214 indicated character position, adjust the character position to
215 refer to the last character of the line (the newline). Spaces on
216 either side of count are optional.
217 - count lines
219 Adjust the index backward by count lines, retaining the same char‐
220 acter position within the line. If there are fewer than count
221 lines before the line containing the current index, then set the
222 index to refer to the same character position on the first line of
223 the text. Then, if the line is not long enough to contain a char‐
224 acter at the indicated character position, adjust the character
225 position to refer to the last character of the line (the newline).
226 Spaces on either side of count are optional.
227 linestart
229 Adjust the index to refer to the first character on the line.
230 lineend
232 Adjust the index to refer to the last character on the line (the
233 newline).
234 wordstart
236 Adjust the index to refer to the first character of the word con‐
237 taining the current index. A word consists of any number of adja‐
238 cent characters that are letters, digits, or underscores, or a sin‐
239 gle character that is not one of these.
240 wordend
242 Adjust the index to refer to the character just after the last one
243 of the word containing the current index. If the current index
244 refers to the last character of the text then it is not modified.
245 If more than one modifier is present then they are applied in left-
247 to-right order. For example, the index ``end - 1 chars'' refers to
248 the next-to-last character in the text and ``insert wordstart - 1
249 c'' refers to the character just before the first one in the word
250 containing the insertion cursor.
251
253 The first form of annotation in text widgets is a tag. A tag is a tex‐
254 tual string that is associated with some of the characters in a text.
255 Tags may contain arbitrary characters, but it is probably best to avoid
256 using the the characters `` '' (space), +, or -: these characters have
257 special meaning in indices, so tags containing them can't be used as
258 indices. There may be any number of tags associated with characters in
259 a text. Each tag may refer to a single character, a range of charac‐
260 ters, or several ranges of characters. An individual character may
261 have any number of tags associated with it.
262 A priority order is defined among tags, and this order is used in
264 implementing some of the tag-related functions described below. When a
265 tag is defined (by associating it with characters or setting its dis‐
266 play options or binding callbacks to it), it is given a priority higher
267 than any existing tag. The priority order of tags may be redefined
268 using the ``$text->tagRaise'' and ``$text->tagLower'' methods.
269 Tags serve three purposes in text widgets. First, they control the way
271 information is displayed on the screen. By default, characters are
272 displayed as determined by the background, font, and foreground options
273 for the text widget. However, display options may be associated with
274 individual tags using the ``$text->tagConfigure'' method. If a charac‐
275 ter has been tagged, then the display options associated with the tag
276 override the default display style. The following options are cur‐
277 rently supported for tags:
278 -background => color
280 Color specifies the background color to use for characters associ‐
281 ated with the tag. It may have any of the forms accepted by
282 Tk_GetColor.
283 -bgstipple => bitmap
285 Bitmap specifies a bitmap that is used as a stipple pattern for the
286 background. It may have any of the forms accepted by Tk_GetBitmap.
287 If bitmap hasn't been specified, or if it is specified as an empty
288 string, then a solid fill will be used for the background.
289 -borderwidth => pixels
291 Pixels specifies the width of a 3-D border to draw around the back‐
292 ground. It may have any of the forms accepted by Tk_GetPixels.
293 This option is used in conjunction with the -relief option to give
294 a 3-D appearance to the background for characters; it is ignored
295 unless the -background option has been set for the tag.
296 -elide => boolean
298 Elide specifies whether the data should be elided. Elided data is
299 not displayed and takes no space on screen, but further on
300 behaves just as normal data.
301 -data => value
303 Allows an arbitrary perl scalar value to be associated with the
304 tag.
305 -fgstipple => bitmap
307 Bitmap specifies a bitmap that is used as a stipple pattern when
308 drawing text and other foreground information such as underlines.
309 It may have any of the forms accepted by Tk_GetBitmap. If bitmap
310 hasn't been specified, or if it is specified as an empty string,
311 then a solid fill will be used.
312 -font => fontName
314 FontName is the name of a font to use for drawing characters. It
315 may have any of the forms accepted by Tk_GetFontStruct.
316 -foreground => color
318 Color specifies the color to use when drawing text and other fore‐
319 ground information such as underlines. It may have any of the
320 forms accepted by Tk_GetColor.
321 -justify => justify
323 If the first character of a display line has a tag for which this
324 option has been specified, then justify determines how to justify
325 the line. It must be one of left, right, or center. If a line
326 wraps, then the justification for each line on the display is
327 determined by the first character of that display line.
328 -lmargin1 => pixels
330 If the first character of a text line has a tag for which this
331 option has been specified, then pixels specifies how much the line
332 should be indented from the left edge of the window. Pixels may
333 have any of the standard forms for screen distances. If a line of
334 text wraps, this option only applies to the first line on the dis‐
335 play; the -lmargin2 option controls the indentation for subsequent
336 lines.
337 -lmargin2 => pixels
339 If the first character of a display line has a tag for which this
340 option has been specified, and if the display line is not the first
341 for its text line (i.e., the text line has wrapped), then pixels
342 specifies how much the line should be indented from the left edge
343 of the window. Pixels may have any of the standard forms for
344 screen distances. This option is only used when wrapping is
345 enabled, and it only applies to the second and later display lines
346 for a text line.
347 -offset => pixels
349 Pixels specifies an amount by which the text's baseline should be
350 offset vertically from the baseline of the overall line, in pixels.
351 For example, a positive offset can be used for superscripts and a
352 negative offset can be used for subscripts. Pixels may have any of
353 the standard forms for screen distances.
354 -overstrike => boolean
356 Specifies whether or not to draw a horizontal rule through the mid‐
357 dle of characters. Boolean may have any of the forms accepted by
358 Tk_GetBoolean.
359 -relief => relief
361 Relief specifies the 3-D relief to use for drawing backgrounds, in
362 any of the forms accepted by Tk_GetRelief. This option is used in
363 conjunction with the -borderwidth option to give a 3-D appearance
364 to the background for characters; it is ignored unless the -back‐
365 ground option has been set for the tag.
366 -rmargin => pixels
368 If the first character of a display line has a tag for which this
369 option has been specified, then pixels specifies how wide a margin
370 to leave between the end of the line and the right edge of the win‐
371 dow. Pixels may have any of the standard forms for screen dis‐
372 tances. This option is only used when wrapping is enabled. If a
373 text line wraps, the right margin for each line on the display is
374 determined by the first character of that display line.
375 -spacing1 => pixels
377 Pixels specifies how much additional space should be left above
378 each text line, using any of the standard forms for screen dis‐
379 tances. If a line wraps, this option only applies to the first
380 line on the display.
381 -spacing2 => pixels
383 For lines that wrap, this option specifies how much additional
384 space to leave between the display lines for a single text line.
385 Pixels may have any of the standard forms for screen distances.
386 -spacing3 => pixels
388 Pixels specifies how much additional space should be left below
389 each text line, using any of the standard forms for screen dis‐
390 tances. If a line wraps, this option only applies to the last line
391 on the display.
392 -tabs => tabList
394 TabList specifies a set of tab stops in the same form as for the
395 -tabs option for the text widget. This option only applies to a
396 display line if it applies to the first character on that display
397 line. If this option is specified as an empty string, it cancels
398 the option, leaving it unspecified for the tag (the default). If
399 the option is specified as a non-empty string that is an empty
400 list, such as -tabs = " ">, then it requests default 8-character
401 tabs as described for the tabs widget option.
402 -underline => boolean
404 Boolean specifies whether or not to draw an underline underneath
405 characters. It may have any of the forms accepted by Tk_Get‐
406 Boolean.
407 -wrap => mode
409 Mode specifies how to handle lines that are wider than the text's
410 window. It has the same legal values as the -wrap option for the
411 text widget: none, char, or word. If this tag option is speci‐
412 fied, it overrides the -wrap option for the text widget.
413 If a character has several tags associated with it, and if their dis‐
415 play options conflict, then the options of the highest priority tag are
416 used. If a particular display option hasn't been specified for a par‐
417 ticular tag, or if it is specified as an empty string, then that option
418 will never be used; the next-highest-priority tag's option will used
419 instead. If no tag specifies a particular display option, then the
420 default style for the widget will be used.
421 The second purpose for tags is event bindings. You can associate bind‐
423 ings with a tag in much the same way you can associate bindings with a
424 widget class: whenever particular X events occur on characters with
425 the given tag, a given <perl/Tk callback⎪Tk::callbacks> will be exe‐
426 cuted. Tag bindings can be used to give behaviors to ranges of charac‐
427 ters; among other things, this allows hypertext-like features to be
428 implemented. For details, see the description of the tagBind widget
429 method below.
430 The third use for tags is in managing the selection. See "THE SELEC‐
432 TION" below.
433
435 The second form of annotation in text widgets is a mark. Marks are
436 used for remembering particular places in a text. They are something
437 like tags, in that they have names and they refer to places in the
438 file, but a mark isn't associated with particular characters. Instead,
439 a mark is associated with the gap between two characters. Only a sin‐
440 gle position may be associated with a mark at any given time. If the
441 characters around a mark are deleted the mark will still remain; it
442 will just have new neighbor characters. In contrast, if the characters
443 containing a tag are deleted then the tag will no longer have an asso‐
444 ciation with characters in the file. Marks may be manipulated with the
445 ``$text->mark'' text widget method, and their current locations may be
446 determined by using the mark name as an index in methods.
447 Each mark also has a gravity, which is either left or right. The grav‐
449 ity for a mark specifies what happens to the mark when text is inserted
450 at the point of the mark. If a mark has left gravity, then the mark is
451 treated as if it were attached to the character on its left, so the
452 mark will remain to the left of any text inserted at the mark position.
453 If the mark has right gravity, new text inserted at the mark position
454 will appear to the right of the mark. The gravity for a mark defaults
455 to right.
456 The name space for marks is different from that for tags: the same
458 name may be used for both a mark and a tag, but they will refer to dif‐
459 ferent things.
460 Two marks have special significance. First, the mark insert is associ‐
462 ated with the insertion cursor, as described under "THE INSERTION CUR‐
463 SOR" below. Second, the mark current is associated with the character
464 closest to the mouse and is adjusted automatically to track the mouse
465 position and any changes to the text in the widget (one exception:
466 current is not updated in response to mouse motions if a mouse button
467 is down; the update will be deferred until all mouse buttons have been
468 released). Neither of these special marks may be deleted.
469
471 The third form of annotation in text widgets is an embedded window.
472 Each embedded window annotation causes a window to be displayed at a
473 particular point in the text. There may be any number of embedded
474 windows in a text widget, and any widget may be used as an embedded
475 window (subject to the usual rules for geometry management, which
476 require the text window to be the parent of the embedded window or a
477 descendant of its parent). The embedded window's position on the
478 screen will be updated as the text is modified or scrolled, and it will
479 be mapped and unmapped as it moves into and out of the visible area of
480 the text widget. Each embedded window occupies one character's worth
481 of index space in the text widget, and it may be referred to either by
482 the name of its embedded window or by its position in the widget's
483 index space. If the range of text containing the embedded window is
484 deleted then the window is destroyed.
485 When an embedded window is added to a text widget with the widgetCreate
487 method, several configuration options may be associated with it. These
488 options may be modified later with the widgetConfigure method. The
489 following options are currently supported:
490 -align => where
492 If the window is not as tall as the line in which it is displayed,
493 this option determines where the window is displayed in the line.
494 Where must have one of the values top (align the top of the window
495 with the top of the line), center (center the window within the
496 range of the line), bottom (align the bottom of the window with the
497 bottom of the line's area), or baseline (align the bottom of the
498 window with the baseline of the line).
499 -create => callback
501 Specifies a callback that may be evaluated to create the window for
502 the annotation. If no -window option has been specified for the
503 annotation this callback will be evaluated when the annotation is
504 about to be displayed on the screen. Callback must create a window
505 for the annotation and return the name of that window as its
506 result. If the annotation's window should ever be deleted, call‐
507 back will be evaluated again the next time the annotation is dis‐
508 played.
509 -padx => pixels
511 Pixels specifies the amount of extra space to leave on each side of
512 the embedded window. It may have any of the usual forms defined
513 for a screen distance (see Tk_GetPixels).
514 -pady => pixels
516 Pixels specifies the amount of extra space to leave on the top and
517 on the bottom of the embedded window. It may have any of the usual
518 forms defined for a screen distance (see Tk_GetPixels).
519 -stretch => boolean
521 If the requested height of the embedded window is less than the
522 height of the line in which it is displayed, this option can be
523 used to specify whether the window should be stretched vertically
524 to fill its line. If the -pady option has been specified as well,
525 then the requested padding will be retained even if the window is
526 stretched.
527 -window => $widget
529 Specifies the name of a window to display in the annotation.
530
532 The final form of annotation in text widgets is an embedded image.
533 Each embedded image annotation causes an image to be displayed at a
534 particular point in the text. There may be any number of embedded
535 images in a text widget, and a particular image may be embedded in mul‐
536 tiple places in the same text widget. The embedded image's position on
537 the screen will be updated as the text is modified or scrolled. Each
538 embedded image occupies one character's worth of index space in the
539 text widget, and it may be referred to either by its position in the
540 widget's index space, or the name it is assigned when the image is
541 inserted into the text widget with imageCreate. If the range of text
542 containing the embedded image is deleted then that copy of the image is
543 removed from the screen.
544 When an embedded image is added to a text widget with the image create
546 method, a name unique to this instance of the image is returned. This
547 name may then be used to refer to this image instance. The name is
548 taken to be the value of the -name option (described below). If the
549 -name option is not provided, the -image name is used instead. If the
550 imageName is already in use in the text widget, then #nn is added to
551 the end of the imageName, where nn is an arbitrary integer. This
552 insures the imageName is unique. Once this name is assigned to this
553 instance of the image, it does not change, even though the -image or
554 -name values can be changed with image configure.
555 When an embedded image is added to a text widget with the imageCreate
557 method, several configuration options may be associated with it. These
558 options may be modified later with the image configure method. The
559 following options are currently supported:
560 -align => where
562 If the image is not as tall as the line in which it is displayed,
563 this option determines where the image is displayed in the line.
564 Where must have one of the values top (align the top of the image
565 with the top of the line), center (center the image within the
566 range of the line), bottom (align the bottom of the image with the
567 bottom of the line's area), or baseline (align the bottom of the
568 image with the baseline of the line).
569 -image => image
571 Specifies the name of the Tk image to display in the annotation.
572 If image is not a valid Tk image, then an error is returned.
573 -name => ImageName
575 Specifies the name by which this image instance may be referenced
576 in the text widget. If ImageName is not supplied, then the name of
577 the Tk image is used instead. If the imageName is already in use,
578 #nn is appended to the end of the name as described above.
579 -padx => pixels
581 Pixels specifies the amount of extra space to leave on each side of
582 the embedded image. It may have any of the usual forms defined for
583 a screen distance.
584 -pady => pixels
586 Pixels specifies the amount of extra space to leave on the top and
587 on the bottom of the embedded image. It may have any of the usual
588 forms defined for a screen distance.
589
591 Selection support is implemented via tags. If the exportSelection
592 option for the text widget is true then the sel tag will be associated
593 with the selection:
594 [1] Whenever characters are tagged with sel the text widget will claim
596 ownership of the selection.
597 [2] Attempts to retrieve the selection will be serviced by the text
599 widget, returning all the characters with the sel tag.
600 [3] If the selection is claimed away by another application or by
602 another window within this application, then the sel tag will be
603 removed from all characters in the text.
604 [4] Whenever the sel tag range changes a virtual event <<Selection>> is
606 generated.
607 The sel tag is automatically defined when a text widget is created,
609 and it may not be deleted with the ``$text->tagDelete'' method.
610 Furthermore, the selectBackground, selectBorderWidth, and select‐
611 Foreground options for the text widget are tied to the -background,
612 -borderwidth, and -foreground options for the sel tag: changes in
613 either will automatically be reflected in the other.
614
616 The mark named insert has special significance in text widgets. It is
617 defined automatically when a text widget is created and it may not be
618 unset with the ``$text->markUnset'' widget command. The insert mark
619 represents the position of the insertion cursor, and the insertion cur‐
620 sor will automatically be drawn at this point whenever the text widget
621 has the input focus.
622
624 The text widget can keep track of changes to the content of the widget
625 by means of the modified flag. Inserting or deleting text will set this
626 flag. The flag can be queried, set and cleared programatically as well.
627 Whenever the flag changes state a <<Modified>> virtual event is gener-
628 ated. See the edit modified widget command for more details.
629
631 The Text method creates a widget object. This object supports the con‐
632 figure and cget methods described in Tk::options which can be used to
633 enquire and modify the options described above. The widget also inher‐
634 its all the methods provided by the generic Tk::Widget class.
635 The following additional methods are available for text widgets. In
637 addition, the extended text widget methods as documented in "Mastering
638 Perl/Tk" are included in this pod (with permission from the publisher,
639 O'Reilly and Associates Inc.).
640 $text->adjustSelect
642 Moves the end point of the selection and anchor point to the mouse
643 pointer location.
644 $text->bbox(index)
646 Returns a list of four elements describing the screen area of the
647 character given by index. The first two elements of the list give
648 the x and y coordinates of the upper-left corner of the area occu‐
649 pied by the character, and the last two elements give the width and
650 height of the area. If the character is only partially visible on
651 the screen, then the return value reflects just the visible part.
652 If the character is not visible on the screen then the return value
653 is an empty list.
654 $text->clipboardColumnCopy
656 Performs a rectangular copy of the currently selected text with
657 basic compensation for tab characters.
658 $text->clipboardColumnCut
660 Performs a rectangular cut of the currently selected text with
661 basic compensation for tab characters.
662 $text->clipboardColumnPaste
664 Performs a rectangular paste of the text in the clipboard. The
665 upper-left corner is specified by the current position of the
666 insert mark with basic compensation for tab characters.
667 $text->compare(index1, op, index2)
669 Compares the indices given by index1 and index2 according to the
670 relational operator given by op, and returns 1 if the relationship
671 is satisfied and 0 if it isn't. Op must be one of the operators <,
672 <=, ==, >=, >, or !=. If op is == then 1 is returned if the two
673 indices refer to the same character, if op is < then 1 is returned
674 if index1 refers to an earlier character in the text than index2,
675 and so on.
676 $text->Contents(?args?)
678 Query or change the entire contents of the text widget. If no argu‐
679 ments are given, the entire contents of the text widget are
680 returned. If any arguments are given, the entire contents of the
681 text widget are deleted and replaced by the argument list.
682 $text->debug(?boolean?)
684 If boolean is specified, then it must have one of the true or false
685 values accepted by Tcl_GetBoolean. If the value is a true one then
686 internal consistency checks will be turned on in the B-tree code
687 associated with text widgets. If boolean has a false value then
688 the debugging checks will be turned off. In either case the com‐
689 mand returns an empty string. If boolean is not specified then the
690 command returns on or off to indicate whether or not debugging is
691 turned on. There is a single debugging switch shared by all text
692 widgets: turning debugging on or off in any widget turns it on or
693 off for all widgets. For widgets with large amounts of text, the
694 consistency checks may cause a noticeable slow-down.
695 $text->delete(index1, ?index2?)
697 Delete a range of characters from the text. If both index1 and
698 index2 are specified, then delete all the characters starting with
699 the one given by index1 and stopping just before index2 (i.e. the
700 character at index2 is not deleted). If index2 doesn't specify a
701 position later in the text than index1 then no characters are
702 deleted. If index2 isn't specified then the single character at
703 index1 is deleted. It is not allowable to delete characters in a
704 way that would leave the text without a newline as the last charac‐
705 ter. The command returns an empty string. If more indices are
706 given, multiple ranges of text will be deleted. All indices are
707 first checked for validity before any deletions are made. They
708 are sorted and the text is removed from the last range to the first
709 range to deleted text does not cause a undesired index shift‐
710 ing side-effects. If multiple ranges with the same start index
711 are given, then the longest range is used. If overlapping
712 ranges are given, then they will be merged into spans that do not
713 cause deletion of text outside the given ranges due to text
714 shifted during deletion.
715 $text->deleteSelected
717 Delete the currently selected text.
718 $text->deleteTextTaggedWith(tag)
720 Delete the text tagged with the tag parameter.
721 $text->deleteToEndofLine
723 Delete from the insert mark location to the end of line.
724 $text->dlineinfo(index)
726 Returns a list with five elements describing the area occupied by
727 the display line containing index. The first two elements of the
728 list give the x and y coordinates of the upper-left corner of the
729 area occupied by the line, the third and fourth elements give the
730 width and height of the area, and the fifth element gives the posi‐
731 tion of the baseline for the line, measured down from the top of
732 the area. All of this information is measured in pixels. If the
733 current wrap mode is none and the line extends beyond the bound‐
734 aries of the window, the area returned reflects the entire area of
735 the line, including the portions that are out of the window. If
736 the line is shorter than the full width of the window then the area
737 returned reflects just the portion of the line that is occupied by
738 characters and embedded windows. If the display line containing
739 index is not visible on the screen then the return value is an
740 empty list.
741 $text->dump(?switches?, index1, ?index2?)
743 Return the contents of the text widget from index1 up to, but not
744 including index2, including the text and information about marks,
745 tags, and embedded windows. If index2 is not specified, then it
746 defaults to one character past index1. The information is returned
747 in the following format:
748 key1 value1 index1 key2 value2 index2 ...
750 The possible key values are text, mark, tagon, tagoff, and $text.
752 The corresponding value is the text, mark name, tag name, or window
753 name. The index information is the index of the start of the text,
754 the mark, the tag transition, or the window. One or more of the
755 following switches (or abbreviations thereof) may be specified to
756 control the dump:
757 -all
759 Return information about all elements: text, marks, tags, and
760 windows. This is the default.
761 -command => callback
763 Instead of returning the information as the result of the dump
764 operation, invoke the callback on each element of the text wid‐
765 get within the range. The callback has three arguments
766 appended to it before it is evaluated: the key, value, and
767 index.
768 -mark
770 Include information about marks in the dump results.
771 -tag
773 Include information about tag transitions in the dump results.
774 Tag information is returned as tagon and tagoff elements that
775 indicate the begin and end of each range of each tag, respec‐
776 tively.
777 -text
779 Include information about text in the dump results. The value
780 is the text up to the next element or the end of range indi‐
781 cated by index2. A text element does not span newlines. A
782 multi-line block of text that contains no marks or tag transi‐
783 tions will still be dumped as a set of text seqments that each
784 end with a newline. The newline is part of the value.
785 -window
787 Include information about embedded windows in the dump results.
789 The value of a window is its Tk pathname, unless the window has not
790 been created yet. (It must have a create script.) In this case an
791 empty string is returned, and you must query the window by its
792 index position to get more information.
793 $text->edit( option, ?arg, arg ...? );
795 This command controls the undo mechanism and the modified flag.
796 The exact behavior of the command depends on the option argument
797 that follows the edit argument. The following forms of the command
798 are currently supported:
799 $text->editModified( ?boolean? );
801 If boolean is not specified, returns the modified flag of the
802 widget. The insert, delete, edit undo and edit redo commands
803 or the user can set or clear the modified flag. If boolean is
804 specified, sets the modified flag of the widget to boolean.
805 $text->editRedo;
807 (Not implemented, use TextUndo.) When the -undo option is
808 true, reapplies the last undone edits provided no other edits
809 were done since then. Generates an error when the redo stack is
810 empty. Does nothing when the -undo option is false.
811 $text->editReset;
813 (Not implemented, use TextUndo.) Clears the undo and redo
814 stacks.
815 $text->editSeparator;
817 (Not implemented, use TextUndo.) Inserts a separator (boundary)
818 on the undo stack. Does nothing when the -undo option is false.
819 $text->editUndo;
821 (Not implemented, use TextUndo.) Undoes the last edit action
822 when the -undo option is true. An edit action is defined as
823 all the insert and delete commands that are recorded on the
824 undo stack in between two separators. Generates an error when
825 the undo stack is empty. Does nothing when the -undo option is
826 false.
827 $text->FindAll(mode, case, pattern)
829 Removes any current selections and then performs a global text
830 search. All matches are tagged with the sel tag.
831 mode can be be -exact or -regexp. See the search command for more
833 information
834 case can be -nocase or -case. See the search command for more
836 information
837 pattern is an exact string to match if mode is -exact or a regular
839 expression if the match mode is -regexp.
840 $text->FindAndReplaceAll(mode, case, find, replace)
842 Same as the FindAll method, however additionally substitutes the
843 matched text with the characters replace.
844 $text->FindAndReplacePopUp
846 Creates a find-and-replace popup window if one does not already
847 exist. If there is currently selected text, then the 'find' field
848 will be 'pre-filled' with the selection.
849 $text->FindNext(direction, mode, case, pattern)
851 Removes any current selections and then performs a forward or
852 reverse text search. All matches are tagged with the sel tag.
853 direction can be -forward or -reverse. mode, case and pattern are
854 as for the FindAll method.
855 $text->FindPopUp
857 Creates a find popup, if one does not yet exist. If there is cur‐
858 rently selected text, then the 'find' field will be 'pre-filled'
859 with the selection.
860 $text->FindSelectionNext
862 Gets the currently selected text and removes all selections. It
863 then finds the next exact, case-sensitive string that matches in a
864 forward direction and selects the text and makes the new selection
865 visible.
866 $text->FindSelectionPrevious
868 Gets the currently selected text and removes all selections. It
869 then finds the next exact, case-sensitive string that matches in a
870 reverse direction and selects the text and makes the new selection
871 visible.
872 $text->get(index1, ?index2?)
874 Return a range of characters from the text. The return value will
875 be all the characters in the text starting with the one whose index
876 is index1 and ending just before the one whose index is index2 (the
877 character at index2 will not be returned). If index2 is omitted
878 then the single character at index1 is returned. If there are no
879 characters in the specified range (e.g. index1 is past the end of
880 the file or index2 is less than or equal to index1) then an empty
881 string is returned. If the specified range contains embedded win‐
882 dows, no information about them is included in the returned string.
883 If multiple index pairs are given, multiple ranges of text will be
884 returned in a list. Invalid ranges will not be represented with
885 empty strings in the list. The ranges are returned in the order
886 passed to get.
887 $text->getSelected
889 Return the currently selected text.
890 $text->GetTextTaggedWith(tag)
892 Return the text tagged with the tag parameter.
893 $text->GotoLineNumber(line_number)
895 Set the insert mark to line_number and ensures the line is visible.
896 $text->GotoLineNumberPopUp(line_number)
898 Displays a popup, pre-filling it with selected numeric text (if
899 any), or the line number from GotoLineNumber (if any).
900 $text->image(option, ?arg, arg, ...?)
902 $text->imageOption(?arg, arg, ...?)
903 This method is used to manipulate embedded images. The behavior of
904 the method depends on the option argument that follows the image
905 prefix. The following forms of the methods are currently sup‐
906 ported:
907 $text->imageCget(index, option)
909 Returns the value of a configuration option for an embedded
910 image. Index identifies the embedded image, and option
911 specifies a particular configuration option, which must be
912 one of the ones listed in "EMBEDDED IMAGES".
913 $text->imageConfigure(index, ?option, value, ...?)
915 Query or modify the configuration options for an embedded
916 image. If no option is specified, returns a list describ‐
917 ing all of the available options for the embedded image at
918 index (see Tk::options for information on the format of
919 this list). If option is specified with no value, then the
920 command returns a list describing the one named option
921 (this list will be identical to the corresponding sublist
922 of the value returned if no option is specified). If one
923 or more option-value pairs are specified, then the command
924 modifies the given option(s) to have the given value(s);
925 in this case the command returns an empty string. See
926 "EMBEDDED IMAGES" for information on the options that are
927 supported.
928 $text->imageCreate(index, ?option, value, ...?)
930 This command creates a new image annotation, which will
931 appear in the text at the position given by index. Any
932 number of option-value pairs may be specified to configure
933 the annotation. Returns a unique identifier that may be
934 used as an index to refer to this image. See "EMBEDDED
935 IMAGES" for information on the options that are supported,
936 and a description of the identifier returned.
937 $text->imageNames
939 Returns a list whose elements are the names of all image
940 instances currently embedded in $text.
941 $text->index(index)
943 Returns the position corresponding to index in the form line.char
944 where line is the line number and char is the character number.
945 Index may have any of the forms described under "INDICES" above.
946 $text->insert(index, chars, ?tagList, chars, tagList, ...?)
948 Inserts all of the chars arguments just before the character at
949 index. If index refers to the end of the text (the character after
950 the last newline) then the new text is inserted just before the
951 last newline instead. If there is a single chars argument and no
952 tagList, then the new text will receive any tags that are present
953 on both the character before and the character after the insertion
954 point; if a tag is present on only one of these characters then it
955 will not be applied to the new text. If tagList is specified then
956 it consists of a list of tag names; the new characters will
957 receive all of the tags in this list and no others, regardless of
958 the tags present around the insertion point. If multiple
959 chars-tagList argument pairs are present, they produce the same
960 effect as if a separate insert widget command had been issued for
961 each pair, in order. The last tagList argument may be omitted.
962 $text->Insert(string)
964 Do NOT confuse this with the lower-case insert method. Insert
965 string at the point of the insertion cursor. If there is a selec‐
966 tion in the text, and it covers the point of the insertion cursor,
967 then it deletes the selection before inserting.
968 $text->InsertKeypress(character)
970 Inserts character at the insert mark. If in overstrike mode, it
971 firsts deletes the character at the insert mark.
972 $text->InsertSelection
974 Inserts the current selection at the insert mark.
975 $text->insertTab
977 Inserts a tab (\t) character at the insert mark.
978 $text->mark(option, ?arg, arg, ...?)
980 This command is used to manipulate marks. The exact behavior of
981 the command depends on the option argument that follows the mark
982 argument. The following forms of the command are currently sup‐
983 ported:
984 $text->markGravity(markName, ?direction?)
986 If direction is not specified, returns left or right to
987 indicate which of its adjacent characters markName is
988 attached to. If direction is specified, it must be left or
989 right; the gravity of markName is set to the given value.
990 $text->markNames
992 Returns a list whose elements are the names of all the
993 marks that are currently set.
994 $text->markNext(index)
996 Returns the name of the next mark at or after index. If
997 index is specified in numerical form, then the search for
998 the next mark begins at that index. If index is the name
999 of a mark, then the search for the next mark begins immedi‐
1000 ately after that mark. This can still return a mark at the
1001 same position if there are multiple marks at the same
1002 index. These semantics mean that the mark next operation
1003 can be used to step through all the marks in a text widget
1004 in the same order as the mark information returned by the
1005 dump operation. If a mark has been set to the special end
1006 index, then it appears to be after end with respect to the
1007 mark next operation. An empty string is returned if there
1008 are no marks after index.
1009 $text->markPrevious(index)
1011 Returns the name of the mark at or before index. If index
1012 is specified in numerical form, then the search for the
1013 previous mark begins with the character just before that
1014 index. If index is the name of a mark, then the search for
1015 the next mark begins immediately before that mark. This
1016 can still return a mark at the same position if there are
1017 multiple marks at the same index. These semantics mean
1018 that the mark previous operation can be used to step
1019 through all the marks in a text widget in the reverse order
1020 as the mark information returned by the dump operation. An
1021 empty string is returned if there are no marks before
1022 index.
1023 $text->markSet(markName, index)
1025 Sets the mark named markName to a position just before the
1026 character at index. If markName already exists, it is
1027 moved from its old position; if it doesn't exist, a new
1028 mark is created. This command returns an empty string.
1029 $text->markUnset(markName?, markName, markName, ...?)
1031 Remove the mark corresponding to each of the markName argu‐
1032 ments. The removed marks will not be usable in indices and
1033 will not be returned by future calls to ``$text->mark‐
1034 Names''. This command returns an empty string.
1035 $text->markExists(markname)
1037 Returns true if markname exists - false otherwise.
1038 $text->menu(?menu?)
1040 If menu reference is given as an argument, then the text widget
1041 menu is adjusted to use this new menu. If the menu argument is
1042 undef, then this command disables the current text widget menu. If
1043 the menu argument is omitted altogether, then the current text wid‐
1044 get menu reference is returned.
1045 $text->openLine
1047 Inserts a newline (\n) at the insert mark.
1048 $text->OverstrikeMode(?boolean?)
1050 Returns the overstrike mode if boolean is omitted or sets the over‐
1051 strike mode to boolean. True means overstrike mode is enabled.
1052 $text->PostPopupMenu(x,y)
1054 Creates a popup menu at the specified (x,y) pixel coordinates. The
1055 default menu has File, Edit, Search and View menu items which cas‐
1056 cade to sub-menus for further commands. There is an implicit <But‐
1057 ton-3> binding to this method that posts the menu over the cursor.
1058 $text->ResetAnchor
1060 Sets the selection anchor to whichever end is farthest from the
1061 index argument.
1062 $text->scan(option, args) or
1064 $text->scanoption(args)
1065 This method is used to implement scanning on texts. It has two
1066 forms, depending on option:
1067 $text->scanMark(x, y)
1069 Records x and y and the current view in the text window,
1070 for use in conjunction with later scanDragto method. Typi‐
1071 cally this method is associated with a mouse button press
1072 in the widget. It returns an empty string.
1073 $text->scanDragto(x, y)
1075 This command computes the difference between its x and y
1076 arguments and the x and y arguments to the last scanMark
1077 method for the widget. It then adjusts the view by 10
1078 times the difference in coordinates. This command is typi‐
1079 cally associated with mouse motion events in the widget, to
1080 produce the effect of dragging the text at high speed
1081 through the window. The return value is an empty string.
1082 $text->search(?switches,? pattern, index, ?stopIndex?)
1084 Searches the text in $text starting at index for a range of charac‐
1085 ters that matches pattern. If a match is found, the index of the
1086 first character in the match is returned as result; otherwise an
1087 empty string is returned. One or more of the following switches
1088 (or abbreviations thereof) may be specified to control the search:
1089 -forwards
1091 The search will proceed forward through the text, finding
1092 the first matching range starting at or after the position
1093 given by index. This is the default.
1094 -backwards
1096 The search will proceed backward through the text, finding
1097 the matching range closest to index whose first character
1098 is before index.
1099 -exact Use exact matching: the characters in the matching range
1101 must be identical to those in pattern. This is the
1102 default.
1103 -regexp Treat pattern as a regular expression and match it against
1105 the text using the rules for regular expressions (see the
1106 regexp command for details).
1107 -nocase Ignore case differences between the pattern and the text.
1109 -count varName
1111 The argument following -count gives the name of a variable;
1112 if a match is found, the number of characters in the match‐
1113 ing range will be stored in the variable.
1114 -hidden Find hidden text as well. By default only displayed text is
1116 found.
1117 -- This switch has no effect except to terminate the list of
1119 switches: the next argument will be treated as pattern even
1120 if it starts with -.
1121 The matching range must be entirely within a single line of text. For
1123 regular expression matching the newlines are removed from the ends of
1124 the lines before matching: use the $ feature in regular expressions to
1125 match the end of a line. For exact matching the newlines are retained.
1126 If stopIndex is specified, the search stops at that index: for forward
1127 searches, no match at or after stopIndex will be considered; for back‐
1128 ward searches, no match earlier in the text than stopIndex will be con‐
1129 sidered. If stopIndex is omitted, the entire text will be searched:
1130 when the beginning or end of the text is reached, the search continues
1131 at the other end until the starting location is reached again; if
1132 stopIndex is specified, no wrap-around will occur.
1133 $text->see(index)
1135 Adjusts the view in the window so that the character given by index
1136 is completely visible. If index is already visible then the com‐
1137 mand does nothing. If index is a short distance out of view, the
1138 command adjusts the view just enough to make index visible at the
1139 edge of the window. If index is far out of view, then the command
1140 centers index in the window.
1141 $text->selectAll
1143 Selects all the text in the widget.
1144 $text->selectLine
1146 Selects the line with the insert mark.
1147 $text->selectWord
1149 Selects the word with the insert mark.
1150 $text->SetCursor(position)
1152 Moves the insert mark to position.
1153 $text->tag(option, ?arg, arg, ...?)
1155 This command is used to manipulate tags. The exact behavior of the
1156 command depends on the option argument that follows the tag argu‐
1157 ment. The following forms of the command are currently supported:
1158 $text->tagAdd(tagName, index1, ?index2, index1, index2, ...?)
1160 Associate the tag tagName with all of the characters start‐
1161 ing with index1 and ending just before index2 (the charac‐
1162 ter at index2 isn't tagged). A single command may contain
1163 any number of index1-index2 pairs. If the last index2 is
1164 omitted then the single character at index1 is tagged. If
1165 there are no characters in the specified range (e.g. index1
1166 is past the end of the file or index2 is less than or equal
1167 to index1) then the command has no effect.
1168 $text->tagBind(tagName, ?sequence?, ?script?)
1170 This command associates script with the tag given by tag‐
1171 Name. Whenever the event sequence given by sequence occurs
1172 for a character that has been tagged with tagName, the
1173 script will be invoked. This method is similar to the bind
1174 command except that it operates on characters in a text
1175 rather than entire widgets. See the Tk::bind documentation
1176 for complete details on the syntax of sequence and the sub‐
1177 stitutions performed on script before invoking it. If all
1178 arguments are specified then a new binding is created,
1179 replacing any existing binding for the same sequence and
1180 tagName (if the first character of script is ``+'' then
1181 script augments an existing binding rather than replacing
1182 it). In this case the return value is an empty string. If
1183 script is omitted then the command returns the script asso‐
1184 ciated with tagName and sequence (an error occurs if there
1185 is no such binding). If both script and sequence are omit‐
1186 ted then the command returns a list of all the sequences
1187 for which bindings have been defined for tagName.
1188 The only events for which bindings may be specified are
1190 those related to the mouse and keyboard (such as Enter,
1191 Leave, ButtonPress, Motion, and KeyPress) or virtual
1192 events. Event bindings for a text widget use the current
1193 mark described under "MARKS" above. An Enter event trig‐
1194 gers for a tag when the tag first becomes present on the
1195 current character, and a Leave event triggers for a tag
1196 when it ceases to be present on the current character.
1197 Enter and Leave events can happen either because the cur‐
1198 rent mark moved or because the character at that position
1199 changed. Note that these events are different than Enter
1200 and Leave events for windows. Mouse and keyboard events
1201 are directed to the current character. If a virtual event
1202 is used in a binding, that binding can trigger only if the
1203 virtual event is defined by an underlying mouse-related or
1204 keyboard-related event.
1205 It is possible for the current character to have multiple
1207 tags, and for each of them to have a binding for a particu‐
1208 lar event sequence. When this occurs, one binding is
1209 invoked for each tag, in order from lowest-priority to
1210 highest priority. If there are multiple matching bindings
1211 for a single tag, then the most specific binding is chosen
1212 (see the the documentation for the bind command for
1213 details). continue and break commands within binding
1214 scripts are processed in the same way as for bindings cre‐
1215 ated with the bind command.
1216 If bindings are created for the widget as a whole using the
1218 bind command, then those bindings will supplement the tag
1219 bindings. The tag bindings will be invoked first, followed
1220 by bindings for the window as a whole.
1221 $text->tagCget(tagName, option)
1223 This command returns the current value of the option named
1224 option associated with the tag given by tagName. Option
1225 may have any of the values accepted by the tag configure
1226 method.
1227 $text->tagConfigure(tagName, ?option?, ?value?, ?option, value,
1229 ...?)
1230 This command is similar to the configure method except that
1231 it modifies options associated with the tag given by tag‐
1232 Name instead of modifying options for the overall text wid‐
1233 get. If no option is specified, the command returns a list
1234 describing all of the available options for tagName (see
1235 Tk::options for information on the format of this list).
1236 If option is specified with no value, then the command
1237 returns a list describing the one named option (this list
1238 will be identical to the corresponding sublist of the value
1239 returned if no option is specified). If one or more
1240 option-value pairs are specified, then the command modifies
1241 the given option(s) to have the given value(s) in tagName;
1242 in this case the command returns an empty string. See
1243 "TAGS" above for details on the options available for tags.
1244 $text->tagDelete(tagName, ?tagName, ...?)
1246 Deletes all tag information for each of the tagName argu‐
1247 ments. The command removes the tags from all characters in
1248 the file and also deletes any other information associated
1249 with the tags, such as bindings and display information.
1250 The command returns an empty string.
1251 $text->tagLower(tagName?, belowThis?)
1253 Changes the priority of tag tagName so that it is just
1254 lower in priority than the tag whose name is belowThis. If
1255 belowThis is omitted, then tagName's priority is changed to
1256 make it lowest priority of all tags.
1257 $text->tagNames(?index?)
1259 Returns a list whose elements are the names of all the tags
1260 that are active at the character position given by index.
1261 If index is omitted, then the return value will describe
1262 all of the tags that exist for the text (this includes all
1263 tags that have been named in a ``$text->tag'' widget com‐
1264 mand but haven't been deleted by a ``$text->tagDelete''
1265 method, even if no characters are currently marked with the
1266 tag). The list will be sorted in order from lowest prior‐
1267 ity to highest priority.
1268 $text->tagNextrange(tagName, index1, ?index2?)
1270 This command searches the text for a range of characters
1271 tagged with tagName where the first character of the range
1272 is no earlier than the character at index1 and no later
1273 than the character just before index2 (a range starting at
1274 index2 will not be considered). If several matching ranges
1275 exist, the first one is chosen. The command's return value
1276 is a list containing two elements, which are the index of
1277 the first character of the range and the index of the char‐
1278 acter just after the last one in the range. If no matching
1279 range is found then the return value is an empty string.
1280 If index2 is not given then it defaults to the end of the
1281 text.
1282 $text->tagPrevrange(tagName, index1, ?index2?)
1284 This command searches the text for a range of characters
1285 tagged with tagName where the first character of the range
1286 is before the character at index1 and no earlier than the
1287 character at index2 (a range starting at index2 will be
1288 considered). If several matching ranges exist, the one
1289 closest to index1 is chosen. The command's return value is
1290 a list containing two elements, which are the index of the
1291 first character of the range and the index of the character
1292 just after the last one in the range. If no matching range
1293 is found then the return value is an empty string. If
1294 index2 is not given then it defaults to the beginning of
1295 the text.
1296 $text->tagRaise(tagName, ?aboveThis?)
1298 Changes the priority of tag tagName so that it is just
1299 higher in priority than the tag whose name is aboveThis.
1300 If aboveThis is omitted, then tagName's priority is changed
1301 to make it highest priority of all tags.
1302 $text->tagRanges(tagName)
1304 Returns a list describing all of the ranges of text that
1305 have been tagged with tagName. The first two elements of
1306 the list describe the first tagged range in the text, the
1307 next two elements describe the second range, and so on.
1308 The first element of each pair contains the index of the
1309 first character of the range, and the second element of the
1310 pair contains the index of the character just after the
1311 last one in the range. If there are no characters tagged
1312 with tag then an empty string is returned.
1313 $text->tagRemove(tagName, index1, ?index2, index1, index2, ...?)
1315 Remove the tag tagName from all of the characters starting
1316 at index1 and ending just before index2 (the character at
1317 index2 isn't affected). A single command may contain any
1318 number of index1-index2 pairs. If the last index2 is omit‐
1319 ted then the single character at index1 is tagged. If
1320 there are no characters in the specified range (e.g. index1
1321 is past the end of the file or index2 is less than or equal
1322 to index1) then the command has no effect. This command
1323 returns an empty string.
1324 $text->ToggleInsertMode
1326 Toggles the current overstrike mode.
1327 $text->unselectAll
1329 Unselects all the text in the widget.
1330 $text->WhatLineNumberPopup
1332 Creates a popup that displays the current line number of the insert
1333 mark.
1334 $text->widget(option?, arg, arg, ...?)
1336 $text->widgetOption(?arg, arg, ...?)
1337 This method is used to manipulate embedded windows. The behavior
1338 of the method depends on the option argument that follows the win‐
1339 dow argument. The following forms of the method are currently sup‐
1340 ported:
1341 $text->windowCget(index, option)
1343 Returns the value of a configuration option for an embedded
1344 window. Index identifies the embedded window, and option
1345 specifies a particular configuration option, which must be
1346 one of the ones listed in "EMBEDDED WINDOWS" above.
1347 $text->windowConfigure(index?, option, value, ...?)
1349 Query or modify the configuration options for an embedded
1350 window. If no option is specified, returns a list describ‐
1351 ing all of the available options for the embedded window at
1352 index (see Tk::options for information on the format of
1353 this list). If option is specified with no value, then the
1354 command returns a list describing the one named option
1355 (this list will be identical to the corresponding sublist
1356 of the value returned if no option is specified). If one
1357 or more option-value pairs are specified, then the command
1358 modifies the given option(s) to have the given value(s);
1359 in this case the command returns an empty string. See
1360 "EMBEDDED WINDOWS" above for information on the options
1361 that are supported.
1362 $text->windowCreate(index?, option, value, ...?)
1364 This command creates a new window annotation, which will
1365 appear in the text at the position given by index. Any
1366 number of option-value pairs may be specified to configure
1367 the annotation. See "EMBEDDED WINDOWS" above for informa‐
1368 tion on the options that are supported. Returns an empty
1369 string.
1370 $text->windowNames
1372 Returns a list whose elements are the names of all windows
1373 currently embedded in $text.
1374 $text->xview(option, args)
1376 This command is used to query and change the horizontal position of
1377 the text in the widget's window. It can take any of the following
1378 forms:
1379 $text->xview
1381 Returns a list containing two elements. Each element is a
1382 real fraction between 0 and 1; together they describe the
1383 portion of the document's horizontal span that is visible
1384 in the window. For example, if the first element is .2 and
1385 the second element is .6, 20% of the text is off-screen to
1386 the left, the middle 40% is visible in the window, and 40%
1387 of the text is off-screen to the right. The fractions
1388 refer only to the lines that are actually visible in the
1389 window: if the lines in the window are all very short, so
1390 that they are entirely visible, the returned fractions will
1391 be 0 and 1, even if there are other lines in the text that
1392 are much wider than the window. These are the same values
1393 passed to scrollbars via the -xscrollcommand option.
1394 $text->xviewMoveto(fraction)
1396 Adjusts the view in the window so that fraction of the hor‐
1397 izontal span of the text is off-screen to the left. Frac‐
1398 tion is a fraction between 0 and 1.
1399 $text->xviewScroll(number, what)
1401 This command shifts the view in the window left or right
1402 according to number and what. Number must be an integer.
1403 What must be either units or pages or an abbreviation of
1404 one of these. If what is units, the view adjusts left or
1405 right by number average-width characters on the display;
1406 if it is pages then the view adjusts by number screenfuls.
1407 If number is negative then characters farther to the left
1408 become visible; if it is positive then characters farther
1409 to the right become visible.
1410 $text->yview(?args?)
1412 This command is used to query and change the vertical position of
1413 the text in the widget's window. It can take any of the following
1414 forms:
1415 $text->yview
1417 Returns a list containing two elements, both of which are
1418 real fractions between 0 and 1. The first element gives
1419 the position of the first character in the top line in the
1420 window, relative to the text as a whole (0.5 means it is
1421 halfway through the text, for example). The second element
1422 gives the position of the character just after the last one
1423 in the bottom line of the window, relative to the text as a
1424 whole. These are the same values passed to scrollbars via
1425 the -yscrollcommand option.
1426 $text->yviewMoveto(fraction)
1428 Adjusts the view in the window so that the character given
1429 by fraction appears on the top line of the window. Frac‐
1430 tion is a fraction between 0 and 1; 0 indicates the first
1431 character in the text, 0.33 indicates the character one-
1432 third the way through the text, and so on.
1433 $text->yviewScroll(number, what)
1435 This command adjust the view in the window up or down
1436 according to number and what. Number must be an integer.
1437 What must be either units or pages. If what is units, the
1438 view adjusts up or down by number lines on the display; if
1439 it is pages then the view adjusts by number screenfuls. If
1440 number is negative then earlier positions in the text
1441 become visible; if it is positive then later positions in
1442 the text become visible.
1443 $text->yview(?-pickplace,? index)
1445 Changes the view in the $text's window to make index visi‐
1446 ble. If the -pickplace option isn't specified then index
1447 will appear at the top of the window. If -pickplace is
1448 specified then the widget chooses where index appears in
1449 the window:
1450 [1] If index is already visible somewhere in the
1452 window then the command does nothing.
1453 [2] If index is only a few lines off-screen above
1455 the window then it will be positioned at the
1456 top of the window.
1457 [3] If index is only a few lines off-screen below
1459 the window then it will be positioned at the
1460 bottom of the window.
1461 [4] Otherwise, index will be centered in the win‐
1463 dow.
1464 The -pickplace option has been obsoleted by the see widget command (see
1466 handles both x- and y-motion to make a location visible, whereas -pick‐
1467 place only handles motion in y).
1468 $text->yview(number)
1470 This command makes the first character on the line after the one
1471 given by number visible at the top of the window. Number must be
1472 an integer. This command used to be used for scrolling, but now it
1473 is obsolete.
1474
1476 Tk automatically creates class bindings for texts that give them the
1477 following default behavior. In the descriptions below, ``word'' refers
1478 to a contiguous group of letters, digits, or ``_'' characters, or any
1479 single character other than these.
1480 [1] Clicking mouse button 1 positions the insertion cursor just before
1482 the character underneath the mouse cursor, sets the input focus to
1483 this widget, and clears any selection in the widget. Dragging with
1484 mouse button 1 strokes out a selection between the insertion cursor
1485 and the character under the mouse.
1486 [2] Double-clicking with mouse button 1 selects the word under the
1488 mouse and positions the insertion cursor at the beginning of the
1489 word. Dragging after a double click will stroke out a selection
1490 consisting of whole words.
1491 [3] Triple-clicking with mouse button 1 selects the line under the
1493 mouse and positions the insertion cursor at the beginning of the
1494 line. Dragging after a triple click will stroke out a selection
1495 consisting of whole lines.
1496 [4] The ends of the selection can be adjusted by dragging with mouse
1498 button 1 while the Shift key is down; this will adjust the end of
1499 the selection that was nearest to the mouse cursor when button 1
1500 was pressed. If the button is double-clicked before dragging then
1501 the selection will be adjusted in units of whole words; if it is
1502 triple-clicked then the selection will be adjusted in units of
1503 whole lines.
1504 [5] Clicking mouse button 1 with the Control key down will reposition
1506 the insertion cursor without affecting the selection.
1507 [6] If any normal printing characters are typed, they are inserted at
1509 the point of the insertion cursor.
1510 [7] The view in the widget can be adjusted by dragging with mouse but‐
1512 ton 2. If mouse button 2 is clicked without moving the mouse, the
1513 selection is copied into the text at the position of the mouse cur‐
1514 sor. The Insert key also inserts the selection, but at the posi‐
1515 tion of the insertion cursor.
1516 [8] If the mouse is dragged out of the widget while button 1 is
1518 pressed, the entry will automatically scroll to make more text vis‐
1519 ible (if there is more text off-screen on the side where the mouse
1520 left the window).
1521 [9] The Left and Right keys move the insertion cursor one character to
1523 the left or right; they also clear any selection in the text. If
1524 Left or Right is typed with the Shift key down, then the insertion
1525 cursor moves and the selection is extended to include the new char‐
1526 acter. Control-Left and Control-Right move the insertion cursor by
1527 words, and Control-Shift-Left and Control-Shift-Right move the
1528 insertion cursor by words and also extend the selection. Control-b
1529 and Control-f behave the same as Left and Right, respectively.
1530 Meta-b and Meta-f behave the same as Control-Left and Con‐
1531 trol-Right, respectively.
1532 [10]
1534 The Up and Down keys move the insertion cursor one line up or down
1535 and clear any selection in the text. If Up or Right is typed with
1536 the Shift key down, then the insertion cursor moves and the selec‐
1537 tion is extended to include the new character. Control-Up and Con‐
1538 trol-Down move the insertion cursor by paragraphs (groups of lines
1539 separated by blank lines), and Control-Shift-Up and Control-Shift-
1540 Down move the insertion cursor by paragraphs and also extend the
1541 selection. Control-p and Control-n behave the same as Up and Down,
1542 respectively.
1543 [11]
1545 The Next and Prior keys move the insertion cursor forward or back‐
1546 wards by one screenful and clear any selection in the text. If the
1547 Shift key is held down while Next or Prior is typed, then the
1548 selection is extended to include the new character. Control-v
1549 moves the view down one screenful without moving the insertion cur‐
1550 sor or adjusting the selection.
1551 [12]
1553 Control-Next and Control-Prior scroll the view right or left by one
1554 page without moving the insertion cursor or affecting the selec‐
1555 tion.
1556 [13]
1558 Home and Control-a move the insertion cursor to the beginning of
1559 its line and clear any selection in the widget. Shift-Home moves
1560 the insertion cursor to the beginning of the line and also extends
1561 the selection to that point.
1562 [14]
1564 End and Control-e move the insertion cursor to the end of the line
1565 and clear any selection in the widget. Shift-End moves the cursor
1566 to the end of the line and extends the selection to that point.
1567 [15]
1569 Control-Home and Meta-< move the insertion cursor to the beginning
1570 of the text and clear any selection in the widget. Control-Shift-
1571 Home moves the insertion cursor to the beginning of the text and
1572 also extends the selection to that point.
1573 [16]
1575 Control-End and Meta-> move the insertion cursor to the end of the
1576 text and clear any selection in the widget. Control-Shift-End
1577 moves the cursor to the end of the text and extends the selection
1578 to that point.
1579 [17]
1581 The Select key and Control-Space set the selection anchor to the
1582 position of the insertion cursor. They don't affect the current
1583 selection. Shift-Select and Control-Shift-Space adjust the selec‐
1584 tion to the current position of the insertion cursor, selecting
1585 from the anchor to the insertion cursor if there was not any selec‐
1586 tion previously.
1587 [18]
1589 Control-/ selects the entire contents of the widget.
1590 [19]
1592 Control-\ clears any selection in the widget.
1593 [20]
1595 The F16 key (labelled Copy on many Sun workstations) or Meta-w
1596 copies the selection in the widget to the clipboard, if there is a
1597 selection.
1598 [21]
1600 The F20 key (labelled Cut on many Sun workstations) or Control-w
1601 copies the selection in the widget to the clipboard and deletes the
1602 selection. If there is no selection in the widget then these keys
1603 have no effect.
1604 [22]
1606 The F18 key (labelled Paste on many Sun workstations) or Control-y
1607 inserts the contents of the clipboard at the position of the inser‐
1608 tion cursor.
1609 [23]
1611 The Delete key deletes the selection, if there is one in the wid‐
1612 get. If there is no selection, it deletes the character to the
1613 right of the insertion cursor.
1614 [24]
1616 Backspace and Control-h delete the selection, if there is one in
1617 the widget. If there is no selection, they delete the character to
1618 the left of the insertion cursor.
1619 [25]
1621 Control-d deletes the character to the right of the insertion cur‐
1622 sor.
1623 [26]
1625 Meta-d deletes the word to the right of the insertion cursor.
1626 [27]
1628 Control-k deletes from the insertion cursor to the end of its line;
1629 if the insertion cursor is already at the end of a line, then Con‐
1630 trol-k deletes the newline character.
1631 [28]
1633 Control-o opens a new line by inserting a newline character in
1634 front of the insertion cursor without moving the insertion cursor.
1635 [29]
1637 Meta-backspace and Meta-Delete delete the word to the left of the
1638 insertion cursor.
1639 [30]
1641 Control-x deletes whatever is selected in the text widget.
1642 [31]
1644 Control-t reverses the order of the two characters to the right of
1645 the insertion cursor.
1646 [32]
1648 Control-z (and Control-underscore on UNIX when tk_strictMotif is
1649 true) undoes the last edit action if the -undo option is true.
1650 Does nothing otherwise.
1651 [33]
1653 Control-Z (or Control-y on Windows) reapplies the last undone edit
1654 action if the -undo option is true. Does nothing otherwise.
1655 If the widget is disabled using the -state option, then its view can
1657 still be adjusted and text can still be selected, but no insertion cur‐
1658 sor will be displayed and no text modifications will take place.
1659 The behavior of texts can be changed by defining new bindings for indi‐
1661 vidual widgets or by redefining the class bindings.
1662
1664 The Perl/Tk Text widget also has built-in TIEHANDLE methods for print
1665 and printf statements. This means you can print to file handles tied to
1666 a Text widget, and the tied methods automatically insert the print
1667 statement's arguments into the Text widget.
1668 For example:
1670 #!/usr/local/bin/perl -w
1672 use POSIX 'acos';
1673 use Tk;
1674 use strict;
1675 my $mw = MainWindow->new;
1677 my $text = $mw->Text(qw/-width 40 -height 10/)->pack;
1678 tie *STDOUT, ref $text, $text;
1680 print "Hello Text World!\n";
1682 printf "pi ~= %1.5f", acos(-1.0);
1683 MainLoop;
1685
1687 Text widgets should run efficiently under a variety of conditions. The
1688 text widget uses about 2-3 bytes of main memory for each byte of text,
1689 so texts containing a megabyte or more should be practical on most
1690 workstations. Text is represented internally with a modified B-tree
1691 structure that makes operations relatively efficient even with large
1692 texts. Tags are included in the B-tree structure in a way that allows
1693 tags to span large ranges or have many disjoint smaller ranges without
1694 loss of efficiency. Marks are also implemented in a way that allows
1695 large numbers of marks. In most cases it is fine to have large numbers
1696 of unique tags, or a tag that has many distinct ranges.
1697 One performance problem can arise if you have hundreds or thousands of
1699 different tags that all have the following characteristics: the first
1700 and last ranges of each tag are near the beginning and end of the text,
1701 respectively, or a single tag range covers most of the text widget.
1702 The cost of adding and deleting tags like this is proportional to the
1703 number of other tags with the same properties. In contrast, there is
1704 no problem with having thousands of distinct tags if their overall
1705 ranges are localized and spread uniformly throughout the text.
1706 Very long text lines can be expensive, especially if they have many
1708 marks and tags within them.
1709 The display line with the insert cursor is redrawn each time the cursor
1711 blinks, which causes a steady stream of graphics traffic. Set the
1712 -insertofftime option to 0 avoid this.
1713
1715 Tk::ROText Tk::TextUndo
1716
1718 text, widget
1719perl v5.8.8 2008-02-05 Text(3)