1Text(3)               User Contributed Perl Documentation              Text(3)
2
3
4

NAME

6       Tk::Text - Create and manipulate Text widgets
7

SYNOPSIS

9       $text = $parent->Text(?options?);
10
11       -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

WIDGET-SPECIFIC OPTIONS

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
25       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
33       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
42       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
50       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
58       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
86       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
94       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

DESCRIPTION

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
114       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
123       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
128       The third form of annotation allows arbitrary windows to be embedded in
129       a text widget.  See "EMBEDDED WINDOWS" below for more details.
130
131       The fourth form of annotation allows Tk images to be embedded in a text
132       widget.  See "EMBEDDED IMAGES" below for more details.
133
134       The Perl/Tk Text widget does not support undo/redo, use the TextUndo
135       widget instead.
136

INDICES

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
143        base modifier modifier modifier ...
144
145       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
149       The base for an index must have one of the following forms:
150
151       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
157       @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
161       end Indicates the end of the text (the character just after the last
162           newline).
163
164       mark
165           Indicates the character just after the mark whose name is mark.
166
167       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
172       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
177       $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
182       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
187       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
194       + 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
201       - 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
208       + 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
218       - 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
228       linestart
229           Adjust the index to refer to the first character on the line.
230
231       lineend
232           Adjust the index to refer to the last character on the line (the
233           newline).
234
235       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
241       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
246       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

TAGS

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
263       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
271       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
280       -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
285       -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
291       -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
298       -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
303       -data => value
304           Allows an arbitrary perl scalar value to be associated with the
305           tag.
306
307       -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
314       -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
318       -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
323       -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
330       -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
339       -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
349       -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
356       -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
361       -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
368       -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
377       -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
383       -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
388       -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
394       -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
404       -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
409       -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
415       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
423       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
432       The third use for tags is in managing the selection.  See "THE
433       SELECTION" below.
434

MARKS

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
450       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
459       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
463       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

EMBEDDED WINDOWS

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
489       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
494       -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
503       -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
513       -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
518       -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
523       -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
531       -window => $widget
532           Specifies the name of a window to display in the annotation.
533

EMBEDDED IMAGES

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
548       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
559       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
564       -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
573       -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
577       -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
583       -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
588       -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

