1Text(3) User Contributed Perl Documentation Text(3)
2
6 Tk::Text - Create and manipulate Text widgets
7
9 $text = $parent->Text(?options?);
10 -background -highlightbackground -insertontime -selectborderwidth
12 -borderwidth -highlightcolor -insertwidth -selectforeground
13 -cursor -highlightthickness -padx -setgrid
14 -exportselection -insertbackground -pady -takefocus
15 -font -insertborderwidth -relief -xscrollcommand
16 -foreground -insertofftime -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
69 character is positioned at the tab position, and center means that
70 the text is centered at the tab position. Numeric means that the
71 decimal point in the text is positioned at the tab position; if
72 there is no decimal point then the least significant digit of the
73 number is positioned just to the left of the tab position; if
74 there is no number in the text then the text is right-justified at
75 the tab position. For example, -tabs => [qw/2c left 4c 6c center/]
76 creates three tab stops at two-centimeter intervals; the first two
77 use left justification and the third uses center justification. If
78 the list of tab stops does not have enough elements to cover all of
79 the tabs in a text line, then Tk extrapolates new tab stops using
80 the 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
118 different fonts and colors. In addition, perl/Tk callbacks can be
119 associated with tags so that scripts are invoked when particular
120 actions such as keystrokes and mouse button presses occur in particular
121 ranges of the 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
125 interesting positions in the text as it is edited. See "MARKS" below
126 for more 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
159 coordinates 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
175 characters are currently tagged with tag.
176 $widget
178 Indicates the position of the embedded window referenced by
179 $widget. This form generates an error if $widget does not
180 reference to an embedded window.
181 imageName
183 Indicates the position of the embedded image whose name is
184 imageName. This form generates an error if there is no embedded
185 image 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 earlier in
189 the above list takes precedence. If modifiers follow the base index,
190 each one of them must have one of the forms listed below. Keywords
191 such as chars and wordend may be abbreviated as long as the
192 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
210 character position within the line. If there are fewer than count
211 lines after the line containing the current index, then set the
212 index to refer to the same character position on the last line of
213 the text. Then, if the line is not long enough to contain a
214 character at the indicated character position, adjust the character
215 position to refer to the last character of the line (the newline).
216 Spaces on either side of count are optional.
217 - count lines
219 Adjust the index backward by count lines, retaining the same
220 character 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
224 character 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
237 containing the current index. A word consists of any number of
238 adjacent characters that are letters, digits, or underscores, or a
239 single 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-to-
247 right order. For example, the index ``end - 1 chars'' refers to the
248 next-to-last character in the text and ``insert wordstart - 1 c''
249 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
254 textual string that is associated with some of the characters in a
255 text. Tags may contain arbitrary characters, but it is probably best
256 to avoid using the the characters `` '' (space), +, or -: these
257 characters have special meaning in indices, so tags containing them
258 can't be used as indices. There may be any number of tags associated
259 with characters in a text. Each tag may refer to a single character, a
260 range of characters, or several ranges of characters. An individual
261 character may 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
266 display options or binding callbacks to it), it is given a priority
267 higher than any existing tag. The priority order of tags may be
268 redefined using the ``$text->tagRaise'' and ``$text->tagLower''
269 methods.
270 Tags serve three purposes in text widgets. First, they control the way
272 information is displayed on the screen. By default, characters are
273 displayed as determined by the background, font, and foreground options
274 for the text widget. However, display options may be associated with
275 individual tags using the ``$text->tagConfigure'' method. If a
276 character has been tagged, then the display options associated with the
277 tag override the default display style. The following options are
278 currently supported for tags:
279 -background => color
281 Color specifies the background color to use for characters
282 associated with the tag. It may have any of the forms accepted by
283 Tk_GetColor.
284 -bgstipple => bitmap
286 Bitmap specifies a bitmap that is used as a stipple pattern for the
287 background. It may have any of the forms accepted by Tk_GetBitmap.
288 If bitmap hasn't been specified, or if it is specified as an empty
289 string, then a solid fill will be used for the background.
290 -borderwidth => pixels
292 Pixels specifies the width of a 3-D border to draw around the
293 background. It may have any of the forms accepted by Tk_GetPixels.
294 This option is used in conjunction with the -relief option to give
295 a 3-D appearance to the background for characters; it is ignored
296 unless the -background option has been set for the tag.
297 -elide => boolean
299 Elide specifies whether the data should be elided. Elided data is
300 not displayed and takes no space on screen, but further on
301 behaves just as normal data.
302 -data => value
304 Allows an arbitrary perl scalar value to be associated with the
305 tag.
306 -fgstipple => bitmap
308 Bitmap specifies a bitmap that is used as a stipple pattern when
309 drawing text and other foreground information such as underlines.
310 It may have any of the forms accepted by Tk_GetBitmap. If bitmap
311 hasn't been specified, or if it is specified as an empty string,
312 then a solid fill will be used.
313 -font => fontName
315 FontName is the name of a font to use for drawing characters. It
316 may have any of the forms accepted by Tk_GetFontStruct.
317 -foreground => color
319 Color specifies the color to use when drawing text and other
320 foreground information such as underlines. It may have any of the
321 forms accepted by Tk_GetColor.
322 -justify => justify
324 If the first character of a display line has a tag for which this
325 option has been specified, then justify determines how to justify
326 the line. It must be one of left, right, or center. If a line
327 wraps, then the justification for each line on the display is
328 determined by the first character of that display line.
329 -lmargin1 => pixels
331 If the first character of a text line has a tag for which this
332 option has been specified, then pixels specifies how much the line
333 should be indented from the left edge of the window. Pixels may
334 have any of the standard forms for screen distances. If a line of
335 text wraps, this option only applies to the first line on the
336 display; the -lmargin2 option controls the indentation for
337 subsequent lines.
338 -lmargin2 => pixels
340 If the first character of a display line has a tag for which this
341 option has been specified, and if the display line is not the first
342 for its text line (i.e., the text line has wrapped), then pixels
343 specifies how much the line should be indented from the left edge
344 of the window. Pixels may have any of the standard forms for
345 screen distances. This option is only used when wrapping is
346 enabled, and it only applies to the second and later display lines
347 for a text line.
348 -offset => pixels
350 Pixels specifies an amount by which the text's baseline should be
351 offset vertically from the baseline of the overall line, in pixels.
352 For example, a positive offset can be used for superscripts and a
353 negative offset can be used for subscripts. Pixels may have any of
354 the standard forms for screen distances.
355 -overstrike => boolean
357 Specifies whether or not to draw a horizontal rule through the
358 middle of characters. Boolean may have any of the forms accepted
359 by Tk_GetBoolean.
360 -relief => relief
362 Relief specifies the 3-D relief to use for drawing backgrounds, in
363 any of the forms accepted by Tk_GetRelief. This option is used in
364 conjunction with the -borderwidth option to give a 3-D appearance
365 to the background for characters; it is ignored unless the
366 -background option has been set for the tag.
367 -rmargin => pixels
369 If the first character of a display line has a tag for which this
370 option has been specified, then pixels specifies how wide a margin
371 to leave between the end of the line and the right edge of the
372 window. Pixels may have any of the standard forms for screen
373 distances. This option is only used when wrapping is enabled. If
374 a text line wraps, the right margin for each line on the display is
375 determined by the first character of that display line.
376 -spacing1 => pixels
378 Pixels specifies how much additional space should be left above
379 each text line, using any of the standard forms for screen
380 distances. If a line wraps, this option only applies to the first
381 line on the display.
382 -spacing2 => pixels
384 For lines that wrap, this option specifies how much additional
385 space to leave between the display lines for a single text line.
386 Pixels may have any of the standard forms for screen distances.
387 -spacing3 => pixels
389 Pixels specifies how much additional space should be left below
390 each text line, using any of the standard forms for screen
391 distances. If a line wraps, this option only applies to the last
392 line on the display.
393 -tabs => tabList
395 TabList specifies a set of tab stops in the same form as for the
396 -tabs option for the text widget. This option only applies to a
397 display line if it applies to the first character on that display
398 line. If this option is specified as an empty string, it cancels
399 the option, leaving it unspecified for the tag (the default). If
400 the option is specified as a non-empty string that is an empty
401 list, such as -tabs = " ">, then it requests default 8-character
402 tabs as described for the tabs widget option.
403 -underline => boolean
405 Boolean specifies whether or not to draw an underline underneath
406 characters. It may have any of the forms accepted by
407 Tk_GetBoolean.
408 -wrap => mode
410 Mode specifies how to handle lines that are wider than the text's
411 window. It has the same legal values as the -wrap option for the
412 text widget: none, char, or word. If this tag option is
413 specified, it overrides the -wrap option for the text widget.
414 If a character has several tags associated with it, and if their
416 display options conflict, then the options of the highest priority tag
417 are used. If a particular display option hasn't been specified for a
418 particular tag, or if it is specified as an empty string, then that
419 option will never be used; the next-highest-priority tag's option will
420 used instead. If no tag specifies a particular display option, then
421 the default style for the widget will be used.
422 The second purpose for tags is event bindings. You can associate
424 bindings with a tag in much the same way you can associate bindings
425 with a widget class: whenever particular X events occur on characters
426 with the given tag, a given <perl/Tk callback|Tk::callbacks> will be
427 executed. Tag bindings can be used to give behaviors to ranges of
428 characters; among other things, this allows hypertext-like features to
429 be implemented. For details, see the description of the tagBind widget
430 method below.
431 The third use for tags is in managing the selection. See "THE
433 SELECTION" below.
434
436 The second form of annotation in text widgets is a mark. Marks are
437 used for remembering particular places in a text. They are something
438 like tags, in that they have names and they refer to places in the
439 file, but a mark isn't associated with particular characters. Instead,
440 a mark is associated with the gap between two characters. Only a
441 single position may be associated with a mark at any given time. If
442 the characters around a mark are deleted the mark will still remain;
443 it will just have new neighbor characters. In contrast, if the
444 characters containing a tag are deleted then the tag will no longer
445 have an association with characters in the file. Marks may be
446 manipulated with the ``$text->mark'' text widget method, and their
447 current locations may be determined by using the mark name as an index
448 in methods.
449 Each mark also has a gravity, which is either left or right. The
451 gravity for a mark specifies what happens to the mark when text is
452 inserted at the point of the mark. If a mark has left gravity, then
453 the mark is treated as if it were attached to the character on its
454 left, so the mark will remain to the left of any text inserted at the
455 mark position. If the mark has right gravity, new text inserted at the
456 mark position will appear to the right of the mark. The gravity for a
457 mark defaults to right.
458 The name space for marks is different from that for tags: the same
460 name may be used for both a mark and a tag, but they will refer to
461 different things.
462 Two marks have special significance. First, the mark insert is
464 associated with the insertion cursor, as described under "THE INSERTION
465 CURSOR" below. Second, the mark current is associated with the
466 character closest to the mouse and is adjusted automatically to track
467 the mouse position and any changes to the text in the widget (one
468 exception: current is not updated in response to mouse motions if a
469 mouse button is down; the update will be deferred until all mouse
470 buttons have been released). Neither of these special marks may be
471 deleted.
472
474 The third form of annotation in text widgets is an embedded window.
475 Each embedded window annotation causes a window to be displayed at a
476 particular point in the text. There may be any number of embedded
477 windows in a text widget, and any widget may be used as an embedded
478 window (subject to the usual rules for geometry management, which
479 require the text window to be the parent of the embedded window or a
480 descendant of its parent). The embedded window's position on the
481 screen will be updated as the text is modified or scrolled, and it will
482 be mapped and unmapped as it moves into and out of the visible area of
483 the text widget. Each embedded window occupies one character's worth
484 of index space in the text widget, and it may be referred to either by
485 the name of its embedded window or by its position in the widget's
486 index space. If the range of text containing the embedded window is
487 deleted then the window is destroyed.
488 When an embedded window is added to a text widget with the widgetCreate
490 method, several configuration options may be associated with it. These
491 options may be modified later with the widgetConfigure method. The
492 following options are currently supported:
493 -align => where
495 If the window is not as tall as the line in which it is displayed,
496 this option determines where the window is displayed in the line.
497 Where must have one of the values top (align the top of the window
498 with the top of the line), center (center the window within the
499 range of the line), bottom (align the bottom of the window with the
500 bottom of the line's area), or baseline (align the bottom of the
501 window with the baseline of the line).
502 -create => callback
504 Specifies a callback that may be evaluated to create the window for
505 the annotation. If no -window option has been specified for the
506 annotation this callback will be evaluated when the annotation is
507 about to be displayed on the screen. Callback must create a window
508 for the annotation and return the name of that window as its
509 result. If the annotation's window should ever be deleted,
510 callback will be evaluated again the next time the annotation is
511 displayed.
512 -padx => pixels
514 Pixels specifies the amount of extra space to leave on each side of
515 the embedded window. It may have any of the usual forms defined
516 for a screen distance (see Tk_GetPixels).
517 -pady => pixels
519 Pixels specifies the amount of extra space to leave on the top and
520 on the bottom of the embedded window. It may have any of the usual
521 forms defined for a screen distance (see Tk_GetPixels).
522 -stretch => boolean
524 If the requested height of the embedded window is less than the
525 height of the line in which it is displayed, this option can be
526 used to specify whether the window should be stretched vertically
527 to fill its line. If the -pady option has been specified as well,
528 then the requested padding will be retained even if the window is
529 stretched.
530 -window => $widget
532 Specifies the name of a window to display in the annotation.
533
535 The final form of annotation in text widgets is an embedded image.
536 Each embedded image annotation causes an image to be displayed at a
537 particular point in the text. There may be any number of embedded
538 images in a text widget, and a particular image may be embedded in
539 multiple places in the same text widget. The embedded image's position
540 on the screen will be updated as the text is modified or scrolled.
541 Each embedded image occupies one character's worth of index space in
542 the text widget, and it may be referred to either by its position in
543 the widget's index space, or the name it is assigned when the image is
544 inserted into the text widget with imageCreate. If the range of text
545 containing the embedded image is deleted then that copy of the image is
546 removed from the screen.
547 When an embedded image is added to a text widget with the image create
549 method, a name unique to this instance of the image is returned. This
550 name may then be used to refer to this image instance. The name is
551 taken to be the value of the -name option (described below). If the
552 -name option is not provided, the -image name is used instead. If the
553 imageName is already in use in the text widget, then #nn is added to
554 the end of the imageName, where nn is an arbitrary integer. This
555 insures the imageName is unique. Once this name is assigned to this
556 instance of the image, it does not change, even though the -image or
557 -name values can be changed with image configure.
558 When an embedded image is added to a text widget with the imageCreate
560 method, several configuration options may be associated with it. These
561 options may be modified later with the image configure method. The
562 following options are currently supported:
563 -align => where
565 If the image is not as tall as the line in which it is displayed,
566 this option determines where the image is displayed in the line.
567 Where must have one of the values top (align the top of the image
568 with the top of the line), center (center the image within the
569 range of the line), bottom (align the bottom of the image with the
570 bottom of the line's area), or baseline (align the bottom of the
571 image with the baseline of the line).
572 -image => image
574 Specifies the name of the Tk image to display in the annotation.
575 If image is not a valid Tk image, then an error is returned.
576 -name => ImageName
578 Specifies the name by which this image instance may be referenced
579 in the text widget. If ImageName is not supplied, then the name of
580 the Tk image is used instead. If the imageName is already in use,
581 #nn is appended to the end of the name as described above.
582 -padx => pixels
584 Pixels specifies the amount of extra space to leave on each side of
585 the embedded image. It may have any of the usual forms defined for
586 a screen distance.
587 -pady => pixels
589 Pixels specifies the amount of extra space to leave on the top and
590 on the bottom of the embedded image. It may have any of the usual
591 forms defined for a screen distance.
592
594 Selection support is implemented via tags. If the exportSelection
595 option for the text widget is true then the sel tag will be associated
596 with the selection:
597 [1] Whenever characters are tagged with sel the text widget will claim
599 ownership of the selection.
600 [2] Attempts to retrieve the selection will be serviced by the text
602 widget, returning all the characters with the sel tag.
603 [3] If the selection is claimed away by another application or by
605 another window within this application, then the sel tag will be
606 removed from all characters in the text.
607 [4] Whenever the sel tag range changes a virtual event <<Selection>> is
609 generated.
610 The sel tag is automatically defined when a text widget is created,
612 and it may not be deleted with the ``$text->tagDelete'' method.
613 Furthermore, the selectBackground, selectBorderWidth, and
614 selectForeground options for the text widget are tied to the
615 -background, -borderwidth, and -foreground options for the sel tag:
616 changes in either will automatically be reflected in the other.
617
619 The mark named insert has special significance in text widgets. It is
620 defined automatically when a text widget is created and it may not be
621 unset with the ``$text->markUnset'' widget command. The insert mark
622 represents the position of the insertion cursor, and the insertion
623 cursor will automatically be drawn at this point whenever the text
624 widget has the input focus.
625
627 The text widget can keep track of changes to the content of the widget
628 by means of the modified flag. Inserting or deleting text will set this
629 flag. The flag can be queried, set and cleared programatically as well.
630 Whenever the flag changes state a <<Modified>> virtual event is gener-
631 ated. See the edit modified widget command for more details.
632
634 The Text method creates a widget object. This object supports the
635 configure and cget methods described in Tk::options which can be used
636 to enquire and modify the options described above. The widget also
637 inherits all the methods provided by the generic Tk::Widget class.
638 The following additional methods are available for text widgets. In
640 addition, the extended text widget methods as documented in "Mastering
641 Perl/Tk" are included in this pod (with permission from the publisher,
642 O'Reilly and Associates Inc.).
643 $text->adjustSelect
645 Moves the end point of the selection and anchor point to the mouse
646 pointer location.
647 $text->bbox(index)
649 Returns a list of four elements describing the screen area of the
650 character given by index. The first two elements of the list give
651 the x and y coordinates of the upper-left corner of the area
652 occupied by the character, and the last two elements give the width
653 and height of the area. If the character is only partially visible
654 on the screen, then the return value reflects just the visible
655 part. If the character is not visible on the screen then the
656 return value is an empty list.
657 $text->clipboardColumnCopy
659 Performs a rectangular copy of the currently selected text with
660 basic compensation for tab characters.
661 $text->clipboardColumnCut
663 Performs a rectangular cut of the currently selected text with
664 basic compensation for tab characters.
665 $text->clipboardColumnPaste
667 Performs a rectangular paste of the text in the clipboard. The
668 upper-left corner is specified by the current position of the
669 insert mark with basic compensation for tab characters.
670 $text->compare(index1, op, index2)
672 Compares the indices given by index1 and index2 according to the
673 relational operator given by op, and returns 1 if the relationship
674 is satisfied and 0 if it isn't. Op must be one of the operators <,
675 <=, ==, >=, >, or !=. If op is == then 1 is returned if the two
676 indices refer to the same character, if op is < then 1 is returned
677 if index1 refers to an earlier character in the text than index2,
678 and so on.
679 $text->Contents(?args?)
681 Query or change the entire contents of the text widget. If no
682 arguments are given, the entire contents of the text widget are
683 returned. If any arguments are given, the entire contents of the
684 text widget are deleted and replaced by the argument list.
685 $text->debug(?boolean?)
687 If boolean is specified, then it must have one of the true or false
688 values accepted by Tcl_GetBoolean. If the value is a true one then
689 internal consistency checks will be turned on in the B-tree code
690 associated with text widgets. If boolean has a false value then
691 the debugging checks will be turned off. In either case the
692 command returns an empty string. If boolean is not specified then
693 the command returns on or off to indicate whether or not debugging
694 is turned on. There is a single debugging switch shared by all
695 text widgets: turning debugging on or off in any widget turns it
696 on or off for all widgets. For widgets with large amounts of text,
697 the consistency checks may cause a noticeable slow-down.
698 $text->delete(index1, ?index2?)
700 Delete a range of characters from the text. If both index1 and
701 index2 are specified, then delete all the characters starting with
702 the one given by index1 and stopping just before index2 (i.e. the
703 character at index2 is not deleted). If index2 doesn't specify a
704 position later in the text than index1 then no characters are
705 deleted. If index2 isn't specified then the single character at
706 index1 is deleted. It is not allowable to delete characters in a
707 way that would leave the text without a newline as the last
708 character. The command returns an empty string. If more indices
709 are given, multiple ranges of text will be deleted. All indices
710 are first checked for validity before any deletions are made.
711 They are sorted and the text is removed from the last range to the
712 first range to deleted text does not cause a undesired index
713 shifting side-effects. If multiple ranges with the same start
714 index are given, then the longest range is used. If
715 overlapping ranges are given, then they will be merged into spans
716 that do not cause deletion of text outside the given ranges due to
717 text shifted during deletion.
718 $text->deleteSelected
720 Delete the currently selected text.
721 $text->deleteTextTaggedWith(tag)
723 Delete the text tagged with the tag parameter.
724 $text->deleteToEndofLine
726 Delete from the insert mark location to the end of line.
727 $text->dlineinfo(index)
729 Returns a list with five elements describing the area occupied by
730 the display line containing index. The first two elements of the
731 list give the x and y coordinates of the upper-left corner of the
732 area occupied by the line, the third and fourth elements give the
733 width and height of the area, and the fifth element gives the
734 position of the baseline for the line, measured down from the top
735 of the area. All of this information is measured in pixels. If
736 the current wrap mode is none and the line extends beyond the
737 boundaries of the window, the area returned reflects the entire
738 area of the line, including the portions that are out of the
739 window. If the line is shorter than the full width of the window
740 then the area returned reflects just the portion of the line that
741 is occupied by characters and embedded windows. If the display
742 line containing index is not visible on the screen then the return
743 value is an empty list.
744 $text->dump(?switches?, index1, ?index2?)
746 Return the contents of the text widget from index1 up to, but not
747 including index2, including the text and information about marks,
748 tags, and embedded windows. If index2 is not specified, then it
749 defaults to one character past index1. The information is returned
750 in the following format:
751 key1 value1 index1 key2 value2 index2 ...
753 The possible key values are text, mark, tagon, tagoff, and $text.
755 The corresponding value is the text, mark name, tag name, or window
756 name. The index information is the index of the start of the text,
757 the mark, the tag transition, or the window. One or more of the
758 following switches (or abbreviations thereof) may be specified to
759 control the dump:
760 -all
762 Return information about all elements: text, marks, tags, and
763 windows. This is the default.
764 -command => callback
766 Instead of returning the information as the result of the dump
767 operation, invoke the callback on each element of the text
768 widget within the range. The callback has three arguments
769 appended to it before it is evaluated: the key, value, and
770 index.
771 -mark
773 Include information about marks in the dump results.
774 -tag
776 Include information about tag transitions in the dump results.
777 Tag information is returned as tagon and tagoff elements that
778 indicate the begin and end of each range of each tag,
779 respectively.
780 -text
782 Include information about text in the dump results. The value
783 is the text up to the next element or the end of range
784 indicated by index2. A text element does not span newlines. A
785 multi-line block of text that contains no marks or tag
786 transitions will still be dumped as a set of text seqments that
787 each end with a newline. The newline is part of the value.
788 -window
790 Include information about embedded windows in the dump results.
792 The value of a window is its Tk pathname, unless the window has not
793 been created yet. (It must have a create script.) In this case an
794 empty string is returned, and you must query the window by its
795 index position to get more information.
796 $text->edit( option, ?arg, arg ...? );
798 This command controls the undo mechanism and the modified flag.
799 The exact behavior of the command depends on the option argument
800 that follows the edit argument. The following forms of the command
801 are currently supported:
802 $text->editModified( ?boolean? );
804 If boolean is not specified, returns the modified flag of the
805 widget. The insert, delete, edit undo and edit redo commands
806 or the user can set or clear the modified flag. If boolean is
807 specified, sets the modified flag of the widget to boolean.
808 $text->editRedo;
810 (Not implemented, use TextUndo.) When the -undo option is
811 true, reapplies the last undone edits provided no other edits
812 were done since then. Generates an error when the redo stack is
813 empty. Does nothing when the -undo option is false.
814 $text->editReset;
816 (Not implemented, use TextUndo.) Clears the undo and redo
817 stacks.
818 $text->editSeparator;
820 (Not implemented, use TextUndo.) Inserts a separator (boundary)
821 on the undo stack. Does nothing when the -undo option is false.
822 $text->editUndo;
824 (Not implemented, use TextUndo.) Undoes the last edit action
825 when the -undo option is true. An edit action is defined as
826 all the insert and delete commands that are recorded on the
827 undo stack in between two separators. Generates an error when
828 the undo stack is empty. Does nothing when the -undo option is
829 false.
830 $text->FindAll(mode, case, pattern)
832 Removes any current selections and then performs a global text
833 search. All matches are tagged with the sel tag.
834 mode can be be -exact or -regexp. See the search command for more
836 information
837 case can be -nocase or -case. See the search command for more
839 information
840 pattern is an exact string to match if mode is -exact or a regular
842 expression if the match mode is -regexp.
843 $text->FindAndReplaceAll(mode, case, find, replace)
845 Same as the FindAll method, however additionally substitutes the
846 matched text with the characters replace.
847 $text->FindAndReplacePopUp
849 Creates a find-and-replace popup window if one does not already
850 exist. If there is currently selected text, then the 'find' field
851 will be 'pre-filled' with the selection.
852 $text->FindNext(direction, mode, case, pattern)
854 Removes any current selections and then performs a forward or
855 reverse text search. All matches are tagged with the sel tag.
856 direction can be -forwards or -backwards. mode, case and pattern
857 are as for the FindAll method.
858 $text->FindPopUp
860 Creates a find popup, if one does not yet exist. If there is
861 currently selected text, then the 'find' field will be 'pre-filled'
862 with the selection.
863 $text->FindSelectionNext
865 Gets the currently selected text and removes all selections. It
866 then finds the next exact, case-sensitive string that matches in a
867 forward direction and selects the text and makes the new selection
868 visible.
869 $text->FindSelectionPrevious
871 Gets the currently selected text and removes all selections. It
872 then finds the next exact, case-sensitive string that matches in a
873 reverse direction and selects the text and makes the new selection
874 visible.
875 $text->get(index1, ?index2?)
877 Return a range of characters from the text. The return value will
878 be all the characters in the text starting with the one whose index
879 is index1 and ending just before the one whose index is index2 (the
880 character at index2 will not be returned). If index2 is omitted
881 then the single character at index1 is returned. If there are no
882 characters in the specified range (e.g. index1 is past the end of
883 the file or index2 is less than or equal to index1) then an empty
884 string is returned. If the specified range contains embedded
885 windows, no information about them is included in the returned
886 string. If multiple index pairs are given, multiple ranges of text
887 will be returned in a list. Invalid ranges will not be represented
888 with empty strings in the list. The ranges are returned in the
889 order passed to get.
890 $text->getSelected
892 Return the currently selected text.
893 $text->GetTextTaggedWith(tag)
895 Return the text tagged with the tag parameter.
896 $text->GotoLineNumber(line_number)
898 Set the insert mark to line_number and ensures the line is visible.
899 $text->GotoLineNumberPopUp(line_number)
901 Displays a popup, pre-filling it with selected numeric text (if
902 any), or the line number from GotoLineNumber (if any).
903 $text->image(option, ?arg, arg, ...?)
905 $text->imageOption(?arg, arg, ...?)
906 This method is used to manipulate embedded images. The behavior of
907 the method depends on the option argument that follows the image
908 prefix. The following forms of the methods are currently
909 supported:
910 $text->imageCget(index, option)
912 Returns the value of a configuration option for an embedded
913 image. Index identifies the embedded image, and option
914 specifies a particular configuration option, which must be
915 one of the ones listed in "EMBEDDED IMAGES".
916 $text->imageConfigure(index, ?option, value, ...?)
918 Query or modify the configuration options for an embedded
919 image. If no option is specified, returns a list
920 describing all of the available options for the embedded
921 image at index (see Tk::options for information on the
922 format of this list). If option is specified with no
923 value, then the command returns a list describing the one
924 named option (this list will be identical to the
925 corresponding sublist of the value returned if no option is
926 specified). If one or more option-value pairs are
927 specified, then the command modifies the given option(s) to
928 have the given value(s); in this case the command returns
929 an empty string. See "EMBEDDED IMAGES" for information on
930 the options that are supported.
931 $text->imageCreate(index, ?option, value, ...?)
933 This command creates a new image annotation, which will
934 appear in the text at the position given by index. Any
935 number of option-value pairs may be specified to configure
936 the annotation. Returns a unique identifier that may be
937 used as an index to refer to this image. See "EMBEDDED
938 IMAGES" for information on the options that are supported,
939 and a description of the identifier returned.
940 $text->imageNames
942 Returns a list whose elements are the names of all image
943 instances currently embedded in $text.
944 $text->index(index)
946 Returns the position corresponding to index in the form line.char
947 where line is the line number and char is the character number.
948 Index may have any of the forms described under "INDICES" above.
949 $text->insert(index, chars, ?tagList, chars, tagList, ...?)
951 Inserts all of the chars arguments just before the character at
952 index. If index refers to the end of the text (the character after
953 the last newline) then the new text is inserted just before the
954 last newline instead. If there is a single chars argument and no
955 tagList, then the new text will receive any tags that are present
956 on both the character before and the character after the insertion
957 point; if a tag is present on only one of these characters then it
958 will not be applied to the new text. If tagList is specified then
959 it consists of a list of tag names; the new characters will
960 receive all of the tags in this list and no others, regardless of
961 the tags present around the insertion point. If multiple
962 chars-tagList argument pairs are present, they produce the same
963 effect as if a separate insert widget command had been issued for
964 each pair, in order. The last tagList argument may be omitted.
965 $text->Insert(string)
967 Do NOT confuse this with the lower-case insert method. Insert
968 string at the point of the insertion cursor. If there is a
969 selection in the text, and it covers the point of the insertion
970 cursor, then it deletes the selection before inserting.
971 $text->InsertKeypress(character)
973 Inserts character at the insert mark. If in overstrike mode, it
974 firsts deletes the character at the insert mark.
975 $text->InsertSelection
977 Inserts the current selection at the insert mark.
978 $text->insertTab
980 Inserts a tab (\t) character at the insert mark.
981 $text->mark(option, ?arg, arg, ...?)
983 This command is used to manipulate marks. The exact behavior of
984 the command depends on the option argument that follows the mark
985 argument. The following forms of the command are currently
986 supported:
987 $text->markGravity(markName, ?direction?)
989 If direction is not specified, returns left or right to
990 indicate which of its adjacent characters markName is
991 attached to. If direction is specified, it must be left or
992 right; the gravity of markName is set to the given value.
993 $text->markNames
995 Returns a list whose elements are the names of all the
996 marks that are currently set.
997 $text->markNext(index)
999 Returns the name of the next mark at or after index. If
1000 index is specified in numerical form, then the search for
1001 the next mark begins at that index. If index is the name
1002 of a mark, then the search for the next mark begins
1003 immediately after that mark. This can still return a mark
1004 at the same position if there are multiple marks at the
1005 same index. These semantics mean that the mark next
1006 operation can be used to step through all the marks in a
1007 text widget in the same order as the mark information
1008 returned by the dump operation. If a mark has been set to
1009 the special end index, then it appears to be after end with
1010 respect to the mark next operation. An empty string is
1011 returned if there are no marks after index.
1012 $text->markPrevious(index)
1014 Returns the name of the mark at or before index. If index
1015 is specified in numerical form, then the search for the
1016 previous mark begins with the character just before that
1017 index. If index is the name of a mark, then the search for
1018 the next mark begins immediately before that mark. This
1019 can still return a mark at the same position if there are
1020 multiple marks at the same index. These semantics mean
1021 that the mark previous operation can be used to step
1022 through all the marks in a text widget in the reverse order
1023 as the mark information returned by the dump operation. An
1024 empty string is returned if there are no marks before
1025 index.
1026 $text->markSet(markName, index)
1028 Sets the mark named markName to a position just before the
1029 character at index. If markName already exists, it is
1030 moved from its old position; if it doesn't exist, a new
1031 mark is created. This command returns an empty string.
1032 $text->markUnset(markName?, markName, markName, ...?)
1034 Remove the mark corresponding to each of the markName
1035 arguments. The removed marks will not be usable in indices
1036 and will not be returned by future calls to
1037 ``$text->markNames''. This command returns an empty
1038 string.
1039 $text->markExists(markname)
1041 Returns true if markname exists - false otherwise.
1042 $text->menu(?menu?)
1044 If menu reference is given as an argument, then the text widget
1045 menu is adjusted to use this new menu. If the menu argument is
1046 undef, then this command disables the current text widget menu. If
1047 the menu argument is omitted altogether, then the current text
1048 widget menu reference is returned.
1049 $text->openLine
1051 Inserts a newline (\n) at the insert mark.
1052 $text->OverstrikeMode(?boolean?)
1054 Returns the overstrike mode if boolean is omitted or sets the
1055 overstrike mode to boolean. True means overstrike mode is enabled.
1056 $text->PostPopupMenu(x,y)
1058 Creates a popup menu at the specified (x,y) pixel coordinates. The
1059 default menu has File, Edit, Search and View menu items which
1060 cascade to sub-menus for further commands. There is an implicit
1061 <Button-3> binding to this method that posts the menu over the
1062 cursor.
1063 $text->ResetAnchor
1065 Sets the selection anchor to whichever end is farthest from the
1066 index argument.
1067 $text->scan(option, args) or
1069 $text->scanoption(args)
1070 This method is used to implement scanning on texts. It has two
1071 forms, depending on option:
1072 $text->scanMark(x, y)
1074 Records x and y and the current view in the text window,
1075 for use in conjunction with later scanDragto method.
1076 Typically this method is associated with a mouse button
1077 press in the widget. It returns an empty string.
1078 $text->scanDragto(x, y)
1080 This command computes the difference between its x and y
1081 arguments and the x and y arguments to the last scanMark
1082 method for the widget. It then adjusts the view by 10
1083 times the difference in coordinates. This command is
1084 typically associated with mouse motion events in the
1085 widget, to produce the effect of dragging the text at high
1086 speed through the window. The return value is an empty
1087 string.
1088 $text->search(?switches,? pattern, index, ?stopIndex?)
1090 Searches the text in $text starting at index for a range of
1091 characters that matches pattern. If a match is found, the index of
1092 the first character in the match is returned as result; otherwise
1093 an empty string is returned. One or more of the following switches
1094 (or abbreviations thereof) may be specified to control the search:
1095 -forwards
1097 The search will proceed forward through the text, finding
1098 the first matching range starting at or after the position
1099 given by index. This is the default.
1100 -backwards
1102 The search will proceed backward through the text, finding
1103 the matching range closest to index whose first character
1104 is before index.
1105 -exact Use exact matching: the characters in the matching range
1107 must be identical to those in pattern. This is the
1108 default.
1109 -regexp Treat pattern as a regular expression and match it against
1111 the text using the rules for regular expressions (see the
1112 regexp command for details).
1113 -nocase Ignore case differences between the pattern and the text.
1115 -count varName
1117 The argument following -count gives the name of a variable;
1118 if a match is found, the number of characters in the
1119 matching range will be stored in the variable.
1120 -hidden Find hidden text as well. By default only displayed text is
1122 found.
1123 -- This switch has no effect except to terminate the list of
1125 switches: the next argument will be treated as pattern even
1126 if it starts with -.
1127 The matching range must be entirely within a single line of text. For
1129 regular expression matching the newlines are removed from the ends of
1130 the lines before matching: use the $ feature in regular expressions to
1131 match the end of a line. For exact matching the newlines are retained.
1132 If stopIndex is specified, the search stops at that index: for forward
1133 searches, no match at or after stopIndex will be considered; for
1134 backward searches, no match earlier in the text than stopIndex will be
1135 considered. If stopIndex is omitted, the entire text will be searched:
1136 when the beginning or end of the text is reached, the search continues
1137 at the other end until the starting location is reached again; if
1138 stopIndex is specified, no wrap-around will occur.
1139 $text->see(index)
1141 Adjusts the view in the window so that the character given by index
1142 is completely visible. If index is already visible then the
1143 command does nothing. If index is a short distance out of view,
1144 the command adjusts the view just enough to make index visible at
1145 the edge of the window. If index is far out of view, then the
1146 command centers index in the window.
1147 $text->selectAll
1149 Selects all the text in the widget.
1150 $text->selectLine
1152 Selects the line with the insert mark.
1153 $text->selectWord
1155 Selects the word with the insert mark.
1156 $text->SetCursor(position)
1158 Moves the insert mark to position.
1159 $text->tag(option, ?arg, arg, ...?)
1161 This command is used to manipulate tags. The exact behavior of the
1162 command depends on the option argument that follows the tag
1163 argument. The following forms of the command are currently
1164 supported:
1165 $text->tagAdd(tagName, index1, ?index2, index1, index2, ...?)
1167 Associate the tag tagName with all of the characters
1168 starting with index1 and ending just before index2 (the
1169 character at index2 isn't tagged). A single command may
1170 contain any number of index1-index2 pairs. If the last
1171 index2 is omitted then the single character at index1 is
1172 tagged. If there are no characters in the specified range
1173 (e.g. index1 is past the end of the file or index2 is less
1174 than or equal to index1) then the command has no effect.
1175 $text->tagBind(tagName, ?sequence?, ?script?)
1177 This command associates script with the tag given by
1178 tagName. Whenever the event sequence given by sequence
1179 occurs for a character that has been tagged with tagName,
1180 the script will be invoked. This method is similar to the
1181 bind command except that it operates on characters in a
1182 text rather than entire widgets. See the Tk::bind
1183 documentation for complete details on the syntax of
1184 sequence and the substitutions performed on script before
1185 invoking it. If all arguments are specified then a new
1186 binding is created, replacing any existing binding for the
1187 same sequence and tagName (if the first character of script
1188 is ``+'' then script augments an existing binding rather
1189 than replacing it). In this case the return value is an
1190 empty string. If script is omitted then the command
1191 returns the script associated with tagName and sequence (an
1192 error occurs if there is no such binding). If both script
1193 and sequence are omitted then the command returns a list of
1194 all the sequences for which bindings have been defined for
1195 tagName.
1196 The only events for which bindings may be specified are
1198 those related to the mouse and keyboard (such as Enter,
1199 Leave, ButtonPress, Motion, and KeyPress) or virtual
1200 events. Event bindings for a text widget use the current
1201 mark described under "MARKS" above. An Enter event
1202 triggers for a tag when the tag first becomes present on
1203 the current character, and a Leave event triggers for a tag
1204 when it ceases to be present on the current character.
1205 Enter and Leave events can happen either because the
1206 current mark moved or because the character at that
1207 position changed. Note that these events are different
1208 than Enter and Leave events for windows. Mouse and
1209 keyboard events are directed to the current character. If
1210 a virtual event is used in a binding, that binding can
1211 trigger only if the virtual event is defined by an
1212 underlying mouse-related or keyboard-related event.
1213 It is possible for the current character to have multiple
1215 tags, and for each of them to have a binding for a
1216 particular event sequence. When this occurs, one binding
1217 is invoked for each tag, in order from lowest-priority to
1218 highest priority. If there are multiple matching bindings
1219 for a single tag, then the most specific binding is chosen
1220 (see the the documentation for the bind command for
1221 details). continue and break commands within binding
1222 scripts are processed in the same way as for bindings
1223 created with the bind command.
1224 If bindings are created for the widget as a whole using the
1226 bind command, then those bindings will supplement the tag
1227 bindings. The tag bindings will be invoked first, followed
1228 by bindings for the window as a whole.
1229 $text->tagCget(tagName, option)
1231 This command returns the current value of the option named
1232 option associated with the tag given by tagName. Option
1233 may have any of the values accepted by the tag configure
1234 method.
1235 $text->tagConfigure(tagName, ?option?, ?value?, ?option, value,
1237 ...?)
1238 This command is similar to the configure method except that
1239 it modifies options associated with the tag given by
1240 tagName instead of modifying options for the overall text
1241 widget. If no option is specified, the command returns a
1242 list describing all of the available options for tagName
1243 (see Tk::options for information on the format of this
1244 list). If option is specified with no value, then the
1245 command returns a list describing the one named option
1246 (this list will be identical to the corresponding sublist
1247 of the value returned if no option is specified). If one
1248 or more option-value pairs are specified, then the command
1249 modifies the given option(s) to have the given value(s) in
1250 tagName; in this case the command returns an empty string.
1251 See "TAGS" above for details on the options available for
1252 tags.
1253 $text->tagDelete(tagName, ?tagName, ...?)
1255 Deletes all tag information for each of the tagName
1256 arguments. The command removes the tags from all
1257 characters in the file and also deletes any other
1258 information associated with the tags, such as bindings and
1259 display information. The command returns an empty string.
1260 $text->tagLower(tagName?, belowThis?)
1262 Changes the priority of tag tagName so that it is just
1263 lower in priority than the tag whose name is belowThis. If
1264 belowThis is omitted, then tagName's priority is changed to
1265 make it lowest priority of all tags.
1266 $text->tagNames(?index?)
1268 Returns a list whose elements are the names of all the tags
1269 that are active at the character position given by index.
1270 If index is omitted, then the return value will describe
1271 all of the tags that exist for the text (this includes all
1272 tags that have been named in a ``$text->tag'' widget
1273 command but haven't been deleted by a ``$text->tagDelete''
1274 method, even if no characters are currently marked with the
1275 tag). The list will be sorted in order from lowest
1276 priority to highest priority.
1277 $text->tagNextrange(tagName, index1, ?index2?)
1279 This command searches the text for a range of characters
1280 tagged with tagName where the first character of the range
1281 is no earlier than the character at index1 and no later
1282 than the character just before index2 (a range starting at
1283 index2 will not be considered). If several matching ranges
1284 exist, the first one is chosen. The command's return value
1285 is a list containing two elements, which are the index of
1286 the first character of the range and the index of the
1287 character just after the last one in the range. If no
1288 matching range is found then the return value is an empty
1289 string. If index2 is not given then it defaults to the end
1290 of the text.
1291 $text->tagPrevrange(tagName, index1, ?index2?)
1293 This command searches the text for a range of characters
1294 tagged with tagName where the first character of the range
1295 is before the character at index1 and no earlier than the
1296 character at index2 (a range starting at index2 will be
1297 considered). If several matching ranges exist, the one
1298 closest to index1 is chosen. The command's return value is
1299 a list containing two elements, which are the index of the
1300 first character of the range and the index of the character
1301 just after the last one in the range. If no matching range
1302 is found then the return value is an empty string. If
1303 index2 is not given then it defaults to the beginning of
1304 the text.
1305 $text->tagRaise(tagName, ?aboveThis?)
1307 Changes the priority of tag tagName so that it is just
1308 higher in priority than the tag whose name is aboveThis.
1309 If aboveThis is omitted, then tagName's priority is changed
1310 to make it highest priority of all tags.
1311 $text->tagRanges(tagName)
1313 Returns a list describing all of the ranges of text that
1314 have been tagged with tagName. The first two elements of
1315 the list describe the first tagged range in the text, the
1316 next two elements describe the second range, and so on.
1317 The first element of each pair contains the index of the
1318 first character of the range, and the second element of the
1319 pair contains the index of the character just after the
1320 last one in the range. If there are no characters tagged
1321 with tag then an empty string is returned.
1322 $text->tagRemove(tagName, index1, ?index2, index1, index2, ...?)
1324 Remove the tag tagName from all of the characters starting
1325 at index1 and ending just before index2 (the character at
1326 index2 isn't affected). A single command may contain any
1327 number of index1-index2 pairs. If the last index2 is
1328 omitted then the single character at index1 is tagged. If
1329 there are no characters in the specified range (e.g. index1
1330 is past the end of the file or index2 is less than or equal
1331 to index1) then the command has no effect. This command
1332 returns an empty string.
1333 $text->ToggleInsertMode
1335 Toggles the current overstrike mode.
1336 $text->unselectAll
1338 Unselects all the text in the widget.
1339 $text->WhatLineNumberPopup
1341 Creates a popup that displays the current line number of the insert
1342 mark.
1343 $text->widget(option?, arg, arg, ...?)
1345 $text->widgetOption(?arg, arg, ...?)
1346 This method is used to manipulate embedded windows. The behavior
1347 of the method depends on the option argument that follows the
1348 window argument. The following forms of the method are currently
1349 supported:
1350 $text->windowCget(index, option)
1352 Returns the value of a configuration option for an embedded
1353 window. Index identifies the embedded window, and option
1354 specifies a particular configuration option, which must be
1355 one of the ones listed in "EMBEDDED WINDOWS" above.
1356 $text->windowConfigure(index?, option, value, ...?)
1358 Query or modify the configuration options for an embedded
1359 window. If no option is specified, returns a list
1360 describing all of the available options for the embedded
1361 window at index (see Tk::options for information on the
1362 format of this list). If option is specified with no
1363 value, then the command returns a list describing the one
1364 named option (this list will be identical to the
1365 corresponding sublist of the value returned if no option is
1366 specified). If one or more option-value pairs are
1367 specified, then the command modifies the given option(s) to
1368 have the given value(s); in this case the command returns
1369 an empty string. See "EMBEDDED WINDOWS" above for
1370 information on the options that are supported.
1371 $text->windowCreate(index?, option, value, ...?)
1373 This command creates a new window annotation, which will
1374 appear in the text at the position given by index. Any
1375 number of option-value pairs may be specified to configure
1376 the annotation. See "EMBEDDED WINDOWS" above for
1377 information on the options that are supported. Returns an
1378 empty string.
1379 $text->windowNames
1381 Returns a list whose elements are the names of all windows
1382 currently embedded in $text.
1383 $text->xview(option, args)
1385 This command is used to query and change the horizontal position of
1386 the text in the widget's window. It can take any of the following
1387 forms:
1388 $text->xview
1390 Returns a list containing two elements. Each element is a
1391 real fraction between 0 and 1; together they describe the
1392 portion of the document's horizontal span that is visible
1393 in the window. For example, if the first element is .2 and
1394 the second element is .6, 20% of the text is off-screen to
1395 the left, the middle 40% is visible in the window, and 40%
1396 of the text is off-screen to the right. The fractions
1397 refer only to the lines that are actually visible in the
1398 window: if the lines in the window are all very short, so
1399 that they are entirely visible, the returned fractions will
1400 be 0 and 1, even if there are other lines in the text that
1401 are much wider than the window. These are the same values
1402 passed to scrollbars via the -xscrollcommand option.
1403 $text->xviewMoveto(fraction)
1405 Adjusts the view in the window so that fraction of the
1406 horizontal span of the text is off-screen to the left.
1407 Fraction is a fraction between 0 and 1.
1408 $text->xviewScroll(number, what)
1410 This command shifts the view in the window left or right
1411 according to number and what. Number must be an integer.
1412 What must be either units or pages or an abbreviation of
1413 one of these. If what is units, the view adjusts left or
1414 right by number average-width characters on the display;
1415 if it is pages then the view adjusts by number screenfuls.
1416 If number is negative then characters farther to the left
1417 become visible; if it is positive then characters farther
1418 to the right become visible.
1419 $text->yview(?args?)
1421 This command is used to query and change the vertical position of
1422 the text in the widget's window. It can take any of the following
1423 forms:
1424 $text->yview
1426 Returns a list containing two elements, both of which are
1427 real fractions between 0 and 1. The first element gives
1428 the position of the first character in the top line in the
1429 window, relative to the text as a whole (0.5 means it is
1430 halfway through the text, for example). The second element
1431 gives the position of the character just after the last one
1432 in the bottom line of the window, relative to the text as a
1433 whole. These are the same values passed to scrollbars via
1434 the -yscrollcommand option.
1435 $text->yviewMoveto(fraction)
1437 Adjusts the view in the window so that the character given
1438 by fraction appears on the top line of the window.
1439 Fraction is a fraction between 0 and 1; 0 indicates the
1440 first character in the text, 0.33 indicates the character
1441 one-third the way through the text, and so on.
1442 $text->yviewScroll(number, what)
1444 This command adjust the view in the window up or down
1445 according to number and what. Number must be an integer.
1446 What must be either units or pages. If what is units, the
1447 view adjusts up or down by number lines on the display; if
1448 it is pages then the view adjusts by number screenfuls. If
1449 number is negative then earlier positions in the text
1450 become visible; if it is positive then later positions in
1451 the text become visible.
1452 $text->yview(?-pickplace,? index)
1454 Changes the view in the $text's window to make index
1455 visible. If the -pickplace option isn't specified then
1456 index will appear at the top of the window. If -pickplace
1457 is specified then the widget chooses where index appears in
1458 the window:
1459 [1] If index is already visible somewhere in the
1461 window then the command does nothing.
1462 [2] If index is only a few lines off-screen above
1464 the window then it will be positioned at the
1465 top of the window.
1466 [3] If index is only a few lines off-screen below
1468 the window then it will be positioned at the
1469 bottom of the window.
1470 [4] Otherwise, index will be centered in the
1472 window.
1473 The -pickplace option has been obsoleted by the see widget command (see
1475 handles both x- and y-motion to make a location visible, whereas
1476 -pickplace only handles motion in y).
1477 $text->yview(number)
1479 This command makes the first character on the line after the one
1480 given by number visible at the top of the window. Number must be
1481 an integer. This command used to be used for scrolling, but now it
1482 is obsolete.
1483
1485 Tk automatically creates class bindings for texts that give them the
1486 following default behavior. In the descriptions below, ``word'' refers
1487 to a contiguous group of letters, digits, or ``_'' characters, or any
1488 single character other than these.
1489 [1] Clicking mouse button 1 positions the insertion cursor just before
1491 the character underneath the mouse cursor, sets the input focus to
1492 this widget, and clears any selection in the widget. Dragging with
1493 mouse button 1 strokes out a selection between the insertion cursor
1494 and the character under the mouse.
1495 [2] Double-clicking with mouse button 1 selects the word under the
1497 mouse and positions the insertion cursor at the beginning of the
1498 word. Dragging after a double click will stroke out a selection
1499 consisting of whole words.
1500 [3] Triple-clicking with mouse button 1 selects the line under the
1502 mouse and positions the insertion cursor at the beginning of the
1503 line. Dragging after a triple click will stroke out a selection
1504 consisting of whole lines.
1505 [4] The ends of the selection can be adjusted by dragging with mouse
1507 button 1 while the Shift key is down; this will adjust the end of
1508 the selection that was nearest to the mouse cursor when button 1
1509 was pressed. If the button is double-clicked before dragging then
1510 the selection will be adjusted in units of whole words; if it is
1511 triple-clicked then the selection will be adjusted in units of
1512 whole lines.
1513 [5] Clicking mouse button 1 with the Control key down will reposition
1515 the insertion cursor without affecting the selection.
1516 [6] If any normal printing characters are typed, they are inserted at
1518 the point of the insertion cursor.
1519 [7] The view in the widget can be adjusted by dragging with mouse
1521 button 2. If mouse button 2 is clicked without moving the mouse,
1522 the selection is copied into the text at the position of the mouse
1523 cursor. The Insert key also inserts the selection, but at the
1524 position of the insertion cursor.
1525 [8] If the mouse is dragged out of the widget while button 1 is
1527 pressed, the entry will automatically scroll to make more text
1528 visible (if there is more text off-screen on the side where the
1529 mouse left the window).
1530 [9] The Left and Right keys move the insertion cursor one character to
1532 the left or right; they also clear any selection in the text. If
1533 Left or Right is typed with the Shift key down, then the insertion
1534 cursor moves and the selection is extended to include the new
1535 character. Control-Left and Control-Right move the insertion
1536 cursor by words, and Control-Shift-Left and Control-Shift-Right
1537 move the insertion cursor by words and also extend the selection.
1538 Control-b and Control-f behave the same as Left and Right,
1539 respectively. Meta-b and Meta-f behave the same as Control-Left
1540 and Control-Right, respectively.
1541 [10]
1543 The Up and Down keys move the insertion cursor one line up or down
1544 and clear any selection in the text. If Up or Right is typed with
1545 the Shift key down, then the insertion cursor moves and the
1546 selection is extended to include the new character. Control-Up and
1547 Control-Down move the insertion cursor by paragraphs (groups of
1548 lines separated by blank lines), and Control-Shift-Up and Control-
1549 Shift-Down move the insertion cursor by paragraphs and also extend
1550 the selection. Control-p and Control-n behave the same as Up and
1551 Down, respectively.
1552 [11]
1554 The Next and Prior keys move the insertion cursor forward or
1555 backwards by one screenful and clear any selection in the text. If
1556 the Shift key is held down while Next or Prior is typed, then the
1557 selection is extended to include the new character. Control-v
1558 moves the view down one screenful without moving the insertion
1559 cursor or adjusting the selection.
1560 [12]
1562 Control-Next and Control-Prior scroll the view right or left by one
1563 page without moving the insertion cursor or affecting the
1564 selection.
1565 [13]
1567 Home and Control-a move the insertion cursor to the beginning of
1568 its line and clear any selection in the widget. Shift-Home moves
1569 the insertion cursor to the beginning of the line and also extends
1570 the selection to that point.
1571 [14]
1573 End and Control-e move the insertion cursor to the end of the line
1574 and clear any selection in the widget. Shift-End moves the cursor
1575 to the end of the line and extends the selection to that point.
1576 [15]
1578 Control-Home and Meta-< move the insertion cursor to the beginning
1579 of the text and clear any selection in the widget. Control-Shift-
1580 Home moves the insertion cursor to the beginning of the text and
1581 also extends the selection to that point.
1582 [16]
1584 Control-End and Meta-> move the insertion cursor to the end of the
1585 text and clear any selection in the widget. Control-Shift-End
1586 moves the cursor to the end of the text and extends the selection
1587 to that point.
1588 [17]
1590 The Select key and Control-Space set the selection anchor to the
1591 position of the insertion cursor. They don't affect the current
1592 selection. Shift-Select and Control-Shift-Space adjust the
1593 selection to the current position of the insertion cursor,
1594 selecting from the anchor to the insertion cursor if there was not
1595 any selection previously.
1596 [18]
1598 Control-/ selects the entire contents of the widget.
1599 [19]
1601 Control-\ clears any selection in the widget.
1602 [20]
1604 The F16 key (labelled Copy on many Sun workstations) or Meta-w
1605 copies the selection in the widget to the clipboard, if there is a
1606 selection.
1607 [21]
1609 The F20 key (labelled Cut on many Sun workstations) or Control-w
1610 copies the selection in the widget to the clipboard and deletes the
1611 selection. If there is no selection in the widget then these keys
1612 have no effect.
1613 [22]
1615 The F18 key (labelled Paste on many Sun workstations) or Control-y
1616 inserts the contents of the clipboard at the position of the
1617 insertion cursor.
1618 [23]
1620 The Delete key deletes the selection, if there is one in the
1621 widget. If there is no selection, it deletes the character to the
1622 right of the insertion cursor.
1623 [24]
1625 Backspace and Control-h delete the selection, if there is one in
1626 the widget. If there is no selection, they delete the character to
1627 the left of the insertion cursor.
1628 [25]
1630 Control-d deletes the character to the right of the insertion
1631 cursor.
1632 [26]
1634 Meta-d deletes the word to the right of the insertion cursor.
1635 [27]
1637 Control-k deletes from the insertion cursor to the end of its line;
1638 if the insertion cursor is already at the end of a line, then
1639 Control-k deletes the newline character.
1640 [28]
1642 Control-o opens a new line by inserting a newline character in
1643 front of the insertion cursor without moving the insertion cursor.
1644 [29]
1646 Meta-backspace and Meta-Delete delete the word to the left of the
1647 insertion cursor.
1648 [30]
1650 Control-x deletes whatever is selected in the text widget.
1651 [31]
1653 Control-t reverses the order of the two characters to the right of
1654 the insertion cursor.
1655 [32]
1657 Control-z (and Control-underscore on UNIX when tk_strictMotif is
1658 true) undoes the last edit action if the -undo option is true.
1659 Does nothing otherwise.
1660 [33]
1662 Control-Z (or Control-y on Windows) reapplies the last undone edit
1663 action if the -undo option is true. Does nothing otherwise.
1664 If the widget is disabled using the -state option, then its view can
1666 still be adjusted and text can still be selected, but no insertion
1667 cursor will be displayed and no text modifications will take place.
1668 The behavior of texts can be changed by defining new bindings for
1670 individual widgets or by redefining the class bindings.
1671
1673 The Perl/Tk Text widget also has built-in TIEHANDLE methods for print
1674 and printf statements. This means you can print to file handles tied to
1675 a Text widget, and the tied methods automatically insert the print
1676 statement's arguments into the Text widget.
1677 For example:
1679 #!/usr/local/bin/perl -w
1681 use POSIX 'acos';
1682 use Tk;
1683 use strict;
1684 my $mw = MainWindow->new;
1686 my $text = $mw->Text(qw/-width 40 -height 10/)->pack;
1687 tie *STDOUT, ref $text, $text;
1689 print "Hello Text World!\n";
1691 printf "pi ~= %1.5f", acos(-1.0);
1692 MainLoop;
1694 To tie a scrolled Text widget, use the Subwidget method to get to the
1696 "real" widget:
1697 my $text = $mw->Scrolled('Text')->pack;
1699 tie *STDOUT, 'Tk::Text', $text->Subwidget('scrolled');
1700
1702 Text widgets should run efficiently under a variety of conditions. The
1703 text widget uses about 2-3 bytes of main memory for each byte of text,
1704 so texts containing a megabyte or more should be practical on most
1705 workstations. Text is represented internally with a modified B-tree
1706 structure that makes operations relatively efficient even with large
1707 texts. Tags are included in the B-tree structure in a way that allows
1708 tags to span large ranges or have many disjoint smaller ranges without
1709 loss of efficiency. Marks are also implemented in a way that allows
1710 large numbers of marks. In most cases it is fine to have large numbers
1711 of unique tags, or a tag that has many distinct ranges.
1712 One performance problem can arise if you have hundreds or thousands of
1714 different tags that all have the following characteristics: the first
1715 and last ranges of each tag are near the beginning and end of the text,
1716 respectively, or a single tag range covers most of the text widget.
1717 The cost of adding and deleting tags like this is proportional to the
1718 number of other tags with the same properties. In contrast, there is
1719 no problem with having thousands of distinct tags if their overall
1720 ranges are localized and spread uniformly throughout the text.
1721 Very long text lines can be expensive, especially if they have many
1723 marks and tags within them.
1724 The display line with the insert cursor is redrawn each time the cursor
1726 blinks, which causes a steady stream of graphics traffic. Set the
1727 -insertofftime option to 0 avoid this.
1728
1730 Tk::ROText Tk::TextUndo
1731
1733 text, widget
1734perl v5.32.1 2021-01-27 Text(3)