Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Text(3)		      User Contributed Perl Documentation	       Text(3)

NAME
       Tk::Text	- Create and manipulate	Text widgets

SYNOPSIS
       $text = $parent->Text(?options?);

       -background    -highlightbackground     -insertontime  -selectborderwidth
       -borderwidth   -highlightcolor	  -insertwidth	 -selectforeground
       -cursor	 -highlightthickness -padx     -setgrid
       -exportselection	   -insertbackground   -pady	 -takefocus
       -font	 -insertborderwidth  -relief   -xscrollcommand
       -foreground    -insertofftime -selectbackground	 -yscrollcommand

WIDGET-SPECIFIC	OPTIONS
       Name:	 height
       Class:	 Height
       Switch:	 -height
	   Specifies the desired height	for the	window,	in units of characters
	   in the font given by	the -font option.  Must	be at least one.

       Name:	 spacing1
       Class:	 Spacing1
       Switch:	 -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	-spacing1 options in tags.

       Name:	 spacing2
       Class:	 Spacing2
       Switch:	 -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	-spacing2 options in tags.

       Name:	 spacing3
       Class:	 Spacing3
       Switch:	 -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	-spacing3 options in tags.

       Name:	 state
       Class:	 State
       Switch:	 -state
	   Specifies one of two	states for the text:  normal or	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.

       Name:	 tabs
       Class:	 Tabs
       Switch:	 -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 left, right, center, or
	   numeric, which specifies how	to justify text	relative to the	tab
	   stop.  Left is the default; it causes the text following the	tab
	   character to	be positioned with its left edge at the	tab position.
	   Right means that the	right edge of the text following the tab
	   character is	positioned at the tab position,	and center means that
	   the text is centered	at the tab position.  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, -tabs => [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	tabs option may	be overridden by -tabs options in
	   tags.  If no	-tabs option is	specified, or if it is specified as an
	   empty list, then Tk uses default tabs spaced	every eight (average
	   size) characters.

       Name:	 width
       Class:	 Width
       Switch:	 -width
	   Specifies the desired width for the window in units of characters
	   in the font given by	the -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.

       Name:	 wrap
       Class:	 Wrap
       Switch:	 -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
	   none	or char	or word.  A wrap mode of 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 char mode a
	   screen line break may occur after any character; in word mode a
	   line	break will only	be made	at word	boundaries.

DESCRIPTION
       The 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 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, perl/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	"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 "MARKS" below
       for more	details.

       The third form of annotation allows arbitrary windows to	be embedded in
       a text widget.  See "EMBEDDED WINDOWS" below for	more details.

       The fourth form of annotation allows Tk images to be embedded in	a text
       widget.	See "EMBEDDED IMAGES" below for	more details.

       The Perl/Tk Text	widget does not	support	undo/redo, use the TextUndo
       widget instead.

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 base gives	a starting point and the modifiers adjust the index
       from the	starting point (e.g. move forward or backward one character).
       Every index must	contain	a base,	but the	modifiers are optional.

       The base	for an index must have one of the following forms:

       line.char
	   Indicates char'th character on line 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 char is
	   end then it refers to the newline character that ends the line.

       @x,y
	   Indicates the character that	covers the pixel whose x and y
	   coordinates within the text's window	are x and y.

       end Indicates the end of	the text (the character	just after the last
	   newline).

       mark
	   Indicates the character just	after the mark whose name is mark.

       tag.first
	   Indicates the first character in the	text that has been tagged with
	   tag.	 This form generates an	error if no characters are currently
	   tagged with tag.

       tag.last
	   Indicates the character just	after the last one in the text that
	   has been tagged with	tag.  This form	generates an error if no
	   characters are currently tagged with	tag.

       $widget
	   Indicates the position of the embedded window referenced by
	   $widget.  This form generates an error if $widget does not
	   reference to	an embedded window.

       imageName
	   Indicates the position of the embedded image	whose name is
	   imageName.  This form generates an error if there is	no embedded
	   image by the	given name.

       If the base could match more than one of	the above forms, such as a
       mark and	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 chars and wordend may be	abbreviated as long as the
       abbreviation is unambiguous.

       + count chars
	   Adjust the index forward by count characters, moving	to later lines
	   in the text if necessary.  If there are fewer than 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 count are
	   optional.

       - count chars
	   Adjust the index backward by	count characters, moving to earlier
	   lines in the	text if	necessary.  If there are fewer than 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 count
	   are optional.

       + count lines
	   Adjust the index forward by count lines, retaining the same
	   character position within the line.	If there are fewer than	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 count are optional.

       - count lines
	   Adjust the index backward by	count lines, retaining the same
	   character position within the line.	If there are fewer than	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 count are optional.

       linestart
	   Adjust the index to refer to	the first character on the line.

       lineend
	   Adjust the index to refer to	the last character on the line (the
	   newline).

       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.

       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 ``end - 1 chars'' refers to	the
       next-to-last character in the text and ``insert wordstart - 1 c''
       refers to the character just before the first one in the	word
       containing the insertion	cursor.

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),	+, or -: 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 ``$text->tagRaise'' and ``$text->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 background, font,	and foreground options
       for the text widget.  However, display options may be associated	with
       individual tags using the ``$text->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:

       -background => color
	   Color specifies the background color	to use for characters
	   associated with the tag.  It	may have any of	the forms accepted by
	   Tk_GetColor.

       -bgstipple => bitmap
	   Bitmap specifies a bitmap that is used as a stipple pattern for the
	   background.	It may have any	of the forms accepted by Tk_GetBitmap.
	   If bitmap hasn't been specified, or if it is	specified as an	empty
	   string, then	a solid	fill will be used for the background.

       -borderwidth => pixels
	   Pixels specifies the	width of a 3-D border to draw around the
	   background.	It may have any	of the forms accepted by Tk_GetPixels.
	   This	option is used in conjunction with the -relief option to give
	   a 3-D appearance to the background for characters; it is ignored
	   unless the -background option has been set for the tag.

       -elide => 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.

       -data =>	value
	   Allows an arbitrary perl scalar value to be associated with the
	   tag.

       -fgstipple => bitmap
	   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 Tk_GetBitmap.  If bitmap
	   hasn't been specified, or if	it is specified	as an empty string,
	   then	a solid	fill will be used.

       -font =>	fontName
	   FontName is the name	of a font to use for drawing characters.  It
	   may have any	of the forms accepted by Tk_GetFontStruct.

       -foreground => color
	   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 Tk_GetColor.

       -justify	=> justify
	   If the first	character of a display line has	a tag for which	this
	   option has been specified, then justify determines how to justify
	   the line.  It must be one of	left, right, or	center.	 If a line
	   wraps, then the justification for each line on the display is
	   determined by the first character of	that display line.

       -lmargin1 => pixels
	   If the first	character of a text line has a tag for which this
	   option has been specified, then pixels specifies how	much the line
	   should be indented from the left edge of the	window.	 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 -lmargin2 option controls the indentation for
	   subsequent lines.

       -lmargin2 => 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 pixels
	   specifies how much the line should be indented from the left	edge
	   of the window.  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.

       -offset => pixels
	   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.	Pixels may have	any of
	   the standard	forms for screen distances.

       -overstrike => boolean
	   Specifies whether or	not to draw a horizontal rule through the
	   middle of characters.  Boolean may have any of the forms accepted
	   by Tk_GetBoolean.

       -relief => relief
	   Relief specifies the	3-D relief to use for drawing backgrounds, in
	   any of the forms accepted by	Tk_GetRelief.  This option is used in
	   conjunction with the	-borderwidth option to give a 3-D appearance
	   to the background for characters; it	is ignored unless the
	   -background option has been set for the tag.

       -rmargin	=> pixels
	   If the first	character of a display line has	a tag for which	this
	   option has been specified, then pixels specifies how	wide a margin
	   to leave between the	end of the line	and the	right edge of the
	   window.  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.

       -spacing1 => pixels
	   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.

       -spacing2 => pixels
	   For lines that wrap,	this option specifies how much additional
	   space to leave between the display lines for	a single text line.
	   Pixels may have any of the standard forms for screen	distances.

       -spacing3 => pixels
	   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.

       -tabs =>	tabList
	   TabList specifies a set of tab stops	in the same form as for	the
	   -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 -tabs = " ">, then it requests	default	8-character
	   tabs	as described for the tabs widget option.

       -underline => boolean
	   Boolean specifies whether or	not to draw an underline underneath
	   characters.	It may have any	of the forms accepted by
	   Tk_GetBoolean.

       -wrap =>	mode
	   Mode	specifies how to handle	lines that are wider than the text's
	   window.  It has the same legal values as the	-wrap option for the
	   text	widget:	 none, char, or	word.  If this tag option is
	   specified, it overrides the -wrap option for	the text widget.

       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	tagBind	widget
       method below.

       The third use for tags is in managing the selection.  See "THE
       SELECTION" below.

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 ``$text->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 gravity, which is either left or 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	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 insert is
       associated with the insertion cursor, as	described under	"THE INSERTION
       CURSOR" below.  Second, the mark	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:  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.

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 widgetCreate
       method, several configuration options may be associated with it.	 These
       options may be  modified	later with the widgetConfigure method.	The
       following options are currently supported:

       -align => 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.
	   Where must have one of the values top (align	the top	of the window
	   with	the top	of the line), center (center the window	within the
	   range of the	line), bottom (align the bottom	of the window with the
	   bottom of the line's	area), or baseline (align the bottom of	the
	   window with the baseline of the line).

       -create => callback
	   Specifies a callback	that may be evaluated to create	the window for
	   the annotation.  If no -window option has been specified for	the
	   annotation this callback will be evaluated when the annotation is
	   about to be displayed on the	screen.	 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,
	   callback will be evaluated again the	next time the annotation is
	   displayed.

       -padx =>	pixels
	   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 Tk_GetPixels).

       -pady =>	pixels
	   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 Tk_GetPixels).

       -stretch	=> 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 -pady option has been specified as	well,
	   then	the requested padding will be retained even if the window is
	   stretched.

       -window => $widget
	   Specifies the name of a window to display in	the annotation.

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 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 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 -name option (described below).  If	the
       -name option is not provided, the -image	name is	used instead.  If the
       imageName is already in use in the text widget, then #nn	is added to
       the end of the imageName, where nn is an	arbitrary integer.  This
       insures the imageName is	unique.	 Once this name	is assigned to this
       instance	of the image, it does not change, even though the -image or
       -name values can	be changed with	image configure.

       When an embedded	image is added to a text widget	with the imageCreate
       method, several configuration options may be associated with it.	 These
       options may be modified later with the image configure method.  The
       following options are currently supported:

       -align => 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.
	   Where must have one of the values top (align	the top	of the image
	   with	the top	of the line), center (center the image within the
	   range of the	line), bottom (align the bottom	of the image with the
	   bottom of the line's	area), or baseline (align the bottom of	the
	   image with the baseline of the line).

       -image => image
	   Specifies the name of the Tk	image to display in the	annotation.
	   If image is not a valid Tk image, then an error is returned.

       -name =>	ImageName
	   Specifies the name by which this image instance may be referenced
	   in the text widget. If ImageName is not supplied, then the name of
	   the Tk image	is used	instead.  If the imageName is already in use,
	   #nn is appended to the end of the name as described above.

       -padx =>	pixels
	   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.

       -pady =>	pixels
	   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.

