summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/Text.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Text.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/Text.pod2220
1 files changed, 0 insertions, 2220 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/Text.pod b/Master/tlpkg/tlperl/lib/Tk/Text.pod
deleted file mode 100644
index 200cda9b033..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/Text.pod
+++ /dev/null
@@ -1,2220 +0,0 @@
-# Copyright (c) 1992 The Regents of the University of California.
-# Copyright (c) 1994-1996 Sun Microsystems, Inc.
-# Copyright (c) 2002 O'Reilly & Associates Inc.
-# See the file "license.terms" for information on usage and redistribution
-# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-#
-#
-
-=head1 NAME
-
-Tk::Text - Create and manipulate Text widgets
-
-=for category Tk Widget Classes
-
-=head1 SYNOPSIS
-
-I<$text> = I<$parent>-E<gt>B<Text>(?I<options>?);
-
-B<-background> B<-highlightbackground> B<-insertontime> B<-selectborderwidth>
-B<-borderwidth> B<-highlightcolor> B<-insertwidth> B<-selectforeground>
-B<-cursor> B<-highlightthickness> B<-padx> B<-setgrid>
-B<-exportselection> B<-insertbackground> B<-pady> B<-takefocus>
-B<-font> B<-insertborderwidth> B<-relief> B<-xscrollcommand>
-B<-foreground> B<-insertofftime> B<-selectbackground> B<-yscrollcommand>
-
-=head1 WIDGET-SPECIFIC OPTIONS
-
-=over 4
-
-=item Name: B<height>
-
-=item Class: B<Height>
-
-=item Switch: B<-height>
-
-Specifies the desired height for the window, in units of characters
-in the font given by the B<-font> option.
-Must be at least one.
-
-=item Name: B<spacing1>
-
-=item Class: B<Spacing1>
-
-=item Switch: B<-spacing1>
-
-Requests additional space above each text line in the widget,
-using any of the standard forms for screen distances.
-If a line wraps, this option only applies to the first line
-on the display.
-This option may be overriden with B<-spacing1> options in
-tags.
-
-=item Name: B<spacing2>
-
-=item Class: B<Spacing2>
-
-=item Switch: B<-spacing2>
-
-For lines that wrap (so that they cover more than one line on the
-display) this option specifies additional space to provide between
-the display lines that represent a single line of text.
-The value may have any of the standard forms for screen distances.
-This option may be overriden with B<-spacing2> options in
-tags.
-
-=item Name: B<spacing3>
-
-=item Class: B<Spacing3>
-
-=item Switch: B<-spacing3>
-
-Requests additional space below each text line in the widget,
-using any of the standard forms for screen distances.
-If a line wraps, this option only applies to the last line
-on the display.
-This option may be overriden with B<-spacing3> options in
-tags.
-
-=item Name: B<state>
-
-=item Class: B<State>
-
-=item Switch: B<-state>
-
-Specifies one of two states for the text: B<normal> or B<disabled>.
-If the text is disabled then characters may not be inserted or deleted
-and no insertion cursor will be displayed, even if the input focus is
-in the widget.
-
-=item Name: B<tabs>
-
-=item Class: B<Tabs>
-
-=item Switch: B<-tabs>
-
-Specifies a set of tab stops for the window. The option's value consists
-of a list of screen distances giving the positions of the tab stops. Each
-position may optionally be followed in the next list element
-by one of the keywords B<left>, B<right>, B<center>,
-or B<numeric>, which specifies how to justify
-text relative to the tab stop. B<Left> is the default; it causes
-the text following the tab character to be positioned with its left edge
-at the tab position. B<Right> means that the right edge of the text
-following the tab character is positioned at the tab position, and
-B<center> means that the text is centered at the tab position.
-B<Numeric> means that the decimal point in the text is positioned
-at the tab position; if there is no decimal point then the least
-significant digit of the number is positioned just to the left of the
-tab position; if there is no number in the text then the text is
-right-justified at the tab position.
-For example, B<-tabs =E<gt> [qw/2c left 4c 6c center/]> creates three
-tab stops at two-centimeter intervals; the first two use left
-justification and the third uses center justification.
-If the list of tab stops does not have enough elements to cover all
-of the tabs in a text line, then Tk extrapolates new tab stops using
-the spacing and alignment from the last tab stop in the list.
-The value of the B<tabs> option may be overridden by B<-tabs>
-options in tags.
-If no B<-tabs> option is specified, or if it is specified as
-an empty list, then Tk uses default tabs spaced every eight
-(average size) characters.
-
-=item Name: B<width>
-
-=item Class: B<Width>
-
-=item Switch: B<-width>
-
-Specifies the desired width for the window in units of characters
-in the font given by the B<-font> option.
-If the font doesn't have a uniform width then the width of the
-character ``0'' is used in translating from character units to
-screen units.
-
-=item Name: B<wrap>
-
-=item Class: B<Wrap>
-
-=item Switch: B<-wrap>
-
-Specifies how to handle lines in the text that are too long to be
-displayed in a single line of the text's window.
-The value must be B<none> or B<char> or B<word>.
-A wrap mode of B<none> means that each line of text appears as
-exactly one line on the screen; extra characters that don't fit
-on the screen are not displayed.
-In the other modes each line of text will be broken up into several
-screen lines if necessary to keep all the characters visible.
-In B<char> mode a screen line break may occur after any character;
-in B<word> mode a line break will only be made at word boundaries.
-
-=back
-
-=head1 DESCRIPTION
-
-The B<Text> method creates a new window (given by the
-$text argument) and makes it into a text widget.
-Additional
-options, described above, may be specified on the command line
-or in the option database
-to configure aspects of the text such as its default background color
-and relief. The B<text> command returns the
-path name of the new window.
-
-A text widget displays one or more lines of text and allows that
-text to be edited.
-Text widgets support four different kinds of annotations on the
-text, called tags, marks, embedded windows or embedded images.
-Tags allow different portions of the text
-to be displayed with different fonts and colors.
-In addition, L<perl/Tk callbacks|Tk::callbacks> can be associated with tags so
-that scripts are invoked when particular actions such as keystrokes
-and mouse button presses occur in particular ranges of the text.
-See L<"TAGS"> below for more details.
-
-The second form of annotation consists of marks, which are floating
-markers in the text.
-Marks are used to keep track of various interesting positions in the
-text as it is edited.
-See L<"MARKS"> below for more details.
-
-The third form of annotation allows arbitrary windows to be
-embedded in a text widget.
-See L<"EMBEDDED WINDOWS"> below for more details.
-
-The fourth form of annotation allows Tk images to be embedded in a text
-widget.
-See L<"EMBEDDED IMAGES"> below for more details.
-
-The Perl/Tk B<Text> widget does not support undo/redo, use the B<TextUndo>
-widget instead.
-
-=head1 INDICES
-
-Many of the methods for texts take one or more indices
-as arguments.
-An index is a string used to indicate a particular place within
-a text, such as a place to insert characters or one endpoint of a
-range of characters to delete.
-Indices have the syntax
-
- base modifier modifier modifier ...
-
-Where I<base> gives a starting point and the I<modifier>s
-adjust the index from the starting point (e.g. move forward or
-backward one character). Every index must contain a I<base>,
-but the I<modifier>s are optional.
-
-The I<base> for an index must have one of the following forms:
-
-=over 4
-
-=item I<line>B<.>I<char>
-
-Indicates I<char>'th character on line I<line>.
-Lines are numbered from 1 for consistency with other UNIX programs
-that use this numbering scheme.
-Within a line, characters are numbered from 0.
-If I<char> is B<end> then it refers to the newline character
-that ends the line.
-
-=item B<@>I<x>B<,>I<y>
-
-Indicates the character that covers the pixel whose x and y coordinates
-within the text's window are I<x> and I<y>.
-
-=item B<end>
-
-Indicates the end of the text (the character just after the last
-newline).
-
-=item I<mark>
-
-Indicates the character just after the mark whose name is I<mark>.
-
-=item I<tag>B<.first>
-
-Indicates the first character in the text that has been tagged with
-I<tag>.
-This form generates an error if no characters are currently tagged
-with I<tag>.
-
-=item I<tag>B<.last>
-
-Indicates the character just after the last one in the text that has
-been tagged with I<tag>.
-This form generates an error if no characters are currently tagged
-with I<tag>.
-
-=item I<$widget>
-
-Indicates the position of the embedded window referenced by I<$widget>.
-This form generates an error if I<$widget> does not reference to an
-embedded window.
-
-=item I<imageName>
-
-Indicates the position of the embedded image whose name is
-I<imageName>.
-This form generates an error if there is no embedded image
-by the given name.
-
-If the I<base> could match more than one of the above forms, such
-as a I<mark> and I<imageName> both having the same value, then
-the form earlier in the above list takes precedence.
-If modifiers follow the base index, each one of them must have one
-of the forms listed below. Keywords such as B<chars> and B<wordend>
-may be abbreviated as long as the abbreviation is unambiguous.
-
-=item B<+ >I<count>B< chars>
-
-Adjust the index forward by I<count> characters, moving to later
-lines in the text if necessary. If there are fewer than I<count>
-characters in the text after the current index, then set the index
-to the last character in the text.
-Spaces on either side of I<count> are optional.
-
-=item B<- >I<count>B< chars>
-
-Adjust the index backward by I<count> characters, moving to earlier
-lines in the text if necessary. If there are fewer than I<count>
-characters in the text before the current index, then set the index
-to the first character in the text.
-Spaces on either side of I<count> are optional.
-
-=item B<+ >I<count>B< lines>
-
-Adjust the index forward by I<count> lines, retaining the same
-character position within the line. If there are fewer than I<count>
-lines after the line containing the current index, then set the index
-to refer to the same character position on the last line of the text.
-Then, if the line is not long enough to contain a character at the indicated
-character position, adjust the character position to refer to the last
-character of the line (the newline).
-Spaces on either side of I<count> are optional.
-
-=item B<- >I<count>B< lines>
-
-Adjust the index backward by I<count> lines, retaining the same
-character position within the line. If there are fewer than I<count>
-lines before the line containing the current index, then set the index
-to refer to the same character position on the first line of the text.
-Then, if the line is not long enough to contain a character at the indicated
-character position, adjust the character position to refer to the last
-character of the line (the newline).
-Spaces on either side of I<count> are optional.
-
-=item B<linestart>
-
-Adjust the index to refer to the first character on the line.
-
-=item B<lineend>
-
-Adjust the index to refer to the last character on the line (the newline).
-
-=item B<wordstart>
-
-Adjust the index to refer to the first character of the word containing
-the current index. A word consists of any number of adjacent characters
-that are letters, digits, or underscores, or a single character that
-is not one of these.
-
-=item B<wordend>
-
-Adjust the index to refer to the character just after the last one of the
-word containing the current index. If the current index refers to the last
-character of the text then it is not modified.
-
-If more than one modifier is present then they are applied in
-left-to-right order. For example, the index ``B<end - 1 chars>''
-refers to the next-to-last character in the text and
-``B<insert wordstart - 1 c>'' refers to the character just before
-the first one in the word containing the insertion cursor.
-
-=back
-
-=head1 TAGS
-
-The first form of annotation in text widgets is a tag.
-A tag is a textual string that is associated with some of the characters
-in a text.
-Tags may contain arbitrary characters, but it is probably best to
-avoid using the the characters `` '' (space), B<+>, or B<->:
-these characters have special meaning in indices, so tags containing
-them can't be used as indices.
-There may be any number of tags associated with characters in a
-text.
-Each tag may refer to a single character, a range of characters, or
-several ranges of characters.
-An individual character may have any number of tags associated with it.
-
-A priority order is defined among tags, and this order is used in
-implementing some of the tag-related functions described below.
-When a tag is defined (by associating it with characters or setting
-its display options or binding callbacks to it), it is given
-a priority higher than any existing tag.
-The priority order of tags may be redefined using the
-``I<$text>-E<gt>B<tagRaise>'' and ``I<$text>-E<gt>B<tagLower>''
-methods.
-
-Tags serve three purposes in text widgets.
-First, they control the way information is displayed on the screen.
-By default, characters are displayed as determined by the
-B<background>, B<font>, and B<foreground> options for the
-text widget.
-However, display options may be associated with individual tags
-using the ``I<$text>-E<gt>B<tagConfigure>'' method.
-If a character has been tagged, then the display options associated
-with the tag override the default display style.
-The following options are currently supported for tags:
-
-=over 4
-
-=item B<-background> =E<gt> I<color>
-
-I<Color> specifies the background color to use for characters
-associated with the tag.
-It may have any of the forms accepted by B<Tk_GetColor>.
-
-=item B<-bgstipple> =E<gt> I<bitmap>
-
-I<Bitmap> specifies a bitmap that is used as a stipple pattern
-for the background.
-It may have any of the forms accepted by B<Tk_GetBitmap>.
-If I<bitmap> hasn't been specified, or if it is specified
-as an empty string, then a solid fill will be used for the
-background.
-
-=item B<-borderwidth> =E<gt> I<pixels>
-
-I<Pixels> specifies the width of a 3-D border to draw around
-the background.
-It may have any of the forms accepted by B<Tk_GetPixels>.
-This option is used in conjunction with the B<-relief>
-option to give a 3-D appearance to the background for characters;
-it is ignored unless the B<-background> option
-has been set for the tag.
-
-=item B<-elide> =E<gt> boolean
-
-Elide specifies whether the data should be elided. Elided data
-is not displayed and takes no space on screen, but further on
-behaves just as normal data.
-
-=item B<-data> =E<gt> I<value>
-
-Allows an arbitrary perl scalar I<value> to be associated with the tag.
-
-=item B<-fgstipple> =E<gt> I<bitmap>
-
-I<Bitmap> specifies a bitmap that is used as a stipple pattern
-when drawing text and other foreground information such as
-underlines.
-It may have any of the forms accepted by B<Tk_GetBitmap>.
-If I<bitmap> hasn't been specified, or if it is specified
-as an empty string, then a solid fill will be used.
-
-=item B<-font> =E<gt> I<fontName>
-
-I<FontName> is the name of a font to use for drawing characters.
-It may have any of the forms accepted by B<Tk_GetFontStruct>.
-
-=item B<-foreground> =E<gt> I<color>
-
-I<Color> specifies the color to use when drawing text and other
-foreground information such as underlines.
-It may have any of the forms accepted by B<Tk_GetColor>.
-
-=item B<-justify> =E<gt> I<justify>
-
-If the first character of a display line has a tag for which this
-option has been specified, then I<justify> determines how to
-justify the line.
-It must be one of B<left>, B<right>, or B<center>.
-If a line wraps, then the justification for each line on the
-display is determined by the first character of that display line.
-
-=item B<-lmargin1> =E<gt> I<pixels>
-
-If the first character of a text line has a tag for which this
-option has been specified, then I<pixels> specifies how
-much the line should be indented from the left edge of the
-window.
-I<Pixels> may have any of the standard forms for screen
-distances.
-If a line of text wraps, this option only applies to the
-first line on the display; the B<-lmargin2> option controls
-the indentation for subsequent lines.
-
-=item B<-lmargin2> =E<gt> I<pixels>
-
-If the first character of a display line has a tag for which this
-option has been specified, and if the display line is not the
-first for its text line (i.e., the text line has wrapped), then
-I<pixels> specifies how much the line should be indented from
-the left edge of the window.
-I<Pixels> may have any of the standard forms for screen
-distances.
-This option is only used when wrapping is enabled, and it only
-applies to the second and later display lines for a text line.
-
-=item B<-offset> =E<gt> I<pixels>
-
-I<Pixels> specifies an amount by which the text's baseline
-should be offset vertically from the baseline of the overall
-line, in pixels.
-For example, a positive offset can be used for superscripts
-and a negative offset can be used for subscripts.
-I<Pixels> may have any of the standard forms for screen
-distances.
-
-=item B<-overstrike> =E<gt> I<boolean>
-
-Specifies whether or not to draw a horizontal rule through
-the middle of characters.
-I<Boolean> may have any of the forms accepted by B<Tk_GetBoolean>.
-
-=item B<-relief> =E<gt> I<relief>
-
-I<Relief> specifies the 3-D relief to use for drawing backgrounds,
-in any of the forms accepted by B<Tk_GetRelief>.
-This option is used in conjunction with the B<-borderwidth>
-option to give a 3-D appearance to the background for characters;
-it is ignored unless the B<-background> option
-has been set for the tag.
-
-=item B<-rmargin> =E<gt> I<pixels>
-
-If the first character of a display line has a tag for which this
-option has been specified, then I<pixels> specifies how wide
-a margin to leave between the end of the line and the right
-edge of the window.
-I<Pixels> may have any of the standard forms for screen
-distances.
-This option is only used when wrapping is enabled.
-If a text line wraps, the right margin for each line on the
-display is determined by the first character of that display
-line.
-
-=item B<-spacing1> =E<gt> I<pixels>
-
-I<Pixels> specifies how much additional space should be
-left above each text line, using any of the standard forms for
-screen distances.
-If a line wraps, this option only applies to the first
-line on the display.
-
-=item B<-spacing2> =E<gt> I<pixels>
-
-For lines that wrap, this option specifies how much additional
-space to leave between the display lines for a single text line.
-I<Pixels> may have any of the standard forms for screen
-distances.
-
-=item B<-spacing3> =E<gt> I<pixels>
-
-I<Pixels> specifies how much additional space should be
-left below each text line, using any of the standard forms for
-screen distances.
-If a line wraps, this option only applies to the last
-line on the display.
-
-=item B<-tabs> =E<gt> I<tabList>
-
-I<TabList> specifies a set of tab stops in the same form
-as for the B<-tabs> option for the text widget. This
-option only applies to a display line if it applies to the
-first character on that display line.
-If this option is specified as an empty string, it cancels
-the option, leaving it unspecified for the tag (the default).
-If the option is specified as a non-empty string that is
-an empty list, such as B<-tabs => " ">, then it requests
-default 8-character tabs as described for the B<tabs>
-widget option.
-
-=item B<-underline> =E<gt> I<boolean>
-
-I<Boolean> specifies whether or not to draw an underline underneath
-characters.
-It may have any of the forms accepted by B<Tk_GetBoolean>.
-
-=item B<-wrap> =E<gt> I<mode>
-
-I<Mode> specifies how to handle lines that are wider than the
-text's window.
-It has the same legal values as the B<-wrap> option
-for the text widget: B<none>, B<char>, or B<word>.
-If this tag option is specified, it overrides the B<-wrap> option
-for the text widget.
-
-=back
-
-If a character has several tags associated with it, and if their
-display options conflict, then the options of the highest priority
-tag are used.
-If a particular display option hasn't been specified for a
-particular tag, or if it is specified as an empty string, then
-that option will never be used; the next-highest-priority
-tag's option will used instead.
-If no tag specifies a particular display option, then the default
-style for the widget will be used.
-
-The second purpose for tags is event bindings.
-You can associate bindings with a tag in much the same way you can
-associate bindings with a widget class: whenever particular X
-events occur on characters with the given tag, a given
-<perl/Tk callback|Tk::callbacks> will be executed.
-Tag bindings can be used to give behaviors to ranges of characters;
-among other things, this allows hypertext-like
-features to be implemented.
-For details, see the description of the B<tagBind> widget
-method below.
-
-The third use for tags is in managing the selection.
-See L<"THE SELECTION"> below.
-
-=head1 MARKS
-
-The second form of annotation in text widgets is a mark.
-Marks are used for remembering particular places in a text.
-They are something like tags, in that they have names and
-they refer to places in the file, but a mark isn't associated
-with particular characters.
-Instead, a mark is associated with the gap between two characters.
-Only a single position may be associated with a mark at any given
-time.
-If the characters around a mark are deleted the mark will still
-remain; it will just have new neighbor characters.
-In contrast, if the characters containing a tag are deleted then
-the tag will no longer have an association with characters in
-the file.
-Marks may be manipulated with the ``I<$text>-E<gt>B<mark>'' text widget
-method, and their current locations may be determined by using the
-mark name as an index in methods.
-
-Each mark also has a I<gravity>, which is either B<left> or
-B<right>.
-The gravity for a mark specifies what happens to the mark when
-text is inserted at the point of the mark.
-If a mark has left gravity, then the mark is treated as if it
-were attached to the character on its left, so the mark will
-remain to the left of any text inserted at the mark position.
-If the mark has right gravity, new text inserted at the mark
-position will appear to the right of the mark. The gravity
-for a mark defaults to B<right>.
-
-The name space for marks is different from that for tags: the
-same name may be used for both a mark and a tag, but they will refer
-to different things.
-
-Two marks have special significance.
-First, the mark B<insert> is associated with the insertion cursor,
-as described under L<"THE INSERTION CURSOR"> below.
-Second, the mark B<current> is associated with the character
-closest to the mouse and is adjusted automatically to track the
-mouse position and any changes to the text in the widget (one
-exception: B<current> is not updated in response to mouse
-motions if a mouse button is down; the update will be deferred
-until all mouse buttons have been released).
-Neither of these special marks may be deleted.
-
-=head1 EMBEDDED WINDOWS
-
-The third form of annotation in text widgets is an embedded window.
-Each embedded window annotation causes a window to be displayed
-at a particular point in the text.
-There may be any number of embedded windows in a text widget,
-and any widget may be used as an embedded window (subject to the
-usual rules for geometry management, which require the text window
-to be the parent of the embedded window or a descendant of its
-parent).
-The embedded window's position on the screen will be updated as the
-text is modified or scrolled, and it will be mapped and unmapped as
-it moves into and out of the visible area of the text widget.
-Each embedded window occupies one character's worth of index space
-in the text widget, and it may be referred to either by the name
-of its embedded window or by its position in the widget's
-index space.
-If the range of text containing the embedded window is deleted then
-the window is destroyed.
-
-When an embedded window is added to a text widget with the
-B<widgetCreate> method, several configuration
-options may be associated with it.
-These options may be modified later with the B<widgetConfigure>
-method.
-The following options are currently supported:
-
-=over 4
-
-=item B<-align> =E<gt> I<where>
-
-If the window is not as tall as the line in which it is displayed,
-this option determines where the window is displayed in the line.
-I<Where> must have one of the values B<top> (align the top of the window
-with the top of the line), B<center> (center the window
-within the range of the line), B<bottom> (align the bottom of the
-window with the bottom of the line's area),
-or B<baseline> (align the bottom of the window with the baseline
-of the line).
-
-=item B<-create> =E<gt> I<callback>
-
-Specifies a L<callback|Tk::callbacks> that may be evaluated to create the window
-for the annotation.
-If no B<-window> option has been specified for the annotation
-this I<callback> will be evaluated when the annotation is about to
-be displayed on the screen.
-I<Callback> must create a window for the annotation and return
-the name of that window as its result.
-If the annotation's window should ever be deleted, I<callback>
-will be evaluated again the next time the annotation is displayed.
-
-=item B<-padx> =E<gt> I<pixels>
-
-I<Pixels> specifies the amount of extra space to leave on
-each side of the embedded window.
-It may have any of the usual forms defined for a screen distance
-(see B<Tk_GetPixels>).
-
-=item B<-pady> =E<gt> I<pixels>
-
-I<Pixels> specifies the amount of extra space to leave on
-the top and on the bottom of the embedded window.
-It may have any of the usual forms defined for a screen distance
-(see B<Tk_GetPixels>).
-
-=item B<-stretch> =E<gt> I<boolean>
-
-If the requested height of the embedded window is less than the
-height of the line in which it is displayed, this option can be
-used to specify whether the window should be stretched vertically
-to fill its line.
-If the B<-pady> option has been specified as well, then the
-requested padding will be retained even if the window is
-stretched.
-
-=item B<-window> =E<gt> I<$widget>
-
-Specifies the name of a window to display in the annotation.
-
-=back
-
-=head1 EMBEDDED IMAGES
-
-The final form of annotation in text widgets is an embedded image.
-Each embedded image annotation causes an image to be displayed
-at a particular point in the text.
-There may be any number of embedded images in a text widget,
-and a particular image may be embedded in multiple places in the same
-text widget.
-The embedded image's position on the screen will be updated as the
-text is modified or scrolled.
-Each embedded image occupies one character's worth of index space
-in the text widget, and it may be referred to either by
-its position in the widget's index space, or the name it is assigned
-when the image is inserted into the text widget with B<imageCreate>.
-If the range of text containing the embedded image is deleted then
-that copy of the image is removed from the screen.
-
-When an embedded image is added to a text widget with the B<image>
-create method, a name unique to this instance of the image
-is returned. This name may then be used to refer to this image
-instance. The name is taken to be the value of the B<-name> option
-(described below). If the B<-name> option is not provided, the
-B<-image> name is used instead. If the I<imageName> is already
-in use in the text widget, then B<#>I<nn> is added to the end of the
-I<imageName>, where I<nn> is an arbitrary integer. This insures
-the I<imageName> is unique.
-Once this name is assigned to this instance of the image, it does not
-change, even though the B<-image> or B<-name> values can be changed
-with B<image configure>.
-
-When an embedded image is added to a text widget with the
-B<imageCreate> method, several configuration
-options may be associated with it.
-These options may be modified later with the B<image configure>
-method.
-The following options are currently supported:
-
-=over 4
-
-=item B<-align> =E<gt> I<where>
-
-If the image is not as tall as the line in which it is displayed,
-this option determines where the image is displayed in the line.
-I<Where> must have one of the values B<top> (align the top of the image
-with the top of the line), B<center> (center the image
-within the range of the line), B<bottom> (align the bottom of the
-image with the bottom of the line's area),
-or B<baseline> (align the bottom of the image with the baseline
-of the line).
-
-=item B<-image> =E<gt> I<image>
-
-Specifies the name of the Tk image to display in the annotation.
-If I<image> is not a valid Tk image, then an error is returned.
-
-=item B<-name> =E<gt> I<ImageName>
-
-Specifies the name by which this image instance may be referenced in
-the text widget. If I<ImageName> is not supplied, then the
-name of the Tk image is used instead.
-If the I<imageName> is already in use, I<#nn> is appended to
-the end of the name as described above.
-
-=item B<-padx> =E<gt> I<pixels>
-
-I<Pixels> specifies the amount of extra space to leave on
-each side of the embedded image.
-It may have any of the usual forms defined for a screen distance.
-
-=item B<-pady> =E<gt> I<pixels>
-
-I<Pixels> specifies the amount of extra space to leave on
-the top and on the bottom of the embedded image.
-It may have any of the usual forms defined for a screen distance.
-
-=back
-
-=head1 THE SELECTION
-
-Selection support is implemented via tags.
-If the B<exportSelection> option for the text widget is true
-then the B<sel> tag will be associated with the selection:
-
-=over 4
-
-=item [1]
-
-Whenever characters are tagged with B<sel> the text widget
-will claim ownership of the selection.
-
-=item [2]
-
-Attempts to retrieve the
-selection will be serviced by the text widget, returning all the
-characters with the B<sel> tag.
-
-=item [3]
-
-If the selection is claimed away by another application or by another
-window within this application, then the B<sel> tag will be removed
-from all characters in the text.
-
-=item [4]
-
-Whenever the sel tag range changes a virtual event B<<<Selection>>>
-is generated.
-
-The B<sel> tag is automatically defined when a text widget is
-created, and it may not be deleted with the ``I<$text>-E<gt>B<tagDelete>''
-method. Furthermore, the B<selectBackground>,
-B<selectBorderWidth>, and B<selectForeground> options for
-the text widget are tied to the B<-background>,
-B<-borderwidth>, and B<-foreground> options for the B<sel>
-tag: changes in either will automatically be reflected in the
-other.
-
-=back
-
-=head1 THE INSERTION CURSOR
-
-The mark named B<insert> has special significance in text widgets.
-It is defined automatically when a text widget is created and it
-may not be unset with the ``I<$text>-E<gt>B<markUnset>'' widget
-command.
-The B<insert> mark represents the position of the insertion
-cursor, and the insertion cursor will automatically be drawn at
-this point whenever the text widget has the input focus.
-
-=head1 THE MODIFIED FLAG
-
-The text widget can keep track of changes to the content of the widget
-by means of the modified flag. Inserting or deleting text will set this
-flag. The flag can be queried, set and cleared programatically as well.
-Whenever the flag changes state a B<<<Modified>>> virtual event is gener-
-ated. See the edit modified widget command for more details.
-
-
-=head1 WIDGET METHODS
-
-The B<Text> method creates a widget object.
-This object supports the B<configure> and B<cget> methods
-described in L<Tk::options> which can be used to enquire and
-modify the options described above.
-The widget also inherits all the methods provided by the generic
-L<Tk::Widget|Tk::Widget> class.
-
-The following additional methods are available for text widgets.
-In addition, the extended text widget methods as documented
-in I<"Mastering Perl/Tk"> are included in this pod (with
-permission from the publisher, B<O'Reilly and Associates Inc.>).
-
-=over 4
-
-=item I<$text>-E<gt>B<adjustSelect>
-
-Moves the end point of the selection and anchor point to the
-mouse pointer location.
-
-=item I<$text>-E<gt>B<bbox>(I<index>)
-
-Returns a list of four elements describing the screen area
-of the character given by I<index>.
-The first two elements of the list give the x and y coordinates
-of the upper-left corner of the area occupied by the
-character, and the last two elements give the width and height
-of the area.
-If the character is only partially visible on the screen, then
-the return value reflects just the visible part.
-If the character is not visible on the screen then the return
-value is an empty list.
-
-=item I<$text>-E<gt>B<clipboardColumnCopy>
-
-Performs a rectangular copy of the currently selected text with
-basic compensation for tab characters.
-
-=item I<$text>-E<gt>B<clipboardColumnCut>
-
-Performs a rectangular cut of the currently selected text with
-basic compensation for tab characters.
-
-=item I<$text>-E<gt>B<clipboardColumnPaste>
-
-Performs a rectangular paste of the text in the clipboard. The
-upper-left corner is specified by the current position of the
-insert mark with basic compensation for tab characters.
-
-=item I<$text>-E<gt>B<compare>(I<index1, op, index2>)
-
-Compares the indices given by I<index1> and I<index2> according
-to the relational operator given by I<op>, and returns 1 if
-the relationship is satisfied and 0 if it isn't.
-I<Op> must be one of the operators E<lt>, E<lt>=, ==, E<gt>=, E<gt>, or !=.
-If I<op> is == then 1 is returned if the two indices refer to
-the same character, if I<op> is E<lt> then 1 is returned if I<index1>
-refers to an earlier character in the text than I<index2>, and
-so on.
-
-=item I<$text>-E<gt>B<Contents>(I<?args>?)
-
-Query or change the entire contents of the text widget. If no
-arguments are given, the entire contents of the text widget are
-returned. If any arguments are given, the entire contents of the
-text widget are deleted and replaced by the argument list.
-
-=item I<$text>-E<gt>B<debug>(?I<boolean>?)
-
-If I<boolean> is specified, then it must have one of the true or
-false values accepted by Tcl_GetBoolean.
-If the value is a true one then internal consistency checks will be
-turned on in the B-tree code associated with text widgets.
-If I<boolean> has a false value then the debugging checks will
-be turned off.
-In either case the command returns an empty string.
-If I<boolean> is not specified then the command returns B<on>
-or B<off> to indicate whether or not debugging is turned on.
-There is a single debugging switch shared by all text widgets: turning
-debugging on or off in any widget turns it on or off for all widgets.
-For widgets with large amounts of text, the consistency checks may
-cause a noticeable slow-down.
-
-=item I<$text>-E<gt>B<delete>(I<index1, >?I<index2>?)
-
-Delete a range of characters from the text.
-If both I<index1> and I<index2> are specified, then delete
-all the characters starting with the one given by I<index1>
-and stopping just before I<index2> (i.e. the character at
-I<index2> is not deleted).
-If I<index2> doesn't specify a position later in the text
-than I<index1> then no characters are deleted.
-If I<index2> isn't specified then the single character at
-I<index1> is deleted.
-It is not allowable to delete characters in a way that would leave
-the text without a newline as the last character.
-The command returns an empty string.
-If more indices are given, multiple ranges of text will
-be deleted. All indices are first checked for validity before
-any deletions are made. They are sorted and the text is removed
-from the last range to the first range to deleted text does not
-cause a undesired index shifting side-effects. If multiple
-ranges with the same start index are given, then the longest
-range is used. If overlapping ranges are given, then they will
-be merged into spans that do not cause deletion of text outside
-the given ranges due to text shifted during deletion.
-
-=item I<$text>-E<gt>B<deleteSelected>
-
-Delete the currently selected text.
-
-=item I<$text>-E<gt>B<deleteTextTaggedWith>(I<tag>)
-
-Delete the text tagged with the I<tag> parameter.
-
-=item I<$text>-E<gt>B<deleteToEndofLine>
-
-Delete from the insert mark location to the end of line.
-
-=item I<$text>-E<gt>B<dlineinfo>(I<index>)
-
-Returns a list with five elements describing the area occupied
-by the display line containing I<index>.
-The first two elements of the list give the x and y coordinates
-of the upper-left corner of the area occupied by the
-line, the third and fourth elements give the width and height
-of the area, and the fifth element gives the position of the baseline
-for the line, measured down from the top of the area.
-All of this information is measured in pixels.
-If the current wrap mode is B<none> and the line extends beyond
-the boundaries of the window,
-the area returned reflects the entire area of the line, including the
-portions that are out of the window.
-If the line is shorter than the full width of the window then the
-area returned reflects just the portion of the line that is occupied
-by characters and embedded windows.
-If the display line containing I<index> is not visible on
-the screen then the return value is an empty list.
-
-=item I<$text>-E<gt>B<dump>(?I<switches>?, I<index1, >?I<index2>?)
-
-Return the contents of the text widget from I<index1> up to,
-but not including I<index2>,
-including the text and
-information about marks, tags, and embedded windows.
-If I<index2> is not specified, then it defaults to
-one character past I<index1>. The information is returned
-in the following format:
-
-I<key1 value1 index1 key2 value2 index2> ...
-
-The possible I<key> values are B<text>, B<mark>,
-B<tagon>, B<tagoff>, and I<$text>. The corresponding
-I<value> is the text, mark name, tag name, or window name.
-The I<index> information is the index of the
-start of the text, the mark, the tag transition, or the window.
-One or more of the following switches (or abbreviations thereof)
-may be specified to control the dump:
-
-=over 4
-
-=item B<-all>
-
-Return information about all elements: text, marks, tags, and windows.
-This is the default.
-
-=item B<-command> =E<gt> I<callback>
-
-Instead of returning the information as the result of the dump operation,
-invoke the I<callback> on each element of the text widget within the range.
-The callback has three arguments appended to it before it is evaluated:
-the I<key>, I<value>, and I<index>.
-
-=item B<-mark>
-
-Include information about marks in the dump results.
-
-=item B<-tag>
-
-Include information about tag transitions in the dump results. Tag information is
-returned as B<tagon> and B<tagoff> elements that indicate the
-begin and end of each range of each tag, respectively.
-
-=item B<-text>
-
-Include information about text in the dump results. The value is the
-text up to the next element or the end of range indicated by I<index2>.
-A text element does not span newlines. A multi-line block of text that
-contains no marks or tag transitions will still be dumped as a set
-of text seqments that each end with a newline. The newline is part
-of the value.
-
-=item B<-window>
-
-=back
-
-Include information about embedded windows in the dump results.
-The value of a window is its Tk pathname, unless the window
-has not been created yet. (It must have a create script.)
-In this case an empty string is returned, and you must query the
-window by its index position to get more information.
-
-=item I<$text>-E<gt>B<edit>( I< option, ?arg, arg ...?> );
-
-This command controls the undo mechanism and the modified flag.
-The exact behavior of the command depends on the option argument
-that follows the edit argument. The following forms of the command
-are currently supported:
-
-=over 4
-
-=item I<$text>-E<gt>B<editModified>( ?boolean? );
-
-If boolean is not specified, returns the modified flag of
-the widget. The insert, delete, edit undo and edit redo
-commands or the user can set or clear the modified flag.
-If boolean is specified, sets the modified flag of the
-widget to boolean.
-
-=item I<$text>-E<gt>B<editRedo>;
-
-(Not implemented, use B<TextUndo>.) When the B<-undo> option is true,
-reapplies the last undone edits provided no other edits were done
-since then. Generates an error when the redo stack is empty. Does
-nothing when the B<-undo> option is false.
-
-=item I<$text>-E<gt>B<editReset>;
-
-(Not implemented, use B<TextUndo>.) Clears the undo and redo stacks.
-
-=item I<$text>-E<gt>B<editSeparator>;
-
-(Not implemented, use B<TextUndo>.) Inserts a separator (boundary) on
-the undo stack. Does nothing when the -undo option is false.
-
-=item I<$text>-E<gt>B<editUndo>;
-
-(Not implemented, use B<TextUndo>.) Undoes the last edit action when
-the -undo option is true. An edit action is defined as all the insert
-and delete commands that are recorded on the undo stack in between two
-separators. Generates an error when the undo stack is empty. Does
-nothing when the -undo option is false.
-
-=back
-
-=item I<$text>-E<gt>B<FindAll>(I<mode, case, pattern>)
-
-Removes any current selections and then performs a global text
-search. All matches are tagged with the B<sel> tag.
-
-I<mode> can be be B<-exact> or B<-regexp>. See the B<search> command
-for more information
-
-I<case> can be B<-nocase> or B<-case>. See the B<search> command
-for more information
-
-I<pattern> is an exact string to match if I<mode> is B<-exact> or a
-regular expression if the match I<mode> is B<-regexp>.
-
-
-=item I<$text>-E<gt>B<FindAndReplaceAll>(I<mode, case, find, replace>)
-
-Same as the B<FindAll> method, however additionally substitutes the
-matched text with the characters I<replace>.
-
-=item I<$text>-E<gt>B<FindAndReplacePopUp>
-
-Creates a find-and-replace popup window if one does not already exist.
-If there is currently selected text, then the 'find' field will be
-'pre-filled' with the selection.
-
-=item I<$text>-E<gt>B<FindNext>(I<direction, mode, case, pattern>)
-
-Removes any current selections and then performs a forward or reverse
-text search. All matches are tagged with the B<sel> tag. I<direction>
-can be B<-forwards> or B<-backwards>. I<mode, case> and I<pattern> are
-as for the B<FindAll> method.
-
-=item I<$text>-E<gt>B<FindPopUp>
-
-Creates a find popup, if one does not yet exist. If there is currently
-selected text, then the 'find' field will be 'pre-filled' with the
-selection.
-
-=item I<$text>-E<gt>B<FindSelectionNext>
-
-Gets the currently selected text and removes all selections. It then
-finds the next exact, case-sensitive string that matches in a forward
-direction and selects the text and makes the new selection visible.
-
-=item I<$text>-E<gt>B<FindSelectionPrevious>
-
-Gets the currently selected text and removes all selections. It then
-finds the next exact, case-sensitive string that matches in a reverse
-direction and selects the text and makes the new selection visible.
-
-=item I<$text>-E<gt>B<get>(I<index1, >?I<index2>?)
-
-Return a range of characters from the text. The return value will be
-all the characters in the text starting with the one whose index is
-I<index1> and ending just before the one whose index is I<index2> (the
-character at I<index2> will not be returned). If I<index2> is omitted
-then the single character at I<index1> is returned. If there are no
-characters in the specified range (e.g. I<index1> is past the end of
-the file or I<index2> is less than or equal to I<index1>) then an
-empty string is returned. If the specified range contains embedded
-windows, no information about them is included in the returned string.
-If multiple index pairs are given, multiple ranges of text will be
-returned in a list. Invalid ranges will not be represented with empty
-strings in the list. The ranges are returned in the order passed to
-B<get>.
-
-=item I<$text>-E<gt>B<getSelected>
-
-Return the currently selected text.
-
-=item I<$text>-E<gt>B<GetTextTaggedWith>(I<tag>)
-
-Return the text tagged with the I<tag> parameter.
-
-=item I<$text>-E<gt>B<GotoLineNumber>(I<line_number>)
-
-Set the insert mark to I<line_number> and ensures the line is
-visible.
-
-=item I<$text>-E<gt>B<GotoLineNumberPopUp>(I<line_number>)
-
-Displays a popup, pre-filling it with selected numeric text
-(if any), or the line number from B<GotoLineNumber> (if any).
-
-=item I<$text>-E<gt>B<image>(I<option>, ?I<arg, arg, ...>?)
-
-=item I<$text>-E<gt>B<image>I<Option>(?I<arg, arg, ...>?)
-
-This method is used to manipulate embedded images.
-The behavior of the method depends on the I<option> argument
-that follows the B<image> prefix.
-The following forms of the methods are currently supported:
-
-=over 8
-
-=item I<$text>-E<gt>B<imageCget>(I<index, option>)
-
-Returns the value of a configuration option for an embedded image.
-I<Index> identifies the embedded image, and I<option>
-specifies a particular configuration option, which must be one of
-the ones listed in L<"EMBEDDED IMAGES">.
-
-=item I<$text>-E<gt>B<imageConfigure>(I<index, >?I<option, value, ...>?)
-
-Query or modify the configuration options for an embedded image.
-If no I<option> is specified, returns a list describing all of
-the available options for the embedded image at I<index>
-(see L<Tk::options> for information on the format of this list).
-If I<option> is specified with no I<value>, then the command
-returns a list describing the one named option (this list will be
-identical to the corresponding sublist of the value returned if no
-I<option> is specified).
-If one or more I<option-value> pairs are specified, then the command
-modifies the given option(s) to have the given value(s); in
-this case the command returns an empty string.
-See L<"EMBEDDED IMAGES"> for information on the options that
-are supported.
-
-=item I<$text>-E<gt>B<imageCreate>(I<index, >?I<option, value, ...>?)
-
-This command creates a new image annotation, which will appear
-in the text at the position given by I<index>.
-Any number of I<option-value> pairs may be specified to
-configure the annotation.
-Returns a unique identifier that may be used as an index to refer to
-this image.
-See L<"EMBEDDED IMAGES"> for information on the options that
-are supported, and a description of the identifier returned.
-
-=item I<$text>-E<gt>B<imageNames>
-
-Returns a list whose elements are the names of all image instances currently
-embedded in $text.
-
-=back
-
-=item I<$text>-E<gt>B<index>(I<index>)
-
-Returns the position corresponding to I<index> in the form
-I<line.char> where I<line> is the line number and I<char>
-is the character number.
-I<Index> may have any of the forms described under L<"INDICES"> above.
-
-=item I<$text>-E<gt>B<insert>(I<index, chars, >?I<tagList, chars, tagList, ...>?)
-
-Inserts all of the I<chars> arguments just before the character at
-I<index>.
-If I<index> refers to the end of the text (the character after
-the last newline) then the new text is inserted just before the
-last newline instead.
-If there is a single I<chars> argument and no I<tagList>, then
-the new text will receive any tags that are present on both the
-character before and the character after the insertion point; if a tag
-is present on only one of these characters then it will not be
-applied to the new text.
-If I<tagList> is specified then it consists of a list of
-tag names; the new characters will receive all of the tags in
-this list and no others, regardless of the tags present around
-the insertion point.
-If multiple I<chars>-I<tagList> argument pairs are present,
-they produce the same effect as if a separate B<insert> widget
-command had been issued for each pair, in order.
-The last I<tagList> argument may be omitted.
-
-=item I<$text>-E<gt>B<Insert>(I<string>)
-
-Do NOT confuse this with the lower-case B<insert> method.
-Insert I<string> at the point of the insertion cursor. If there is
-a selection in the text, and it covers the point of the insertion
-cursor, then it deletes the selection before inserting.
-
-=item I<$text>-E<gt>B<InsertKeypress>(I<character>)
-
-Inserts I<character> at the B<insert> mark. If in overstrike mode,
-it firsts deletes the character at the B<insert> mark.
-
-=item I<$text>-E<gt>B<InsertSelection>
-
-Inserts the current selection at the B<insert> mark.
-
-=item I<$text>-E<gt>B<insertTab>
-
-Inserts a tab (\t) character at the B<insert> mark.
-
-=item I<$text>-E<gt>B<mark>(I<option, >?I<arg, arg, ...>?)
-
-This command is used to manipulate marks. The exact behavior of
-the command depends on the I<option> argument that follows
-the B<mark> argument. The following forms of the command
-are currently supported:
-
-=over 8
-
-=item I<$text>-E<gt>B<markGravity>(I<markName, >?I<direction>?)
-
-If I<direction> is not specified, returns B<left> or B<right>
-to indicate which of its adjacent characters I<markName> is attached
-to.
-If I<direction> is specified, it must be B<left> or B<right>;
-the gravity of I<markName> is set to the given value.
-
-=item I<$text>-E<gt>B<markNames>
-
-Returns a list whose elements are the names of all the marks that
-are currently set.
-
-=item I<$text>-E<gt>B<markNext>(I<index>)
-
-Returns the name of the next mark at or after I<index>.
-If I<index> is specified in numerical form, then the search for
-the next mark begins at that index.
-If I<index> is the name of a mark, then the search for
-the next mark begins immediately after that mark.
-This can still return a mark at the same position if
-there are multiple marks at the same index.
-These semantics mean that the B<mark next> operation can be used to
-step through all the marks in a text widget in the same order
-as the mark information returned by the B<dump> operation.
-If a mark has been set to the special B<end> index,
-then it appears to be I<after> B<end> with respect to the B<mark next> operation.
-An empty string is returned if there are no marks after I<index>.
-
-=item I<$text>-E<gt>B<markPrevious>(I<index>)
-
-Returns the name of the mark at or before I<index>.
-If I<index> is specified in numerical form, then the search for
-the previous mark begins with the character just before that index.
-If I<index> is the name of a mark, then the search for
-the next mark begins immediately before that mark.
-This can still return a mark at the same position if
-there are multiple marks at the same index.
-These semantics mean that the B<mark previous> operation can be used to
-step through all the marks in a text widget in the reverse order
-as the mark information returned by the B<dump> operation.
-An empty string is returned if there are no marks before I<index>.
-
-=item I<$text>-E<gt>B<markSet>(I<markName, index>)
-
-Sets the mark named I<markName> to a position just before the
-character at I<index>.
-If I<markName> already exists, it is moved from its old position;
-if it doesn't exist, a new mark is created.
-This command returns an empty string.
-
-=item I<$text>-E<gt>B<markUnset>(I<markName>?, I<markName, markName, ...>?)
-
-Remove the mark corresponding to each of the I<markName> arguments.
-The removed marks will not be usable in indices and will not be
-returned by future calls to ``I<$text>-E<gt>B<markNames>''.
-This command returns an empty string.
-
-=back
-
-=item I<$text>-E<gt>B<markExists>(I<markname>)
-
-Returns true if I<markname> exists - false otherwise.
-
-=item I<$text>-E<gt>B<menu>(I<?menu?>)
-
-If I<menu> reference is given as an argument, then the text widget
-menu is adjusted to use this new I<menu>. If the I<menu> argument
-is B<undef>, then this command disables the current text widget menu.
-If the I<menu> argument is omitted altogether, then the current text
-widget menu reference is returned.
-
-=item I<$text>-E<gt>B<openLine>
-
-Inserts a newline (\n) at the insert mark.
-
-=item I<$text>-E<gt>B<OverstrikeMode>(I<?boolean?>)
-
-Returns the overstrike mode if I<boolean> is omitted or sets the
-overstrike mode to I<boolean>. True means overstrike mode is enabled.
-
-=item I<$text>-E<gt>B<PostPopupMenu>(I<x,y>)
-
-Creates a popup menu at the specified (I<x,y>) pixel coordinates. The
-default menu has File, Edit, Search and View menu items which cascade
-to sub-menus for further commands. There is an implicit E<lt>Button-3E<gt>
-binding to this method that posts the menu over the cursor.
-
-=item I<$text>-E<gt>B<ResetAnchor>
-
-Sets the selection anchor to whichever end is farthest from the index
-argument.
-
-=item I<$text>-E<gt>B<scan>(I<option>, I<args>) or
-
-=item I<$text>-E<gt>B<scan>I<option>(I<args>)
-
-This method is used to implement scanning on texts. It has
-two forms, depending on I<option>:
-
-=over 8
-
-=item I<$text>-E<gt>B<scanMark>(I<x, y>)
-
-Records I<x> and I<y> and the current view in the text window,
-for use in conjunction with later B<scanDragto> method.
-Typically this method is associated with a mouse button press in
-the widget. It returns an empty string.
-
-=item I<$text>-E<gt>B<scanDragto>(I<x, y>)
-
-This command computes the difference between its I<x> and I<y>
-arguments and the I<x> and I<y> arguments to the last
-B<scanMark> method for the widget.
-It then adjusts the view by 10 times the difference in coordinates.
-This command is typically associated
-with mouse motion events in the widget, to produce the effect of
-dragging the text at high speed through the window. The return
-value is an empty string.
-
-=back
-
-=item I<$text>-E<gt>B<search>(?I<switches>,? I<pattern, index, >?I<stopIndex>?)
-
-Searches the text in I<$text> starting at I<index> for a range
-of characters that matches I<pattern>.
-If a match is found, the index of the first character in the match is
-returned as result; otherwise an empty string is returned.
-One or more of the following switches (or abbreviations thereof)
-may be specified to control the search:
-
-=over 8
-
-=item B<-forwards>
-
-The search will proceed forward through the text, finding the first
-matching range starting at or after the position given by I<index>.
-This is the default.
-
-=item B<-backwards>
-
-The search will proceed backward through the text, finding the
-matching range closest to I<index> whose first character
-is before I<index>.
-
-=item B<-exact>
-
-Use exact matching: the characters in the matching range must be
-identical to those in I<pattern>.
-This is the default.
-
-=item B<-regexp>
-
-Treat I<pattern> as a regular expression and match it against
-the text using the rules for regular expressions (see the B<regexp>
-command for details).
-
-=item B<-nocase>
-
-Ignore case differences between the pattern and the text.
-
-=item B<-count>I< varName>
-
-The argument following B<-count> gives the name of a variable;
-if a match is found, the number of characters in the matching
-range will be stored in the variable.
-
-=item B<-hidden>
-
-Find hidden text as well. By default only displayed text is found.
-
-=item B<-->
-
-This switch has no effect except to terminate the list of switches:
-the next argument will be treated as I<pattern> even if it starts
-with B<->.
-
-=back
-
-=back
-
-The matching range must be entirely within a single line of text.
-For regular expression matching the newlines are removed from the ends
-of the lines before matching: use the B<$> feature in regular
-expressions to match the end of a line.
-For exact matching the newlines are retained.
-If I<stopIndex> is specified, the search stops at that index:
-for forward searches, no match at or after I<stopIndex> will
-be considered; for backward searches, no match earlier in the
-text than I<stopIndex> will be considered.
-If I<stopIndex> is omitted, the entire text will be searched:
-when the beginning or end of the text is reached, the search
-continues at the other end until the starting location is reached
-again; if I<stopIndex> is specified, no wrap-around will occur.
-
-=over 4
-
-=item I<$text>-E<gt>B<see>(I<index>)
-
-Adjusts the view in the window so that the character given by I<index>
-is completely visible.
-If I<index> is already visible then the command does nothing.
-If I<index> is a short distance out of view, the command
-adjusts the view just enough to make I<index> visible at the
-edge of the window.
-If I<index> is far out of view, then the command centers
-I<index> in the window.
-
-=item I<$text>-E<gt>B<selectAll>
-
-Selects all the text in the widget.
-
-=item I<$text>-E<gt>B<selectLine>
-
-Selects the line with the insert mark.
-
-=item I<$text>-E<gt>B<selectWord>
-
-Selects the word with the insert mark.
-
-=item I<$text>-E<gt>B<SetCursor>(I<position>)
-
-Moves the insert mark to I<position>.
-
-=item I<$text>-E<gt>B<tag>(I<option, >?I<arg, arg, ...>?)
-
-This command is used to manipulate tags. The exact behavior of the
-command depends on the I<option> argument that follows the
-B<tag> argument. The following forms of the command are currently
-supported:
-
-=over 8
-
-=item I<$text>-E<gt>B<tagAdd>(I<tagName, index1, >?I<index2, index1, index2, ...>?)
-
-Associate the tag I<tagName> with all of the characters starting
-with I<index1> and ending just before
-I<index2> (the character at I<index2> isn't tagged).
-A single command may contain any number of I<index1>-I<index2>
-pairs.
-If the last I<index2> is omitted then the single character at
-I<index1> is tagged.
-If there are no characters in the specified range (e.g. I<index1>
-is past the end of the file or I<index2> is less than or equal
-to I<index1>) then the command has no effect.
-
-=item I<$text>-E<gt>B<tagBind>(I<tagName, >?I<sequence>?, ?I<script>?)
-
-This command associates I<script> with the tag given by
-I<tagName>.
-Whenever the event sequence given by I<sequence> occurs for a
-character that has been tagged with I<tagName>,
-the script will be invoked.
-This method is similar to the B<bind> command except that
-it operates on characters in a text rather than entire widgets.
-See the L<Tk::bind> documentation for complete details
-on the syntax of I<sequence> and the substitutions performed
-on I<script> before invoking it.
-If all arguments are specified then a new binding is created, replacing
-any existing binding for the same I<sequence> and I<tagName>
-(if the first character of I<script> is ``+'' then I<script>
-augments an existing binding rather than replacing it).
-In this case the return value is an empty string.
-If I<script> is omitted then the command returns the I<script>
-associated with I<tagName> and I<sequence> (an error occurs
-if there is no such binding).
-If both I<script> and I<sequence> are omitted then the command
-returns a list of all the sequences for which bindings have been
-defined for I<tagName>.
-
-The only events for which bindings may be specified are those related
-to the mouse and keyboard (such as B<Enter>, B<Leave>,
-B<ButtonPress>, B<Motion>, and B<KeyPress>) or virtual events.
-Event bindings for a text widget use the B<current> mark described
-under L<"MARKS"> above. An B<Enter> event triggers for a tag when the tag
-first becomes present on the current character, and a B<Leave> event
-triggers for a tag when it ceases to be present on the current character.
-B<Enter> and B<Leave> events can happen either because the
-B<current> mark moved or because the character at that position
-changed. Note that these events are different than B<Enter> and
-B<Leave> events for windows. Mouse and keyboard events are directed
-to the current character. If a virtual event is used in a binding, that
-binding can trigger only if the virtual event is defined by an underlying
-mouse-related or keyboard-related event.
-
-It is possible for the current character to have multiple tags,
-and for each of them to have a binding for a particular event
-sequence.
-When this occurs, one binding is invoked for each tag, in order
-from lowest-priority to highest priority.
-If there are multiple matching bindings for a single tag, then
-the most specific binding is chosen (see the the documentation for
-the B<bind> command for details).
-B<continue> and B<break> commands within binding scripts
-are processed in the same way as for bindings created with
-the B<bind> command.
-
-If bindings are created for the widget as a whole using the
-B<bind> command, then those bindings will supplement the
-tag bindings.
-The tag bindings will be invoked first, followed by bindings
-for the window as a whole.
-
-=item I<$text>-E<gt>B<tagCget>(I<tagName, option>)
-
-This command returns the current value of the option named I<option>
-associated with the tag given by I<tagName>.
-I<Option> may have any of the values accepted by the B<tag configure>
-method.
-
-=item I<$text>-E<gt>B<tagConfigure>(I<tagName, >?I<option>?, ?I<value>?, ?I<option, value, ...>?)
-
-This command is similar to the B<configure> method except
-that it modifies options associated with the tag given by I<tagName>
-instead of modifying options for the overall text widget.
-If no I<option> is specified, the command returns a list describing
-all of the available options for I<tagName>
-(see L<Tk::options> for information on the format of this list).
-If I<option> is specified with no I<value>, then the command returns
-a list describing the one named option (this list will be identical to
-the corresponding sublist of the value returned if no I<option>
-is specified).
-If one or more I<option-value> pairs are specified, then the command
-modifies the given option(s) to have the given value(s) in I<tagName>;
-in this case the command returns an empty string.
-See L<"TAGS"> above for details on the options available for tags.
-
-=item I<$text>-E<gt>B<tagDelete>(I<tagName, >?I<tagName, ...>?)
-
-Deletes all tag information for each of the I<tagName>
-arguments.
-The command removes the tags from all characters in the file
-and also deletes any other information associated with the tags,
-such as bindings and display information.
-The command returns an empty string.
-
-=item I<$text>-E<gt>B<tagLower>(I<tagName>?, I<belowThis>?)
-
-Changes the priority of tag I<tagName> so that it is just lower
-in priority than the tag whose name is I<belowThis>.
-If I<belowThis> is omitted, then I<tagName>'s priority
-is changed to make it lowest priority of all tags.
-
-=item I<$text>-E<gt>B<tagNames>(?I<index>?)
-
-Returns a list whose elements are the names of all the tags that
-are active at the character position given by I<index>.
-If I<index> is omitted, then the return value will describe
-all of the tags that exist for the text (this includes all tags
-that have been named in a ``I<$text>-E<gt>B<tag>'' widget
-command but haven't been deleted by a ``I<$text>-E<gt>B<tagDelete>''
-method, even if no characters are currently marked with
-the tag).
-The list will be sorted in order from lowest priority to highest
-priority.
-
-=item I<$text>-E<gt>B<tagNextrange>(I<tagName, index1, >?I<index2>?)
-
-This command searches the text for a range of characters tagged
-with I<tagName> where the first character of the range is
-no earlier than the character at I<index1> and no later than
-the character just before I<index2> (a range starting at
-I<index2> will not be considered).
-If several matching ranges exist, the first one is chosen.
-The command's return value is a list containing
-two elements, which are the index of the first character of the
-range and the index of the character just after the last one in
-the range.
-If no matching range is found then the return value is an
-empty string.
-If I<index2> is not given then it defaults to the end of the text.
-
-=item I<$text>-E<gt>B<tagPrevrange>(I<tagName, index1, >?I<index2>?)
-
-This command searches the text for a range of characters tagged
-with I<tagName> where the first character of the range is
-before the character at I<index1> and no earlier than
-the character at I<index2> (a range starting at
-I<index2> will be considered).
-If several matching ranges exist, the one closest to I<index1> is chosen.
-The command's return value is a list containing
-two elements, which are the index of the first character of the
-range and the index of the character just after the last one in
-the range.
-If no matching range is found then the return value is an
-empty string.
-If I<index2> is not given then it defaults to the beginning of the text.
-
-=item I<$text>-E<gt>B<tagRaise>(I<tagName, >?I<aboveThis>?)
-
-Changes the priority of tag I<tagName> so that it is just higher
-in priority than the tag whose name is I<aboveThis>.
-If I<aboveThis> is omitted, then I<tagName>'s priority
-is changed to make it highest priority of all tags.
-
-=item I<$text>-E<gt>B<tagRanges>(I<tagName>)
-
-Returns a list describing all of the ranges of text that have been
-tagged with I<tagName>.
-The first two elements of the list describe the first tagged range
-in the text, the next two elements describe the second range, and
-so on.
-The first element of each pair contains the index of the first
-character of the range, and the second element of the pair contains
-the index of the character just after the last one in the
-range.
-If there are no characters tagged with I<tag> then an
-empty string is returned.
-
-=item I<$text>-E<gt>B<tagRemove>(I<tagName, index1, >?I<index2, index1, index2, ...>?)
-
-Remove the tag I<tagName> from all of the characters starting
-at I<index1> and ending just before
-I<index2> (the character at I<index2> isn't affected).
-A single command may contain any number of I<index1>-I<index2>
-pairs.
-If the last I<index2> is omitted then the single character at
-I<index1> is tagged.
-If there are no characters in the specified range (e.g. I<index1>
-is past the end of the file or I<index2> is less than or equal
-to I<index1>) then the command has no effect.
-This command returns an empty string.
-
-=back
-
-=item I<$text>-E<gt>B<ToggleInsertMode>
-
-Toggles the current overstrike mode.
-
-=item I<$text>-E<gt>B<unselectAll>
-
-Unselects all the text in the widget.
-
-=item I<$text>-E<gt>B<WhatLineNumberPopup>
-
-Creates a popup that displays the current line number of the
-insert mark.
-
-=item I<$text>->B<widget>(I<option?, arg, arg, ...>?)
-
-=item I<$text>->B<widget>I<Option>(?I<arg, arg, ...>?)
-
-This method is used to manipulate embedded windows.
-The behavior of the method depends on the I<option> argument
-that follows the B<window> argument.
-The following forms of the method are currently supported:
-
-=over 8
-
-=item I<$text>->B<windowCget>(I<index, option>)
-
-Returns the value of a configuration option for an embedded window.
-I<Index> identifies the embedded window, and I<option>
-specifies a particular configuration option, which must be one of
-the ones listed in L<"EMBEDDED WINDOWS"> above.
-
-=item I<$text>->B<windowConfigure>(I<index>?, I<option, value, ...>?)
-
-Query or modify the configuration options for an embedded window.
-If no I<option> is specified, returns a list describing all of
-the available options for the embedded window at I<index>
-(see L<Tk::options> for information on the format of this list).
-If I<option> is specified with no I<value>, then the command
-returns a list describing the one named option (this list will be
-identical to the corresponding sublist of the value returned if no
-I<option> is specified).
-If one or more I<option-value> pairs are specified, then the command
-modifies the given option(s) to have the given value(s); in
-this case the command returns an empty string.
-See L<"EMBEDDED WINDOWS"> above for information on the options that
-are supported.
-
-=item I<$text>->B<windowCreate>(I<index>?, I<option, value, ...>?)
-
-This command creates a new window annotation, which will appear
-in the text at the position given by I<index>.
-Any number of I<option-value> pairs may be specified to
-configure the annotation.
-See L<"EMBEDDED WINDOWS"> above for information on the options that
-are supported.
-Returns an empty string.
-
-=item I<$text>->B<windowNames>
-
-Returns a list whose elements are the names of all windows currently
-embedded in $text.
-
-=back
-
-=item I<$text>->B<xview>(I<option, args>)
-
-This command is used to query and change the horizontal position of the
-text in the widget's window. It can take any of the following
-forms:
-
-=over 8
-
-=item I<$text>->B<xview>
-
-Returns a list containing two elements.
-Each element is a real fraction between 0 and 1; together they describe
-the portion of the document's horizontal span that is visible in
-the window.
-For example, if the first element is .2 and the second element is .6,
-20% of the text is off-screen to the left, the middle 40% is visible
-in the window, and 40% of the text is off-screen to the right.
-The fractions refer only to the lines that are actually visible in the
-window: if the lines in the window are all very short, so that they
-are entirely visible, the returned fractions will be 0 and 1,
-even if there are other lines in the text that are
-much wider than the window.
-These are the same values passed to scrollbars via the B<-xscrollcommand>
-option.
-
-=item I<$text>-E<gt>B<xviewMoveto>(I<fraction>)
-
-Adjusts the view in the window so that I<fraction> of the horizontal
-span of the text is off-screen to the left.
-I<Fraction> is a fraction between 0 and 1.
-
-=item I<$text>-E<gt>B<xviewScroll>(I<number, what>)
-
-This command shifts the view in the window left or right according to
-I<number> and I<what>.
-I<Number> must be an integer.
-I<What> must be either B<units> or B<pages> or an abbreviation
-of one of these.
-If I<what> is B<units>, the view adjusts left or right by
-I<number> average-width characters on the display; if it is
-B<pages> then the view adjusts by I<number> screenfuls.
-If I<number> is negative then characters farther to the left
-become visible; if it is positive then characters farther to the right
-become visible.
-
-=back
-
-=item I<$text>-E<gt>B<yview>(I<?args>?)
-
-This command is used to query and change the vertical position of the
-text in the widget's window.
-It can take any of the following forms:
-
-=over 8
-
-=item I<$text>-E<gt>B<yview>
-
-Returns a list containing two elements, both of which are real fractions
-between 0 and 1.
-The first element gives the position of the first character in the
-top line in the window, relative to the text as a whole (0.5 means
-it is halfway through the text, for example).
-The second element gives the position of the character just after
-the last one in the bottom line of the window,
-relative to the text as a whole.
-These are the same values passed to scrollbars via the B<-yscrollcommand>
-option.
-
-=item I<$text>-E<gt>B<yviewMoveto>(I<fraction>)
-
-Adjusts the view in the window so that the character given by I<fraction>
-appears on the top line of the window.
-I<Fraction> is a fraction between 0 and 1; 0 indicates the first
-character in the text, 0.33 indicates the character one-third the
-way through the text, and so on.
-
-=item I<$text>-E<gt>B<yviewScroll>(I<number, what>)
-
-This command adjust the view in the window up or down according to
-I<number> and I<what>.
-I<Number> must be an integer.
-I<What> must be either B<units> or B<pages>.
-If I<what> is B<units>, the view adjusts up or down by
-I<number> lines on the display; if it is B<pages> then
-the view adjusts by I<number> screenfuls.
-If I<number> is negative then earlier positions in the text
-become visible; if it is positive then later positions in the text
-become visible.
-
-=item I<$text>->B<yview>(?B<-pickplace>,? I<index>)
-
-Changes the view in the I<$text>'s window to make I<index> visible.
-If the B<-pickplace> option isn't specified then I<index> will
-appear at the top of the window.
-If B<-pickplace> is specified then the widget chooses where
-I<index> appears in the window:
-
-=over 12
-
-=item [1]
-
-If I<index> is already visible somewhere in the window then the
-command does nothing.
-
-=item [2]
-
-If I<index> is only a few lines off-screen above the window then
-it will be positioned at the top of the window.
-
-=item [3]
-
-If I<index> is only a few lines off-screen below the window then
-it will be positioned at the bottom of the window.
-
-=item [4]
-
-Otherwise, I<index> will be centered in the window.
-
-=back
-
-=back
-
-=back
-
-The B<-pickplace> option has been obsoleted by the B<see> widget
-command (B<see> handles both x- and y-motion to make a location
-visible, whereas B<-pickplace> only handles motion in y).
-
-=over 4
-
-=item I<$text>-E<gt>B<yview>(I<number>)
-
-This command makes the first character on the line after
-the one given by I<number> visible at the top of the window.
-I<Number> must be an integer.
-This command used to be used for scrolling, but now it is obsolete.
-
-=back
-
-=head1 BINDINGS
-
-Tk automatically creates class bindings for texts that give them
-the following default behavior.
-In the descriptions below, ``word'' refers to a contiguous group
-of letters, digits, or ``_'' characters, or any single character
-other than these.
-
-=over 4
-
-=item [1]
-
-Clicking mouse button 1 positions the insertion cursor
-just before the character underneath the mouse cursor, sets the
-input focus to this widget, and clears any selection in the widget.
-Dragging with mouse button 1 strokes out a selection between
-the insertion cursor and the character under the mouse.
-
-=item [2]
-
-Double-clicking with mouse button 1 selects the word under the mouse
-and positions the insertion cursor at the beginning of the word.
-Dragging after a double click will stroke out a selection consisting
-of whole words.
-
-=item [3]
-
-Triple-clicking with mouse button 1 selects the line under the mouse
-and positions the insertion cursor at the beginning of the line.
-Dragging after a triple click will stroke out a selection consisting
-of whole lines.
-
-=item [4]
-
-The ends of the selection can be adjusted by dragging with mouse
-button 1 while the Shift key is down; this will adjust the end
-of the selection that was nearest to the mouse cursor when button
-1 was pressed.
-If the button is double-clicked before dragging then the selection
-will be adjusted in units of whole words; if it is triple-clicked
-then the selection will be adjusted in units of whole lines.
-
-=item [5]
-
-Clicking mouse button 1 with the Control key down will reposition the
-insertion cursor without affecting the selection.
-
-=item [6]
-
-If any normal printing characters are typed, they are
-inserted at the point of the insertion cursor.
-
-=item [7]
-
-The view in the widget can be adjusted by dragging with mouse button 2.
-If mouse button 2 is clicked without moving the mouse, the selection
-is copied into the text at the position of the mouse cursor.
-The Insert key also inserts the selection, but at the position of
-the insertion cursor.
-
-=item [8]
-
-If the mouse is dragged out of the widget
-while button 1 is pressed, the entry will automatically scroll to
-make more text visible (if there is more text off-screen on the side
-where the mouse left the window).
-
-=item [9]
-
-The Left and Right keys move the insertion cursor one character to the
-left or right; they also clear any selection in the text.
-If Left or Right is typed with the Shift key down, then the insertion
-cursor moves and the selection is extended to include the new character.
-Control-Left and Control-Right move the insertion cursor by words, and
-Control-Shift-Left and Control-Shift-Right move the insertion cursor
-by words and also extend the selection.
-Control-b and Control-f behave the same as Left and Right, respectively.
-Meta-b and Meta-f behave the same as Control-Left and Control-Right,
-respectively.
-
-=item [10]
-
-The Up and Down keys move the insertion cursor one line up or
-down and clear any selection in the text.
-If Up or Right is typed with the Shift key down, then the insertion
-cursor moves and the selection is extended to include the new character.
-Control-Up and Control-Down move the insertion cursor by paragraphs (groups
-of lines separated by blank lines), and
-Control-Shift-Up and Control-Shift-Down move the insertion cursor
-by paragraphs and also extend the selection.
-Control-p and Control-n behave the same as Up and Down, respectively.
-
-=item [11]
-
-The Next and Prior keys move the insertion cursor forward or backwards
-by one screenful and clear any selection in the text.
-If the Shift key is held down while Next or Prior is typed, then
-the selection is extended to include the new character.
-Control-v moves the view down one screenful without moving the
-insertion cursor or adjusting the selection.
-
-=item [12]
-
-Control-Next and Control-Prior scroll the view right or left by one page
-without moving the insertion cursor or affecting the selection.
-
-=item [13]
-
-Home and Control-a move the insertion cursor to the
-beginning of its line and clear any selection in the widget.
-Shift-Home moves the insertion cursor to the beginning of the line
-and also extends the selection to that point.
-
-=item [14]
-
-End and Control-e move the insertion cursor to the
-end of the line and clear any selection in the widget.
-Shift-End moves the cursor to the end of the line and extends the selection
-to that point.
-
-=item [15]
-
-Control-Home and Meta-E<lt> move the insertion cursor to the beginning of
-the text and clear any selection in the widget.
-Control-Shift-Home moves the insertion cursor to the beginning of the text
-and also extends the selection to that point.
-
-=item [16]
-
-Control-End and Meta-E<gt> move the insertion cursor to the end of the
-text and clear any selection in the widget.
-Control-Shift-End moves the cursor to the end of the text and extends
-the selection to that point.
-
-=item [17]
-
-The Select key and Control-Space set the selection anchor to the position
-of the insertion cursor. They don't affect the current selection.
-Shift-Select and Control-Shift-Space adjust the selection to the
-current position of the insertion cursor, selecting from the anchor
-to the insertion cursor if there was not any selection previously.
-
-=item [18]
-
-Control-/ selects the entire contents of the widget.
-
-=item [19]
-
-Control-\ clears any selection in the widget.
-
-=item [20]
-
-The F16 key (labelled Copy on many Sun workstations) or Meta-w
-copies the selection in the widget to the clipboard, if there is a selection.
-
-=item [21]
-
-The F20 key (labelled Cut on many Sun workstations) or Control-w
-copies the selection in the widget to the clipboard and deletes
-the selection.
-If there is no selection in the widget then these keys have no effect.
-
-=item [22]
-
-The F18 key (labelled Paste on many Sun workstations) or Control-y
-inserts the contents of the clipboard at the position of the
-insertion cursor.
-
-=item [23]
-
-The Delete key deletes the selection, if there is one in the widget.
-If there is no selection, it deletes the character to the right of
-the insertion cursor.
-
-=item [24]
-
-Backspace and Control-h delete the selection, if there is one
-in the widget.
-If there is no selection, they delete the character to the left of
-the insertion cursor.
-
-=item [25]
-
-Control-d deletes the character to the right of the insertion cursor.
-
-=item [26]
-
-Meta-d deletes the word to the right of the insertion cursor.
-
-=item [27]
-
-Control-k deletes from the insertion cursor to the end of its line;
-if the insertion cursor is already at the end of a line, then
-Control-k deletes the newline character.
-
-=item [28]
-
-Control-o opens a new line by inserting a newline character in
-front of the insertion cursor without moving the insertion cursor.
-
-=item [29]
-
-Meta-backspace and Meta-Delete delete the word to the left of the
-insertion cursor.
-
-=item [30]
-
-Control-x deletes whatever is selected in the text widget.
-
-=item [31]
-
-Control-t reverses the order of the two characters to the right of
-the insertion cursor.
-
-=item [32]
-
-Control-z (and Control-underscore on UNIX when tk_strictMotif is
-true) undoes the last edit action if the -undo option is true.
-Does nothing otherwise.
-
-=item [33]
-
-Control-Z (or Control-y on Windows) reapplies the last undone edit
-action if the -undo option is true. Does nothing otherwise.
-
-=back
-
-If the widget is disabled using the B<-state> option, then its
-view can still be adjusted and text can still be selected,
-but no insertion cursor will be displayed and no text modifications will
-take place.
-
-The behavior of texts can be changed by defining new bindings for
-individual widgets or by redefining the class bindings.
-
-
-=head1 TIED INTERFACE
-
-The Perl/Tk Text widget also has built-in TIEHANDLE methods for
-B<print> and B<printf> statements. This means you can print to file
-handles tied to a Text widget, and the tied methods automatically
-insert the print statement's arguments into the Text widget.
-
-For example:
-
- #!/usr/local/bin/perl -w
- use POSIX 'acos';
- use Tk;
- use strict;
-
- my $mw = MainWindow->new;
- my $text = $mw->Text(qw/-width 40 -height 10/)->pack;
-
- tie *STDOUT, ref $text, $text;
-
- print "Hello Text World!\n";
- printf "pi ~= %1.5f", acos(-1.0);
-
- MainLoop;
-
-To tie a scrolled Text widget, use the Subwidget method to get to the
-E<quot>realE<quot> widget:
-
- my $text = $mw->Scrolled('Text')->pack;
- tie *STDOUT, 'Tk::Text', $text->Subwidget('scrolled');
-
-=head1 PERFORMANCE ISSUES
-
-Text widgets should run efficiently under a variety
-of conditions. The text widget uses about 2-3 bytes of
-main memory for each byte of text, so texts containing a megabyte
-or more should be practical on most workstations.
-Text is represented internally with a modified B-tree structure
-that makes operations relatively efficient even with large texts.
-Tags are included in the B-tree structure in a way that allows
-tags to span large ranges or have many disjoint smaller ranges
-without loss of efficiency.
-Marks are also implemented in a way that allows large numbers of
-marks.
-In most cases it is fine to have large numbers of unique tags,
-or a tag that has many distinct ranges.
-
-One performance problem can arise if you have hundreds or thousands
-of different tags that all have the following characteristics:
-the first and last ranges of each tag are near the beginning and
-end of the text, respectively,
-or a single tag range covers most of the text widget.
-The cost of adding and deleting tags like this is proportional
-to the number of other tags with the same properties.
-In contrast, there is no problem with having thousands of distinct
-tags if their overall ranges are localized and spread uniformly throughout
-the text.
-
-Very long text lines can be expensive,
-especially if they have many marks and tags within them.
-
-The display line with the insert cursor is redrawn each time the
-cursor blinks, which causes a steady stream of graphics traffic.
-Set the B<-insertofftime> option to 0 avoid this.
-
-=head1 SEE ALSO
-
-L<Tk::ROText|Tk::ROText>
-L<Tk::TextUndo|Tk::TextUndo>
-
-=head1 KEYWORDS
-
-text, widget
-
-=cut
-
-