THE SELECTION

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
598       [1] Whenever characters are tagged with sel the text widget will claim
599           ownership of the selection.
600
601       [2] Attempts to retrieve the selection will be serviced by the text
602           widget, returning all the characters with the sel tag.
603
604       [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
608       [4] Whenever the sel tag range changes a virtual event <<Selection>> is
609           generated.
610
611           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

THE INSERTION CURSOR

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

THE MODIFIED FLAG

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

WIDGET METHODS

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
639       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
644       $text->adjustSelect
645           Moves the end point of the selection and anchor point to the mouse
646           pointer location.
647
648       $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
658       $text->clipboardColumnCopy
659           Performs a rectangular copy of the currently selected text with
660           basic compensation for tab characters.
661
662       $text->clipboardColumnCut
663           Performs a rectangular cut of the currently selected text with
664           basic compensation for tab characters.
665
666       $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
671       $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
680       $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
686       $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
699       $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
719       $text->deleteSelected
720           Delete the currently selected text.
721
722       $text->deleteTextTaggedWith(tag)
723           Delete the text tagged with the tag parameter.
724
725       $text->deleteToEndofLine
726           Delete from the insert mark location to the end of line.
727
728       $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
745       $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
752           key1 value1 index1 key2 value2 index2 ...
753
754           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
761           -all
762               Return information about all elements: text, marks, tags, and
763               windows.  This is the default.
764
765           -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
772           -mark
773               Include information about marks in the dump results.
774
775           -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
781           -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
789           -window
790
791           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
797       $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
803           $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
809           $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
815           $text->editReset;
816               (Not implemented, use TextUndo.) Clears the undo and redo
817               stacks.
818
819           $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
823           $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
831       $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
835           mode can be be -exact or -regexp. See the search command for more
836           information
837
838           case can be -nocase or -case. See the search command for more
839           information
840
841           pattern is an exact string to match if mode is -exact or a regular
842           expression if the match mode is -regexp.
843
844       $text->FindAndReplaceAll(mode, case, find, replace)
845           Same as the FindAll method, however additionally substitutes the
846           matched text with the characters replace.
847
848       $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
853       $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
859       $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
864       $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
870       $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
876       $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
891       $text->getSelected
892           Return the currently selected text.
893
894       $text->GetTextTaggedWith(tag)
895           Return the text tagged with the tag parameter.
896
897       $text->GotoLineNumber(line_number)
898           Set the insert mark to line_number and ensures the line is visible.
899
900       $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
904       $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
911           $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
917           $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
932           $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
941           $text->imageNames
942                   Returns a list whose elements are the names of all image
943                   instances currently embedded in $text.
944
945       $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
950       $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
966       $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
972       $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
976       $text->InsertSelection
977           Inserts the current selection at the insert mark.
978
979       $text->insertTab
980           Inserts a tab (\t) character at the insert mark.
981
982       $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
988           $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
994           $text->markNames
995                   Returns a list whose elements are the names of all the
996                   marks that are currently set.
997
998           $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
1013           $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
1027           $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
1033           $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
1040       $text->markExists(markname)
1041           Returns true if markname exists - false otherwise.
1042
1043       $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
1050       $text->openLine
1051           Inserts a newline (\n) at the insert mark.
1052
1053       $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
1057       $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
1064       $text->ResetAnchor
1065           Sets the selection anchor to whichever end is farthest from the
1066           index argument.
1067
1068       $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
1073           $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
1079           $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
1089       $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
1096           -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
1101           -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
1106           -exact  Use exact matching:  the characters in the matching range
1107                   must be identical to those in pattern.  This is the
1108                   default.
1109
1110           -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
1114           -nocase Ignore case differences between the pattern and the text.
1115
1116           -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
1121           -hidden Find hidden text as well. By default only displayed text is
1122                   found.
1123
1124           --      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
1128       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
1140       $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
1148       $text->selectAll
1149           Selects all the text in the widget.
1150
1151       $text->selectLine
1152           Selects the line with the insert mark.
1153
1154       $text->selectWord
1155           Selects the word with the insert mark.
1156
1157       $text->SetCursor(position)
1158           Moves the insert mark to position.
1159
1160       $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
1166           $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
1176           $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
1197                   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
1214                   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
1225                   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
1230           $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
1236           $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
1254           $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
1261           $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
1267           $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
1278           $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
1292           $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
1306           $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
1312           $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
1323           $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
1334       $text->ToggleInsertMode
1335           Toggles the current overstrike mode.
1336
1337       $text->unselectAll
1338           Unselects all the text in the widget.
1339
1340       $text->WhatLineNumberPopup
1341           Creates a popup that displays the current line number of the insert
1342           mark.
1343
1344       $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
1351           $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
1357           $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
1372           $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
1380           $text->windowNames
1381                   Returns a list whose elements are the names of all windows
1382                   currently embedded in $text.
1383
1384       $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
1389           $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
1404           $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
1409           $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
1420       $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
1425           $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
1436           $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
1443           $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
1453           $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
1460                   [1]         If index is already visible somewhere in the
1461                               window then the command does nothing.
1462
1463                   [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
1467                   [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
1471                   [4]         Otherwise, index will be centered in the
1472                               window.
1473
1474       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
1478       $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

BINDINGS

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
1490       [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
1496       [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
1501       [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
1506       [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
1514       [5] Clicking mouse button 1 with the Control key down will reposition
1515           the insertion cursor without affecting the selection.
1516
1517       [6] If any normal printing characters are typed, they are inserted at
1518           the point of the insertion cursor.
1519
1520       [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
1526       [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
1531       [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
1542       [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
1553       [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
1561       [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
1566       [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
1572       [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
1577       [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
1583       [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
1589       [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
1597       [18]
1598           Control-/ selects the entire contents of the widget.
1599
1600       [19]
1601           Control-\ clears any selection in the widget.
1602
1603       [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
1608       [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
1614       [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
1619       [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
1624       [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
1629       [25]
1630           Control-d deletes the character to the right of the insertion
1631           cursor.
1632
1633       [26]
1634           Meta-d deletes the word to the right of the insertion cursor.
1635
1636       [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
1641       [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
1645       [29]
1646           Meta-backspace and Meta-Delete delete the word to the left of the
1647           insertion cursor.
1648
1649       [30]
1650           Control-x deletes whatever is selected in the text widget.
1651
1652       [31]
1653           Control-t reverses the order of the two characters to the right of
1654           the insertion cursor.
1655
1656       [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
1661       [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
1665       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
1669       The behavior of texts can be changed by defining new bindings for
1670       individual widgets or by redefining the class bindings.
1671

TIED INTERFACE

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
1678       For example:
1679
1680        #!/usr/local/bin/perl -w
1681        use POSIX 'acos';
1682        use Tk;
1683        use strict;
1684
1685        my $mw = MainWindow->new;
1686        my $text = $mw->Text(qw/-width 40 -height 10/)->pack;
1687
1688        tie *STDOUT, ref $text, $text;
1689
1690        print "Hello Text World!\n";
1691        printf "pi ~= %1.5f", acos(-1.0);
1692
1693        MainLoop;
1694
1695       To tie a scrolled Text widget, use the Subwidget method to get to the
1696       "real" widget:
1697
1698        my $text = $mw->Scrolled('Text')->pack;
1699        tie *STDOUT, 'Tk::Text', $text->Subwidget('scrolled');
1700

PERFORMANCE ISSUES

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
1713       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
1722       Very long text lines can be expensive, especially if they have many
1723       marks and tags within them.
1724
1725       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

SEE ALSO

1730       Tk::ROText Tk::TextUndo
1731

KEYWORDS

1733       text, widget
1734
1735
1736
1737perl v5.32.1                      2021-01-27                           Text(3)
Impressum