THE SELECTION
       Selection support is implemented	via tags.  If the exportSelection
       option for the text widget is true then the sel tag will	be associated
       with the	selection:

       [1] Whenever characters are tagged with sel the text widget will	claim
	   ownership of	the selection.

       [2] Attempts to retrieve	the selection will be serviced by the text
	   widget, returning all the characters	with the sel tag.

       [3] If the selection is claimed away by another application or by
	   another window within this application, then	the sel	tag will be
	   removed from	all characters in the text.

       [4] Whenever the	sel tag	range changes a	virtual	event <<Selection>> is
	   generated.

	   The sel tag is automatically	defined	when a text widget is created,
	   and it may not be deleted with the ``$text->tagDelete'' method.
	   Furthermore,	the selectBackground, selectBorderWidth, and
	   selectForeground options for	the text widget	are tied to the
	   -background,	-borderwidth, and -foreground options for the sel tag:
	   changes in either will automatically	be reflected in	the other.

THE INSERTION CURSOR
       The mark	named 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 ``$text->markUnset'' widget command.  The	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.

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 <<Modified>> virtual event is	gener-
       ated. See the edit modified widget command for more details.

WIDGET METHODS
       The Text	method creates a widget	object.	 This object supports the
       configure and cget methods described in 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	Tk::Widget class.

       The following additional	methods	are available for text widgets.	 In
       addition, the extended text widget methods as documented	in "Mastering
       Perl/Tk"	are included in	this pod (with permission from the publisher,
       O'Reilly	and Associates Inc.).

       $text->adjustSelect
	   Moves the end point of the selection	and anchor point to the	mouse
	   pointer location.

       $text->bbox(index)
	   Returns a list of four elements describing the screen area of the
	   character given by 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.

       $text->clipboardColumnCopy
	   Performs a rectangular copy of the currently	selected text with
	   basic compensation for tab characters.

       $text->clipboardColumnCut
	   Performs a rectangular cut of the currently selected	text with
	   basic compensation for tab characters.

       $text->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.

       $text->compare(index1, op, index2)
	   Compares the	indices	given by index1	and index2 according to	the
	   relational operator given by	op, and	returns	1 if the relationship
	   is satisfied	and 0 if it isn't.  Op must be one of the operators <,
	   <=, ==, >=, >, or !=.  If op	is == then 1 is	returned if the	two
	   indices refer to the	same character,	if op is < then	1 is returned
	   if index1 refers to an earlier character in the text	than index2,
	   and so on.

       $text->Contents(?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.

       $text->debug(?boolean?)
	   If 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 boolean has a false value then
	   the debugging checks	will be	turned off.  In	either case the
	   command returns an empty string.  If	boolean	is not specified then
	   the command returns on or 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.

       $text->delete(index1, ?index2?)
	   Delete a range of characters	from the text.	If both	index1 and
	   index2 are specified, then delete all the characters	starting with
	   the one given by index1 and stopping	just before index2 (i.e. the
	   character at	index2 is not deleted).	 If index2 doesn't specify a
	   position later in the text than index1 then no characters are
	   deleted.  If	index2 isn't specified then the	single character at
	   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.

       $text->deleteSelected
	   Delete the currently	selected text.

       $text->deleteTextTaggedWith(tag)
	   Delete the text tagged with the tag parameter.

       $text->deleteToEndofLine
	   Delete from the insert mark location	to the end of line.

       $text->dlineinfo(index)
	   Returns a list with five elements describing	the area occupied by
	   the display line containing 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 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 index is not	visible	on the screen then the return
	   value is an empty list.

       $text->dump(?switches?, index1, ?index2?)
	   Return the contents of the text widget from index1 up to, but not
	   including index2, including the text	and information	about marks,
	   tags, and embedded windows.	If index2 is not specified, then it
	   defaults to one character past index1.  The information is returned
	   in the following format:

	   key1	value1 index1 key2 value2 index2 ...

	   The possible	key values are text, mark, tagon, tagoff, and $text.
	   The corresponding value is the text,	mark name, tag name, or	window
	   name.  The 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:

	   -all
	       Return information about	all elements: text, marks, tags, and
	       windows.	 This is the default.

	   -command => callback
	       Instead of returning the	information as the result of the dump
	       operation, invoke the callback on each element of the text
	       widget within the range.	 The callback has three	arguments
	       appended	to it before it	is evaluated: the key, value, and
	       index.

	   -mark
	       Include information about marks in the dump results.

	   -tag
	       Include information about tag transitions in the	dump results.
	       Tag information is returned as tagon and	tagoff elements	that
	       indicate	the begin and end of each range	of each	tag,
	       respectively.

	   -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 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.

	   -window

	   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.

       $text->edit(  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:

	   $text->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.

	   $text->editRedo;
	       (Not implemented, use TextUndo.)	 When the -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 -undo option is false.

	   $text->editReset;
	       (Not implemented, use TextUndo.)	Clears the undo	and redo
	       stacks.

	   $text->editSeparator;
	       (Not implemented, use TextUndo.)	Inserts	a separator (boundary)
	       on the undo stack. Does nothing when the	-undo option is	false.

	   $text->editUndo;
	       (Not implemented, use 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.

       $text->FindAll(mode, case, pattern)
	   Removes any current selections and then performs a global text
	   search. All matches are tagged with the sel tag.

	   mode	can be be -exact or -regexp. See the search command for	more
	   information

	   case	can be -nocase or -case. See the search	command	for more
	   information

	   pattern is an exact string to match if mode is -exact or a regular
	   expression if the match mode	is -regexp.

       $text->FindAndReplaceAll(mode, case, find, replace)
	   Same	as the FindAll method, however additionally substitutes	the
	   matched text	with the characters replace.

       $text->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.

       $text->FindNext(direction, mode,	case, pattern)
	   Removes any current selections and then performs a forward or
	   reverse text	search.	All matches are	tagged with the	sel tag.
	   direction can be -forwards or -backwards. mode, case	and pattern
	   are as for the FindAll method.

       $text->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.

       $text->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.

       $text->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.

       $text->get(index1, ?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 index1 and ending	just before the	one whose index	is index2 (the
	   character at	index2 will not	be returned).  If index2 is omitted
	   then	the single character at	index1 is returned.  If	there are no
	   characters in the specified range (e.g. index1 is past the end of
	   the file or index2 is less than or equal to 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 get.

       $text->getSelected
	   Return the currently	selected text.

       $text->GetTextTaggedWith(tag)
	   Return the text tagged with the tag parameter.

       $text->GotoLineNumber(line_number)
	   Set the insert mark to line_number and ensures the line is visible.

       $text->GotoLineNumberPopUp(line_number)
	   Displays a popup, pre-filling it with selected numeric text (if
	   any), or the	line number from GotoLineNumber	(if any).

       $text->image(option, ?arg, arg, ...?)
       $text->imageOption(?arg,	arg, ...?)
	   This	method is used to manipulate embedded images.  The behavior of
	   the method depends on the option argument that follows the image
	   prefix.  The	following forms	of the methods are currently
	   supported:

	   $text->imageCget(index, option)
		   Returns the value of	a configuration	option for an embedded
		   image.  Index identifies the	embedded image,	and option
		   specifies a particular configuration	option,	which must be
		   one of the ones listed in "EMBEDDED IMAGES".

	   $text->imageConfigure(index,	?option, value,	...?)
		   Query or modify the configuration options for an embedded
		   image.  If no option	is specified, returns a	list
		   describing all of the available options for the embedded
		   image at index (see Tk::options for information on the
		   format of this list).  If option is specified with no
		   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 option is
		   specified).	If one or more 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 "EMBEDDED IMAGES" for information on
		   the options that are	supported.

	   $text->imageCreate(index, ?option, value, ...?)
		   This	command	creates	a new image annotation,	which will
		   appear in the text at the position given by index.  Any
		   number of 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 "EMBEDDED
		   IMAGES" for information on the options that are supported,
		   and a description of	the identifier returned.

	   $text->imageNames
		   Returns a list whose	elements are the names of all image
		   instances currently embedded	in $text.

       $text->index(index)
	   Returns the position	corresponding to index in the form line.char
	   where line is the line number and char is the character number.
	   Index may have any of the forms described under "INDICES" above.

       $text->insert(index, chars, ?tagList, chars, tagList, ...?)
	   Inserts all of the chars arguments just before the character	at
	   index.  If 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 chars argument and no
	   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 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
	   chars-tagList argument pairs	are present, they produce the same
	   effect as if	a separate insert widget command had been issued for
	   each	pair, in order.	 The last tagList argument may be omitted.

       $text->Insert(string)
	   Do NOT confuse this with the	lower-case insert method.  Insert
	   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.

       $text->InsertKeypress(character)
	   Inserts character at	the insert mark. If in overstrike mode,	it
	   firsts deletes the character	at the insert mark.

       $text->InsertSelection
	   Inserts the current selection at the	insert mark.

       $text->insertTab
	   Inserts a tab (\t) character	at the insert mark.

       $text->mark(option, ?arg, arg, ...?)
	   This	command	is used	to manipulate marks.  The exact	behavior of
	   the command depends on the option argument that follows the mark
	   argument.  The following forms of the command are currently
	   supported:

	   $text->markGravity(markName,	?direction?)
		   If direction	is not specified, returns left or right	to
		   indicate which of its adjacent characters markName is
		   attached to.	 If direction is specified, it must be left or
		   right; the gravity of markName is set to the	given value.

	   $text->markNames
		   Returns a list whose	elements are the names of all the
		   marks that are currently set.

	   $text->markNext(index)
		   Returns the name of the next	mark at	or after index.	 If
		   index is specified in numerical form, then the search for
		   the next mark begins	at that	index.	If 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 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 dump	operation.  If a mark has been set to
		   the special end index, then it appears to be	after end with
		   respect to the mark next operation.	An empty string	is
		   returned if there are no marks after	index.

	   $text->markPrevious(index)
		   Returns the name of the mark	at or before index.  If	index
		   is specified	in numerical form, then	the search for the
		   previous mark begins	with the character just	before that
		   index.  If 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 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 dump	operation.  An
		   empty string	is returned if there are no marks before
		   index.

	   $text->markSet(markName, index)
		   Sets	the mark named markName	to a position just before the
		   character at	index.	If 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.

	   $text->markUnset(markName?, markName, markName, ...?)
		   Remove the mark corresponding to each of the	markName
		   arguments.  The removed marks will not be usable in indices
		   and will not	be returned by future calls to
		   ``$text->markNames''.  This command returns an empty
		   string.

       $text->markExists(markname)
	   Returns true	if markname exists - false otherwise.

       $text->menu(?menu?)
	   If menu reference is	given as an argument, then the text widget
	   menu	is adjusted to use this	new menu. If the menu argument is
	   undef, then this command disables the current text widget menu.  If
	   the menu argument is	omitted	altogether, then the current text
	   widget menu reference is returned.

       $text->openLine
	   Inserts a newline (\n) at the insert	mark.

       $text->OverstrikeMode(?boolean?)
	   Returns the overstrike mode if boolean is omitted or	sets the
	   overstrike mode to boolean. True means overstrike mode is enabled.

       $text->PostPopupMenu(x,y)
	   Creates a popup menu	at the specified (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
	   <Button-3> binding to this method that posts	the menu over the
	   cursor.

       $text->ResetAnchor
	   Sets	the selection anchor to	whichever end is farthest from the
	   index argument.

       $text->scan(option, args) or
       $text->scanoption(args)
	   This	method is used to implement scanning on	texts.	It has two
	   forms, depending on option:

	   $text->scanMark(x, y)
		   Records x and y and the current view	in the text window,
		   for use in conjunction with later scanDragto	method.
		   Typically this method is associated with a mouse button
		   press in the	widget.	 It returns an empty string.

	   $text->scanDragto(x,	y)
		   This	command	computes the difference	between	its x and y
		   arguments and the x and y arguments to the last 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.

       $text->search(?switches,? pattern, index, ?stopIndex?)
	   Searches the	text in	$text starting at index	for a range of
	   characters that matches 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:

	   -forwards
		   The search will proceed forward through the text, finding
		   the first matching range starting at	or after the position
		   given by index.  This is the	default.

	   -backwards
		   The search will proceed backward through the	text, finding
		   the matching	range closest to index whose first character
		   is before index.

	   -exact  Use exact matching:	the characters in the matching range
		   must	be identical to	those in pattern.  This	is the
		   default.

	   -regexp Treat pattern as a regular expression and match it against
		   the text using the rules for	regular	expressions (see the
		   regexp command for details).

	   -nocase Ignore case differences between the pattern and the text.

	   -count varName
		   The argument	following -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.

	   -hidden Find	hidden text as well. By	default	only displayed text is
		   found.

	   --	   This	switch has no effect except to terminate the list of
		   switches: the next argument will be treated as pattern even
		   if it starts	with -.

       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 $ feature in	regular	expressions to
       match the end of	a line.	 For exact matching the	newlines are retained.
       If stopIndex is specified, the search stops at that index: for forward
       searches, no match at or	after stopIndex	will be	considered;  for
       backward	searches, no match earlier in the text than stopIndex will be
       considered.  If 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
       stopIndex is specified, no wrap-around will occur.

       $text->see(index)
	   Adjusts the view in the window so that the character	given by index
	   is completely visible.  If index is already visible then the
	   command does	nothing.  If index is a	short distance out of view,
	   the command adjusts the view	just enough to make index visible at
	   the edge of the window.  If index is	far out	of view, then the
	   command centers index in the	window.

       $text->selectAll
	   Selects all the text	in the widget.

       $text->selectLine
	   Selects the line with the insert mark.

       $text->selectWord
	   Selects the word with the insert mark.

       $text->SetCursor(position)
	   Moves the insert mark to position.

       $text->tag(option, ?arg,	arg, ...?)
	   This	command	is used	to manipulate tags.  The exact behavior	of the
	   command depends on the option argument that follows the tag
	   argument.  The following forms of the command are currently
	   supported:

	   $text->tagAdd(tagName, index1, ?index2, index1, index2, ...?)
		   Associate the tag tagName with all of the characters
		   starting with index1	and ending just	before index2 (the
		   character at	index2 isn't tagged).  A single	command	may
		   contain any number of index1-index2 pairs.  If the last
		   index2 is omitted then the single character at index1 is
		   tagged.  If there are no characters in the specified	range
		   (e.g. index1	is past	the end	of the file or index2 is less
		   than	or equal to index1) then the command has no effect.

	   $text->tagBind(tagName, ?sequence?, ?script?)
		   This	command	associates script with the tag given by
		   tagName.  Whenever the event	sequence given by sequence
		   occurs for a	character that has been	tagged with tagName,
		   the script will be invoked.	This method is similar to the
		   bind	command	except that it operates	on characters in a
		   text	rather than entire widgets.  See the Tk::bind
		   documentation for complete details on the syntax of
		   sequence and	the substitutions performed on script before
		   invoking it.	 If all	arguments are specified	then a new
		   binding is created, replacing any existing binding for the
		   same	sequence and tagName (if the first character of	script
		   is ``+'' then script	augments an existing binding rather
		   than	replacing it).	In this	case the return	value is an
		   empty string.  If script is omitted then the	command
		   returns the script associated with tagName and sequence (an
		   error occurs	if there is no such binding).  If both script
		   and sequence	are omitted then the command returns a list of
		   all the sequences for which bindings	have been defined for
		   tagName.

		   The only events for which bindings may be specified are
		   those related to the	mouse and keyboard (such as Enter,
		   Leave, ButtonPress, Motion, and KeyPress) or	virtual
		   events.  Event bindings for a text widget use the current
		   mark	described under	"MARKS"	above.	An Enter event
		   triggers for	a tag when the tag first becomes present on
		   the current character, and a	Leave event triggers for a tag
		   when	it ceases to be	present	on the current character.
		   Enter and Leave events can happen either because the
		   current mark	moved or because the character at that
		   position changed.  Note that	these events are different
		   than	Enter and 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 bind command for
		   details).  continue and break commands within binding
		   scripts are processed in the	same way as for	bindings
		   created with	the bind command.

		   If bindings are created for the widget as a whole using the
		   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.

	   $text->tagCget(tagName, option)
		   This	command	returns	the current value of the option	named
		   option associated with the tag given	by tagName.  Option
		   may have any	of the values accepted by the tag configure
		   method.

	   $text->tagConfigure(tagName,	?option?, ?value?, ?option, value,
	   ...?)
		   This	command	is similar to the configure method except that
		   it modifies options associated with the tag given by
		   tagName instead of modifying	options	for the	overall	text
		   widget.  If no option is specified, the command returns a
		   list	describing all of the available	options	for tagName
		   (see	Tk::options for	information on the format of this
		   list).  If option is	specified with no 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 option is specified).  If one
		   or more option-value	pairs are specified, then the command
		   modifies the	given option(s)	to have	the given value(s) in
		   tagName; in this case the command returns an	empty string.
		   See "TAGS" above for	details	on the options available for
		   tags.

	   $text->tagDelete(tagName, ?tagName, ...?)
		   Deletes all tag information for each	of the 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.

	   $text->tagLower(tagName?, belowThis?)
		   Changes the priority	of tag tagName so that it is just
		   lower in priority than the tag whose	name is	belowThis.  If
		   belowThis is	omitted, then tagName's	priority is changed to
		   make	it lowest priority of all tags.

	   $text->tagNames(?index?)
		   Returns a list whose	elements are the names of all the tags
		   that	are active at the character position given by index.
		   If 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 ``$text->tag'' widget
		   command but haven't been deleted by a ``$text->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.

	   $text->tagNextrange(tagName,	index1,	?index2?)
		   This	command	searches the text for a	range of characters
		   tagged with tagName where the first character of the	range
		   is no earlier than the character at index1 and no later
		   than	the character just before index2 (a range starting at
		   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 index2 is not given then	it defaults to the end
		   of the text.

	   $text->tagPrevrange(tagName,	index1,	?index2?)
		   This	command	searches the text for a	range of characters
		   tagged with tagName where the first character of the	range
		   is before the character at index1 and no earlier than the
		   character at	index2 (a range	starting at index2 will	be
		   considered).	 If several matching ranges exist, the one
		   closest to 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
		   index2 is not given then it defaults	to the beginning of
		   the text.

	   $text->tagRaise(tagName, ?aboveThis?)
		   Changes the priority	of tag tagName so that it is just
		   higher in priority than the tag whose name is aboveThis.
		   If aboveThis	is omitted, then tagName's priority is changed
		   to make it highest priority of all tags.

	   $text->tagRanges(tagName)
		   Returns a list describing all of the	ranges of text that
		   have	been tagged with 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	tag then an empty string is returned.

	   $text->tagRemove(tagName, index1, ?index2, index1, index2, ...?)
		   Remove the tag tagName from all of the characters starting
		   at index1 and ending	just before index2 (the	character at
		   index2 isn't	affected).  A single command may contain any
		   number of index1-index2 pairs.  If the last index2 is
		   omitted then	the single character at	index1 is tagged.  If
		   there are no	characters in the specified range (e.g.	index1
		   is past the end of the file or index2 is less than or equal
		   to index1) then the command has no effect.  This command
		   returns an empty string.

       $text->ToggleInsertMode
	   Toggles the current overstrike mode.

       $text->unselectAll
	   Unselects all the text in the widget.

       $text->WhatLineNumberPopup
	   Creates a popup that	displays the current line number of the	insert
	   mark.

       $text->widget(option?, arg, arg,	...?)
       $text->widgetOption(?arg, arg, ...?)
	   This	method is used to manipulate embedded windows.	The behavior
	   of the method depends on the	option argument	that follows the
	   window argument.  The following forms of the	method are currently
	   supported:

	   $text->windowCget(index, option)
		   Returns the value of	a configuration	option for an embedded
		   window.  Index identifies the embedded window, and option
		   specifies a particular configuration	option,	which must be
		   one of the ones listed in "EMBEDDED WINDOWS"	above.

	   $text->windowConfigure(index?, option, value, ...?)
		   Query or modify the configuration options for an embedded
		   window.  If no option is specified, returns a list
		   describing all of the available options for the embedded
		   window at index (see	Tk::options for	information on the
		   format of this list).  If option is specified with no
		   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 option is
		   specified).	If one or more 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 "EMBEDDED WINDOWS" above for
		   information on the options that are supported.

	   $text->windowCreate(index?, option, value, ...?)
		   This	command	creates	a new window annotation, which will
		   appear in the text at the position given by index.  Any
		   number of option-value pairs	may be specified to configure
		   the annotation.  See	"EMBEDDED WINDOWS" above for
		   information on the options that are supported.  Returns an
		   empty string.

	   $text->windowNames
		   Returns a list whose	elements are the names of all windows
		   currently embedded in $text.

       $text->xview(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:

	   $text->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	-xscrollcommand	option.

	   $text->xviewMoveto(fraction)
		   Adjusts the view in the window so that fraction of the
		   horizontal span of the text is off-screen to	the left.
		   Fraction is a fraction between 0 and	1.

	   $text->xviewScroll(number, what)
		   This	command	shifts the view	in the window left or right
		   according to	number and what.  Number must be an integer.
		   What	must be	either units or	pages or an abbreviation of
		   one of these.  If what is units, the	view adjusts left or
		   right by number average-width characters on the display;
		   if it is pages then the view	adjusts	by number screenfuls.
		   If number is	negative then characters farther to the	left
		   become visible;  if it is positive then characters farther
		   to the right	become visible.

       $text->yview(?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:

	   $text->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 -yscrollcommand option.

	   $text->yviewMoveto(fraction)
		   Adjusts the view in the window so that the character	given
		   by fraction appears on the top line of the window.
		   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.

	   $text->yviewScroll(number, what)
		   This	command	adjust the view	in the window up or down
		   according to	number and what.  Number must be an integer.
		   What	must be	either units or	pages.	If what	is units, the
		   view	adjusts	up or down by number lines on the display;  if
		   it is pages then the	view adjusts by	number screenfuls.  If
		   number is negative then earlier positions in	the text
		   become visible;  if it is positive then later positions in
		   the text become visible.

	   $text->yview(?-pickplace,? index)
		   Changes the view in the $text's window to make index
		   visible.  If	the -pickplace option isn't specified then
		   index will appear at	the top	of the window.	If -pickplace
		   is specified	then the widget	chooses	where index appears in
		   the window:

		   [1]	       If index	is already visible somewhere in	the
			       window then the command does nothing.

		   [2]	       If index	is only	a few lines off-screen above
			       the window then it will be positioned at	the
			       top of the window.

		   [3]	       If index	is only	a few lines off-screen below
			       the window then it will be positioned at	the
			       bottom of the window.

		   [4]	       Otherwise, index	will be	centered in the
			       window.

       The -pickplace option has been obsoleted	by the see widget command (see
       handles both x- and y-motion to make a location visible,	whereas
       -pickplace only handles motion in y).

       $text->yview(number)
	   This	command	makes the first	character on the line after the	one
	   given by number visible at the top of the window.  Number must be
	   an integer.	This command used to be	used for scrolling, but	now it
	   is obsolete.

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.

       [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.

       [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.

       [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.

       [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.

       [5] Clicking mouse button 1 with	the Control key	down will reposition
	   the insertion cursor	without	affecting the selection.

       [6] If any normal printing characters are typed,	they are inserted at
	   the point of	the insertion cursor.

       [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.

       [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).

       [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.

       [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.

       [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.

       [12]
	   Control-Next	and Control-Prior scroll the view right	or left	by one
	   page	without	moving the insertion cursor or affecting the
	   selection.

       [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.

       [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.

       [15]
	   Control-Home	and Meta-< 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.

       [16]
	   Control-End and Meta-> 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.

       [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.

       [18]
	   Control-/ selects the entire	contents of the	widget.

       [19]
	   Control-\ clears any	selection in the widget.

       [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.

       [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.

       [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.

       [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.

       [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.

       [25]
	   Control-d deletes the character to the right	of the insertion
	   cursor.

       [26]
	   Meta-d deletes the word to the right	of the insertion cursor.

       [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.

       [28]
	   Control-o opens a new line by inserting a newline character in
	   front of the	insertion cursor without moving	the insertion cursor.

       [29]
	   Meta-backspace and Meta-Delete delete the word to the left of the
	   insertion cursor.

       [30]
	   Control-x deletes whatever is selected in the text widget.

       [31]
	   Control-t reverses the order	of the two characters to the right of
	   the insertion cursor.

       [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.

       [33]
	   Control-Z (or Control-y on Windows) reapplies the last undone edit
	   action if the -undo option is true. Does nothing otherwise.

       If the widget is	disabled using the -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.

TIED INTERFACE
       The Perl/Tk Text	widget also has	built-in TIEHANDLE methods for print
       and 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
       "real" widget:

	my $text = $mw->Scrolled('Text')->pack;
	tie *STDOUT, 'Tk::Text', $text->Subwidget('scrolled');

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
       -insertofftime option to	0 avoid	this.

SEE ALSO
       Tk::ROText Tk::TextUndo

KEYWORDS
       text, widget

perl v5.24.1			  2015-01-31			       Text(3)

NAME | SYNOPSIS | WIDGET-SPECIFIC OPTIONS | DESCRIPTION | INDICES | TAGS | MARKS | EMBEDDED WINDOWS | EMBEDDED IMAGES | THE SELECTION | THE INSERTION CURSOR | THE MODIFIED FLAG | WIDGET METHODS | BINDINGS | TIED INTERFACE | PERFORMANCE ISSUES | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tk::Text&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help