diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Text.pod')
| -rw-r--r-- | Master/tlpkg/tlperl/lib/Tk/Text.pod | 2220 |
1 files changed, 2220 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/Text.pod b/Master/tlpkg/tlperl/lib/Tk/Text.pod new file mode 100644 index 00000000000..3f266979ed3 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Text.pod @@ -0,0 +1,2220 @@ +# 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 + +B<text> $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 + + |