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

FreeBSD Manual Pages

  
 
  

home | help
text(3tk)		     Tk	Built-In Commands		     text(3tk)

______________________________________________________________________________

NAME
       text,  tk_textCopy,  tk_textCut,	 tk_textPaste  - Create	and manipulate
       'text' hypertext	editing	widgets

SYNOPSIS
       text pathName ?options?
       tk_textCopy pathName
       tk_textCut pathName
       tk_textPaste pathName

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

       See the options manual entry for	details	on the standard	options.

WIDGET-SPECIFIC	OPTIONS
       Command-Line Name:-autoseparators
       Database	Name:  autoSeparators
       Database	Class: AutoSeparators

	      Specifies	a boolean that says whether separators	are  automati-
	      cally inserted in	the undo stack.	Only meaningful	when the -undo
	      option is	true.

       Command-Line Name:-blockcursor
       Database	Name:  blockCursor
       Database	Class: BlockCursor

	      Specifies	a boolean that says  whether  the  blinking  insertion
	      cursor  should  be drawn as a character-sized rectangular	block.
	      If false (the default) a thin vertical line is used for the  in-
	      sertion cursor.

       Command-Line Name:-endline
       Database	Name:  endLine
       Database	Class: EndLine

	      Specifies	an integer line	index representing the line of the un-
	      derlying textual data store that should be just after  the  last
	      line  contained  in the widget. This allows a text widget	to re-
	      flect only a portion of a	larger piece of	text.  Instead	of  an
	      integer,	the empty string can be	provided to this configuration
	      option, which will configure the widget to end at	the very  last
	      line in the textual data store.

       Command-Line Name:-height
       Database	Name:  height
       Database	Class: Height

	      Specifies	the desired height for the window, in units of charac-
	      ters in the font given by	the -font option.  Must	 be  at	 least
	      one.

       Command-Line Name:-inactiveselectbackground
       Database	Name:  inactiveSelectBackground
       Database	Class: Foreground

	      Specifies	the colour to use for the selection (the sel tag) when
	      the window does not have the input focus.	If empty, {}, then  no
	      selection	is shown when the window does not have the focus.

       Command-Line Name:-insertunfocussed
       Database	Name:  insertUnfocussed
       Database	Class: InsertUnfocussed

	      Specifies	 how  to  display the insertion	cursor when the	widget |
	      does not have the	focus. Must be none (the default) which	 means |
	      to  not display the cursor, hollow which means to	display	a hol- |
	      low box, or solid	which means to display a solid box. Note  that |
	      hollow  and solid	will appear very similar when the -blockcursor |
	      option is	false.

       Command-Line Name:-maxundo
       Database	Name:  maxUndo
       Database	Class: MaxUndo

	      Specifies	the maximum number of compound	undo  actions  on  the
	      undo  stack.  A zero or a	negative value imply an	unlimited undo
	      stack.

       Command-Line Name:-spacing1
       Database	Name:  spacing1
       Database	Class: 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  dis-
	      play.  This  option  may be overridden with -spacing1 options in
	      tags.

       Command-Line Name:-spacing2
       Database	Name:  spacing2
       Database	Class: 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 dis-
	      tances. This option may be overridden with -spacing2 options  in
	      tags.

       Command-Line Name:-spacing3
       Database	Name:  spacing3
       Database	Class: 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 overridden with -spacing3 options in tags.

       Command-Line Name:-startline
       Database	Name:  startLine
       Database	Class: StartLine

	      Specifies	an integer line	index representing the first  line  of
	      the  underlying  textual	data store that	should be contained in
	      the widget. This allows a	text widget to reflect only a  portion
	      of  a  larger  piece  of	text. Instead of an integer, the empty
	      string can be provided to	this configuration option, which  will
	      configure	the widget to start at the very	first line in the tex-
	      tual data	store.

       Command-Line Name:-state
       Database	Name:  state
       Database	Class: 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.

       Command-Line Name:-tabs
       Database	Name:  tabs
       Database	Class: 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 of which is a distance relative to the left
	      edge of the widget (excluding borders, padding, etc). Each posi-
	      tion  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 de-
	      fault; it	causes the text	following the tab character to be  po-
	      sitioned	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 {2c left 4c 6c center}" cre-
	      ates 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.	Tab distances must be strictly positive, and must  al-
	      ways increase from one tab stop to the next (if not, an error is
	      thrown). 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	(aver-
	      age  size) characters.  To achieve a different standard spacing,
	      for example every	4 characters, simply configure the widget with
	      "-tabs  "[expr  {4  *  [font  measure $font 0]}] left" -tabstyle
	      wordprocessor".

       Command-Line Name:-tabstyle
       Database	Name:  tabStyle
       Database	Class: TabStyle

	      Specifies	how to interpret the relationship between tab stops on
	      a	line and tabs in the text of that line.	The value must be tab-
	      ular (the	default) or wordprocessor. Note	that tabs  are	inter-
	      preted  as they are encountered in the text. If the tab style is
	      tabular then the n'th tab	character in the line's	text  will  be
	      associated  with the n'th	tab stop defined for that line.	If the
	      tab character's x	coordinate falls to the	right of the n'th  tab
	      stop,  then  a gap of a single space will	be inserted as a fall-
	      back. If the tab style is	wordprocessor then any	tab  character
	      being  laid  out will use	(and be	defined	by) the	first tab stop
	      to the right of the preceding characters	already	 laid  out  on
	      that  line.  The value of	the -tabstyle option may be overridden
	      by -tabstyle options in tags.

       Command-Line Name:-undo
       Database	Name:  undo
       Database	Class: Undo

	      Specifies	a boolean that says whether the	undo mechanism is  ac-
	      tive or not.

       Command-Line Name:-width
       Database	Name:  width
       Database	Class: Width

	      Specifies	 the  desired width for	the window in units of charac-
	      ters in the font given by	the -font option. If the font does not
	      have a uniform width then	the width of the character "0" is used
	      in translating from character units to screen units.

       Command-Line Name:-wrap
       Database	Name:  wrap
       Database	Class: 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; ex-
	      tra characters that do not fit on	the screen are not  displayed.
	      In the other modes each line of text will	be broken up into sev-
	      eral screen lines	if necessary to	keep all the characters	 visi-
	      ble.  In char mode a screen line break may occur after any char-
	      acter; in	word mode a line break	will  only  be	made  at  word
	      boundaries.
______________________________________________________________________________

DESCRIPTION
       The  text command creates a new window (given by	the pathName 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 con-
       figure aspects of the text such as its default background color and re-
       lief.  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  differ-
       ent  fonts and colors. In addition, Tcl commands	can be associated with
       tags so that scripts are	invoked	when particular	actions	such  as  key-
       strokes	and  mouse  button  presses  occur in particular ranges	of the
       text. See TAGS below for	more details.

       The second form of annotation consists of floating markers in the  text
       called  "marks".	  Marks	 are used to keep track	of various interesting
       positions in the	text as	it is edited. See MARKS	 below	for  more  de-
       tails.

       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  text  widget also has a built-in undo/redo mechanism. See THE UNDO
       MECHANISM below for more	details.

       The text	widget allows for the creation	of  peer  widgets.  These  are
       other  text  widgets which share	the same underlying data (text,	marks,
       tags, images, etc).  See	PEER WIDGETS below for more details.

INDICES
       Many of the widget commands for texts take one or more indices as argu-
       ments.  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.  Most
       modifiers (as documented	below) allow an	 optional  submodifier.	 Valid
       submodifiers  are  any  and display. If the submodifier is abbreviated,
       then it must be followed	by whitespace, but otherwise there need	be  no
       space  between  the  submodifier	and the	following modifier.  Typically
       the display submodifier adjusts the meaning of the  following  modifier
       to  make	 it  refer  to	visual or non-elided units rather than logical
       units, but this is explained for	 each  relevant	 case  below.  Lastly,
       where  count is used as part of a modifier, it can be positive or nega-
       tive, so	"base -	-3 lines" is perfectly valid (and equivalent to	 "base
       +3lines").

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

       line.char   Indicates  char'th  character  on line line.	Lines are num-
		   bered 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  new-
		   line	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 char-
		   acters 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.

       pathName	   Indicates the position of the embedded window whose name is
		   pathName.   This form generates an error if there is	no em-
		   bedded window by the	given name.

       imageName   Indicates the position of the embedded image	whose name  is
		   imageName.  This form generates an error if there is	no em-
		   bedded 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 ?submodifier? 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 in-
	      dex to the last index in the text.  Spaces  on  either  side  of
	      count  are optional. If the display submodifier is given,	elided
	      characters are skipped over without being	 counted.  If  any  is
	      given,  then all characters are counted. For historical reasons,
	      if neither modifier is given then	the count actually takes place
	      in  units	of index positions (see	INDICES	for details). This be-
	      haviour may be changed in	a future major release,	so if you need
	      an  index	count, you are encouraged to use indices instead wher-
	      ever possible.

       - count ?submodifier? 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  index in the text (1.0). Spaces on	either
	      side of count are	optional. If the display submodifier is	given,
	      elided characters	are skipped over without being counted.	If any
	      is given,	then all characters are	counted. For  historical  rea-
	      sons, if neither modifier	is given then the count	actually takes
	      place in units of	index positions	 (see  INDICES	for  details).
	      This  behavior  may  be changed in a future major	release, so if
	      you need an index	count, you are encouraged to use  indices  in-
	      stead wherever possible.

       + count ?submodifier? indices
	      Adjust  the  index  forward  by count index positions, moving to
	      later lines in the text if necessary. If there  are  fewer  than
	      count  index positions in	the text after the current index, then
	      set the index to the last	index position in the text. Spaces  on
	      either  side  of count are optional. Note	that an	index position
	      is either	a single character or a	single embedded	image  or  em-
	      bedded  window.  If the display submodifier is given, elided in-
	      dices are	skipped	over without being counted. If any  is	given,
	      then all indices are counted; this is also the default behaviour
	      if no modifier is	given.

       - count ?submodifier? indices
	      Adjust the index backward	by count index	positions,  moving  to
	      earlier  lines in	the text if necessary. If there	are fewer than
	      count index positions in the text	before the current index, then
	      set  the	index  to  the first index position (1.0) in the text.
	      Spaces on	either side of count are optional. If the display sub-
	      modifier is given, elided	indices	are skipped over without being
	      counted. If any is given,	then all indices are counted; this  is
	      also the default behaviour if no modifier	is given.

       + count ?submodifier? 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  op-
	      tional.  If  the	display	submodifier is given, then each	visual
	      display line is counted separately.  Otherwise, if  any  (or  no
	      modifier)	 is  given, then each logical line (no matter how many
	      times it is visually wrapped) counts just	once. If the  relevant
	      lines  are  not  wrapped,	then these two methods of counting are
	      equivalent.

       - count ?submodifier? lines
	      Adjust the index backward	by count logical 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.
	      If the display submodifier is given, then	 each  visual  display
	      line  is	counted	separately. Otherwise, if any (or no modifier)
	      is given,	then each logical line (no matter how many times it is
	      visually	wrapped)  counts  just once. If	the relevant lines are
	      not wrapped, then	these two methods of counting are equivalent.

       ?submodifier? linestart
	      Adjust the index to refer	to the first index on the line.	If the
	      display  submodifier  is	given,	this is	the first index	on the
	      display line, otherwise on the logical line.

       ?submodifier? lineend
	      Adjust the index to refer	to the last index  on  the  line  (the
	      newline).	 If the	display	submodifier is given, this is the last
	      index on the display line, otherwise on the logical line.

       ?submodifier? 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. If the display sub-
	      modifier is given, this  only  examines  non-elided  characters,
	      otherwise	all characters (elided or not) are examined.

       ?submodifier? wordend
	      Adjust  the  index to refer to the character just	after the last
	      one of the word containing the current index. If the current in-
	      dex refers to the	last character of the text then	it is not mod-
	      ified. If	the display submodifier	is given, this	only  examines
	      non-elided  characters, otherwise	all characters (elided or not)
	      are examined.

       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 in-
       sertion cursor. Modifiers are applied one by one	in this	left to	 right
       order,  and  after each step the	resulting index	is constrained to be a
       valid index in the text widget. So, for example,	 the  index  "1.0  -1c
       +1c" refers to the index	"2.0".

       Where modifiers result in index changes by display lines, display chars
       or display indices, and the base	refers to an index  inside  an	elided
       tag,  that  base	index is considered to be equivalent to	the first fol-
       lowing non-elided index.

TAGS
       The first form of annotation in text widgets is a tag. A	tag is a  tex-
       tual  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  characters "	" (space), +, or -: these characters have spe-
       cial meaning in indices,	so tags	containing them	cannot be used as  in-
       dices.  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  im-
       plementing  some	 of  the tag-related functions described below.	When a
       tag is defined (by associating it with characters or setting  its  dis-
       play  options or	binding	commands to it), it is given a priority	higher
       than any	existing tag. The priority order of tags may be	redefined  us-
       ing the "pathName tag raise" and	"pathName tag lower" widget commands.

       Tags  serve three purposes in text widgets. First, they control the way
       information is displayed	on the screen. By default, characters are dis-
       played as determined by the -background,	-font, and -foreground options
       for the text widget. However, display options may  be  associated  with
       individual tags using the "pathName tag configure" widget command. If a
       character has been tagged, then the display options associated with the
       tag  override the default display style.	The following options are cur-
       rently supported	for tags:

       -background color
	      Color specifies the background color to use for characters asso-
	      ciated  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_Get-
	      Bitmap. If bitmap	has not	been specified,	or if it is  specified
	      as an empty string, then a solid fill will be used for the back-
	      ground.

       -borderwidth pixels
	      Pixels specifies the width of a border to	draw  around  the  tag
	      using  any  of  the  forms accepted by Tk_GetPixels. This	option
	      should be	used in	conjunction with the -relief option to provide
	      the desired border.

       -elide boolean
	      Elide  specifies	whether	the data should	be elided. Elided data
	      (characters, images, embedded windows, etc.)  is	not  displayed
	      and  takes  no  space  on	screen,	but further on behaves just as
	      normal data.

       -fgstipple bitmap
	      Bitmap specifies a bitmap	that is	used as	a stipple pattern when
	      drawing  text  and  other	 foreground information	such as	under-
	      lines. It	may have any of	the forms accepted by Tk_GetBitmap. If
	      bitmap has not 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_GetFont.

       -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  non-elided character of a	display	line has a tag
	      for which	this option has	been specified,	 then  justify	deter-
	      mines 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 non-elided character of
	      that display line.

       -lmargin1 pixels
	      If the first non-elided 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  win-
	      dow.  Pixels  may	have any of the	standard forms for screen dis-
	      tances. If a line	of text	wraps, this option only	applies	to the
	      first line on the	display; the -lmargin2 option controls the in-
	      dentation	for subsequent lines.

       -lmargin2 pixels
	      If the first non-elided 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 in-
	      dented 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	super-
	      scripts 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 Tcl_GetBoolean.

       -relief relief
	      Relief specifies the relief style	to use for drawing the border,
	      in any of	the forms accepted by  Tk_GetRelief.  This  option  is
	      used  in	conjunction  with the -borderwidth option to enable to
	      the desired border appearance.

       -rmargin	pixels
	      If the first non-elided 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	 wrap-
	      ping is enabled. If a text line wraps, the right margin for each
	      line on the display is determined	by the first non-elided	 char-
	      acter 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  dis-
	      tances.  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 dis-
	      tances. 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 non-elided 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	-tags {	}, then	it re-
	      quests default 8-character tabs as described for the -tags  wid-
	      get option.

       -tabstyle style
	      Style  specifies	either	the  tabular or	wordprocessor style of
	      tabbing to use for the text widget. This option only applies  to
	      a	 display  line if it applies to	the first non-elided 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).

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

       -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 dis-
       play options conflict, then the options of the highest priority tag are
       used.  If a particular display option has not been specified for	a par-
       ticular 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  de-
       fault style for the widget will be used.

       The  second purpose for tags is event bindings. You can associate bind-
       ings 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 Tcl command 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 "pathName tag bind" widget command below. Tag
       bindings	are shared between all peer widgets  (including	 any  bindings
       for the special sel tag).

       The  third use for tags is in managing the selection. See THE SELECTION
       below. With the exception of the	special	sel tag, all tags  are	shared
       between	peer  text  widgets,  and may be manipulated on	an equal basis
       from any	such widget. The sel tag exists	separately  and	 independently
       in each peer text widget	(but any tag bindings to sel are shared).

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 is not 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  "pathName
       mark"  widget command, and their	current	locations may be determined by
       using the mark name as an index in widget commands.

       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 in-
       serted 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 posi-
       tion.  If the mark has right gravity, new text inserted at the mark po-
       sition will appear to the left of the mark (so that  the	 mark  remains
       rightmost). 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 associ-
       ated with the insertion cursor, as described under THE INSERTION	CURSOR
       below.  Second, the mark	current	is associated with the character clos-
       est to the mouse	and is adjusted	automatically to track the mouse posi-
       tion  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 re-
       leased).	 Neither of these special marks	may be deleted.	With  the  ex-
       ception	of  these two special marks, all marks are shared between peer
       text widgets, and may be	manipulated on an equal	basis from any peer.

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  win-
       dows 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  up-
       dated  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  wid-
       get.  Each  embedded window occupies one	unit'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. Similarly	if the text widget as a	whole is deleted, then
       the window is destroyed.

       When an embedded	window is added	to a text  widget  with	 the  pathName
       window  create widget command, several configuration options may	be as-
       sociated	with it. These options may be modified later with the pathName
       window  configure  widget  command. The following options are currently
       supported:

       -align where
	      If the window is not as tall as the line in  which  it  is  dis-
	      played,  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 win-
	      dow 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 script
	      Specifies	a Tcl script that may be evaluated to create the  win-
	      dow  for the annotation. If no -window option has	been specified
	      for the annotation this script will be evaluated when the	 anno-
	      tation  is about to be displayed on the screen. Script must cre-
	      ate a window for the annotation and return the name of that win-
	      dow as its result. Two substitutions will	be performed in	script
	      before evaluation. %W will be substituted	by  the	 name  of  the
	      parent  text  widget,  and %% will be substituted	by a single %.
	      If the annotation's window should	ever be	deleted,  script  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  de-
	      fined 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	window.	It may have any	of the
	      usual forms defined for a	screen distance.

       -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	verti-
	      cally 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 pathName
	      Specifies	the name of a window to	 display  in  the  annotation.
	      Note  that  if a pathName	has been set, then later configuring a
	      window to	the empty string will not  delete  the	widget	corre-
	      sponding to the old pathName.  Rather it will remove the associ-
	      ation between the	old pathName and the text widget. If  multiple
	      peer  widgets are	in use,	it is usually simpler to use the -cre-
	      ate option if embedded windows are desired in each peer.

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 particu-
       lar 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 im-
       age occupies one	unit'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 pathName image create. 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 pathName im-
       age create widget command, a name unique	to this	instance of the	 image
       is  returned.  This  name  may  then be used to refer to	this image in-
       stance. The name	is taken to be the value  of  the  -name  option  (de-
       scribed 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  as-
       signed  to  this	instance of the	image, it does not change, even	though
       the -image or -name values can be changed with pathName	image  config-
       ure.

       When  an	embedded image is added	to a text widget with the pathName im-
       age create widget command, several configuration	options	may be associ-
       ated with it. These options may be modified later with the pathName im-
       age configure widget command. The following options are currently  sup-
       ported:

       -align where
	      If  the  image  is  not  as tall as the line in which it is dis-
	      played, 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	refer-
	      enced in the text	widget.	If ImageName is	not supplied, then the
	      name of the Tk image is used instead. If the  imageName  is  al-
	      ready  in	 use,  #nn  is	appended to the	end of the name	as de-
	      scribed 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 de-
	      fined 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  op-
       tion  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 "pathName	tag  delete"  widget  command.
       Furthermore,  the  -selectbackground,  -selectborderwidth, and -select-
       foreground options for the text widget are  tied	 to  the  -background,
       -borderwidth,  and  -foreground options for the sel tag:	changes	in ei-
       ther will automatically be reflected in the other. Also the -inactives-
       electbackground	option for the text widget is used instead of -select-
       background when the text	widget does not	have the  focus.  This	allows
       programmatic  control  over  the	visualization of the sel tag for fore-
       ground and background windows, or to have sel not shown	at  all	 (when
       -inactiveselectbackground  is  empty) for background windows. Each peer
       text widget has its own sel tag which can be separately configured  and
       set.

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	 "pathName mark	unset" widget command. The insert mark
       represents the position of the insertion	cursor,	and the	insertion cur-
       sor  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  programmatically  as
       well.  Whenever	the flag changes state a <<Modified>> virtual event is
       generated. See the pathName edit	modified widget	command	for  more  de-
       tails.

THE UNDO MECHANISM
       The  text  widget  has  an  unlimited undo and redo mechanism (when the
       -undo widget option is true) which records every	insert and delete  ac-
       tion on a stack.

       Boundaries (called "separators")	are inserted between edit actions. The
       purpose of these	separators is to group inserts,	deletes	 and  replaces
       into one	compound edit action. When undoing a change everything between
       two separators will be undone. The undone changes are then moved	to the
       redo stack, so that an undone edit can be redone	again.	The redo stack
       is cleared whenever new edit actions are	recorded on  the  undo	stack.
       The  undo and redo stacks can be	cleared	to keep	their depth under con-
       trol.

       Separators are inserted automatically when the  -autoseparators	widget
       option  is true.	You can	insert separators programmatically as well. If
       a separator is already present at the top of the	undo  stack  no	 other
       will  be	inserted. That means that two separators on the	undo stack are
       always separated	by at least one	insert or delete action.

       The undo	mechanism is also linked to the	modified flag. This means that
       undoing	or redoing changes can take a modified text widget back	to the
       unmodified state	or vice	versa. The modified flag will be set automati-
       cally  to  the appropriate state. This automatic	coupling does not work
       when the	modified flag has been set by the user,	 until	the  flag  has
       been reset again.

       See  below  for the pathName edit widget	command	that controls the undo
       mechanism.

PEER WIDGETS
       The text	widget has a separate store of all its	data  concerning  each
       line's  textual contents, marks,	tags, images and windows, and the undo
       stack.

       While this data store cannot be accessed	directly (i.e. without a  text
       widget  as an intermediary), multiple text widgets can be created, each
       of which	present	different views	on the same underlying data. Such text
       widgets are known as peer text widgets.

       As  text	 is added, deleted, edited and coloured	in any one widget, and
       as images, marks, tags are adjusted, all	such changes will be reflected
       in all peers.

       All  data  and markup is	shared,	except for a few small details.	First,
       the sel tag may be set and configured (in its  display  style)  differ-
       ently  for  each	peer. Second, each peer	has its	own insert and current
       mark positions (but all other marks are shared).	Third,	embedded  win-
       dows,  which  are  arbitrary  other  widgets,  cannot be	shared between
       peers. This means the -window option of embedded	 windows  is  indepen-
       dently set for each peer	(it is advisable to use	the -create script ca-
       pabilities to allow each	peer to	create its  own	 embedded  windows  as
       needed).	 Fourth,  all  of the configuration options of each peer (e.g.
       -font, etc) can be set independently,  with  the	 exception  of	-undo,
       -maxundo,  -autoseparators  (i.e. all undo, redo	and modified state is-
       sues are	shared).

       Finally any single peer need not	contain	all lines from the  underlying
       data  store.  When  creating  a peer, a contiguous range	of lines (e.g.
       only lines 52 through 125) may be specified. This allows	a peer to con-
       tain  just a small portion of the overall text. The range of lines will
       expand and contract as text is inserted or deleted. The peer will  only
       ever  display  complete	lines of text (one cannot share	just part of a
       line). If the peer's contents contracts to nothing (i.e.	 all  complete
       lines  in  the peer widget have been deleted from another widget), then
       it is impossible	for new	lines to be inserted. The peer will simply be-
       come  an	 empty	shell  on  which the background	can be configured, but
       which will never	show any content (without  manual  reconfiguration  of
       the  start  and end lines). Note	that a peer which does not contain all
       of the underlying data store still has indices numbered from  "1.0"  to
       "end".	It  is simply that those indices reflect a subset of the total
       data, and data outside the contained range is  not  accessible  to  the
       peer.  This  means that the command peerName index end may return quite
       different values	in different peers. Similarly, commands	like  peerName
       tag  ranges will	not return index ranges	outside	that which is meaning-
       ful to the peer.	The configuration options -startline and -endline  may
       be  used	to control how much of the underlying data is contained	in any
       given text widget.

       Note that peers are really peers. Deleting the "original"  text	widget
       will not	cause any other	peers to be deleted, or	otherwise affected.

       See  below  for the pathName peer widget	command	that controls the cre-
       ation of	peer widgets.

WIDGET COMMAND
       The text	command	creates	a new Tcl command whose	name is	 the  same  as
       the  path name of the text's window. This command may be	used to	invoke
       various operations on the widget. It has	the following general form:
	      pathName option ?arg arg ...?
       PathName	is the name of the command, which is the same as the text wid-
       get's  path  name.  Option and the args determine the exact behavior of
       the command. The	following commands are possible	for text widgets:

       pathName	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  par-
	      tially  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.

       pathName	cget option
	      Returns  the  current value of the configuration option given by
	      option.  Option may have any of the values accepted by the  text
	      command.

       pathName	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  relation-
	      ship  is satisfied and 0 if it is	not. Op	must be	one of the op-
	      erators <, <=, ==, >=, >,	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.

       pathName	configure ?option? ?value option value ...?
	      Query  or	 modify	the configuration options of the widget. If no
	      option is	specified, returns a list describing all of the	avail-
	      able  options for	pathName (see Tk_ConfigureInfo 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  widget option(s) to have the given	value(s); in this case
	      the command returns an empty string. Option may have any of  the
	      values accepted by the text command.

       pathName	count ?options?	index1 index2
	      Counts the number	of relevant things between the two indices. If
	      index1 is	after index2, the result will  be  a  negative	number
	      (and  this  holds	 for each of the possible options). The	actual
	      items which are counted depend on	the options given. The	result
	      is  a  list of integers, one for the result of each counting op-
	      tion given. Valid	counting options  are  -chars,	-displaychars,
	      -displayindices,	-displaylines,	-indices, -lines, -xpixels and
	      -ypixels.	The default value, if no option	is specified, is  -in-
	      dices. There is an additional possible option -update which is a
	      modifier.	If given, then all subsequent options ensure that  any
	      possible out of date information is recalculated.	This currently
	      only has any effect for the -ypixels count (which, if -update is
	      not  given,  will	use the	text widget's current cached value for
	      each line). The count options are	interpreted as follows:

	      -chars count all characters, whether elided or not. Do not count
		     embedded windows or images.

	      -displaychars
		     count all non-elided characters.

	      -displayindices
		     count all non-elided characters, windows and images.

	      -displaylines
		     count  all	display	lines (i.e. counting one for each time
		     a line wraps) from	the line of the	first index up to, but
		     not  including  the  display  line	 of  the second	index.
		     Therefore if they are both	on the same display line, zero
		     will  be returned.	By definition displaylines are visible
		     and therefore this	only counts portions of	actual visible
		     lines.

	      -indices
		     count all characters and embedded windows or images (i.e.
		     everything	which  counts  in  text-widget	index  space),
		     whether they are elided or	not.

	      -lines count  all	 logical lines (irrespective of	wrapping) from
		     the line of the first index up to,	but not	including  the
		     line  of  the second index. Therefore if they are both on
		     the same line, zero will be returned. Logical  lines  are
		     counted  whether  they are	currently visible (non-elided)
		     or	not.

	      -xpixels
		     count the number of  horizontal  pixels  from  the	 first
		     pixel of the first	index to (but not including) the first
		     pixel of the second index.	To  count  the	total  desired
		     width  of	the  text widget (assuming wrapping is not en-
		     abled), first find	the longest line and then  use	".text
		     count -xpixels "${line}.0"	"${line}.0 lineend"".

	      -ypixels
		     count  the	number of vertical pixels from the first pixel
		     of	the first index	to (but	not including) the first pixel
		     of	the second index. If both indices are on the same dis-
		     play line,	zero will be returned. To count	the total num-
		     ber  of  vertical	pixels	in the text widget, use	".text
		     count -ypixels 1.0	end", and to  ensure  this  is	up  to
		     date, use ".text count -update -ypixels 1.0 end".

	      The command returns a positive or	negative integer corresponding
	      to the number of items counted between the two indices. One such
	      integer is returned for each counting option given, so a list is
	      returned if more than  one  option  was  supplied.  For  example
	      ".text  count  -xpixels -ypixels 1.3 4.5"	is perfectly valid and
	      will return a list of two	elements.

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

	      When  debugging  is  turned on, the drawing routines of the text
	      widget set the global variables tk_textRedraw and	 tk_textRelay-
	      out  to  the  lists  of  indices that are	redrawn. The values of
	      these variables are tested by Tk's test suite.

       pathName	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 does
	      not specify a position later in the text	than  index1  then  no
	      characters  are  deleted.	  If  index2 is	not 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 so	deleted	text does  not
	      cause  an	 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.

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

       pathName	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,	image,
	      and window. The corresponding value is the text, mark name,  tag
	      name,  image  name, or window name. The index information	is the
	      index of the start of the	text, mark, tag	transition,  image  or
	      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,
		     images and	windows.  This is the default.

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

	      -image Include information about images in the dump results.

	      -mark  Include information about marks in	the dump results.

	      -tag   Include information about tag transitions in the dump re-
		     sults. 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  segments  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 cre-
		     ate  script.)  In	this case an empty string is returned,
		     and you must query	the window by its  index  position  to
		     get more information.

       pathName	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 com-
	      mand are currently supported:

	      pathName edit modified ?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.

	      pathName edit redo
		     When the -undo option is true, reapplies the last	undone
		     edits  provided no	other edits were done since then. Gen-
		     erates an error when the redo stack is empty. Does	 noth-
		     ing when the -undo	option is false.

	      pathName edit reset
		     Clears the	undo and redo stacks.

	      pathName edit separator
		     Inserts  a	 separator  (boundary) on the undo stack. Does
		     nothing when the -undo option is false.

	      pathName edit undo
		     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.

       pathName	get ?-displaychars? ?--? 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 in-
	      dex2 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,  mul-
	      tiple  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 pathName get.	If the
	      -displaychars option is given, then,  within  each  range,  only
	      those characters which are not elided will be returned. This may
	      have the effect that some	 of  the  returned  ranges  are	 empty
	      strings.

       pathName	image option ?arg arg ...?
	      This command is used to manipulate embedded images. The behavior
	      of the command depends on	the option argument that  follows  the
	      tag  argument.  The following forms of the command are currently
	      supported:

	      pathName image cget index	option
		     Returns the value of a configuration option for an	embed-
		     ded  image.  Index	identifies the embedded	image, and op-
		     tion specifies a particular configuration	option,	 which
		     must  be  one  of the ones	listed in the section EMBEDDED
		     IMAGES.

	      pathName image configure index ?option value ...?
		     Query or modify the configuration options for an embedded
		     image. If no option is specified, returns a list describ-
		     ing all of	the available options for the  embedded	 image
		     at	 index	(see  Tk_ConfigureInfo	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	corre-
		     sponding  sublist	of  the	value returned if no option is
		     specified). If one	or more	option-value pairs are	speci-
		     fied,  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.

	      pathName image create 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  config-
		     ure  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.

	      pathName image names
		     Returns a list whose elements are the names of all	 image
		     instances currently embedded in window.

       pathName	index index
	      Returns	the  position  corresponding  to  index	 in  the  form
	      line.char	where line is the line number and char is the  charac-
	      ter number.  Index may have any of the forms described under IN-
	      DICES above.

       pathName	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 af-
	      ter 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	 char-
	      acters  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 oth-
	      ers, regardless of the tags present around the insertion	point.
	      If  multiple chars-tagList argument pairs	are present, they pro-
	      duce the same effect as if a  separate  pathName	insert	widget
	      command  had  been  issued  for  each  pair,  in order. The last
	      tagList argument may be omitted.

       pathName	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  sup-
	      ported:

	      pathName mark gravity markName ?direction?
		     If	 direction  is not specified, returns left or right to
		     indicate which of its adjacent characters markName	is at-
		     tached  to. If direction is specified, it must be left or
		     right; the	gravity	of markName is set to the given	value.

	      pathName mark names
		     Returns a list whose elements are the names  of  all  the
		     marks that	are currently set.

	      pathName mark next 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 imme-
		     diately  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  wid-
		     get in the	same order as the mark information returned by
		     the pathName dump operation. If a mark has	 been  set  to
		     the  special  end	index, then it appears to be after end
		     with respect to the  pathName  mark  next	operation.  An
		     empty  string is returned if there	are no marks after in-
		     dex.

	      pathName mark previous 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	seman-
		     tics  mean	 that the pathName 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
		     pathName dump operation. An empty string is  returned  if
		     there are no marks	before index.

	      pathName mark set	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 does not exist, a new
		     mark is created. This command returns an empty string.

	      pathName mark unset markName ?markName markName ...?
		     Remove the	mark corresponding to each of the markName ar-
		     guments.  The removed marks will not be usable in indices
		     and will not be returned by  future  calls	 to  "pathName
		     mark names".  This	command	returns	an empty string.

       pathName	peer option args
	      This  command  is	 used to create	and query widget peers.	It has
	      two forms, depending on option:

	      pathName peer create newPathName ?options?
		     Creates a peer text widget	with  the  given  newPathName,
		     and  any  optional	standard configuration options (as for
		     the text command).	By default the peer will have the same
		     start and end line	as the parent widget, but these	can be
		     overridden	with the standard configuration	options.

	      pathName peer names
		     Returns a list of peers of	this widget (this does not in-
		     clude  the	 widget	itself). The order within this list is
		     undefined.

       pathName	replace	index1 index2 chars ?tagList chars tagList ...?
	      Replaces the range of characters between index1 and index2  with
	      the  given  characters and tags. See the section on pathName in-
	      sert for an explanation of the handling of the tagList...	 argu-
	      ments,  and the section on pathName delete for an	explanation of
	      the handling of the indices. If index2 corresponds to  an	 index
	      earlier in the text than index1, an error	will be	generated.

	      The  deletion  and insertion are arranged	so that	no unnecessary
	      scrolling	of the window or movement of insertion cursor  occurs.
	      In  addition the undo/redo stack are correctly modified, if undo
	      operations are active in the text	widget.	The command returns an
	      empty string.

       pathName	scan option args
	      This  command is used to implement scanning on texts. It has two
	      forms, depending on option:

	      pathName scan mark x y
		     Records x and y and the current view in the text  window,
		     for  use  in  conjunction with later pathName scan	dragto
		     commands. Typically this command  is  associated  with  a
		     mouse  button  press  in  the widget. It returns an empty
		     string.

	      pathName scan dragto x y
		     This command computes the difference between its x	and  y
		     arguments	and the	x and y	arguments to the last pathName
		     scan mark command for the widget.	It  then  adjusts  the
		     view by 10	times the difference in	coordinates. This com-
		     mand 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.

       pathName	search ?switches? pattern index	?stopIndex?
	      Searches	the  text in pathName 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; oth-
	      erwise 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 posi-
		     tion given	by index. This is the default.

	      -backwards
		     The search	will proceed backward through the text,	 find-
		     ing the matching range closest to index whose first char-
		     acter is before index (it is not allowed to be at index).
		     Note  that,  for a	variety	of reasons, backwards searches
		     can be substantially slower than forwards searches	 (par-
		     ticularly	when using -regexp), so	it is recommended that
		     performance-critical code use forward searches.

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

	      -regexp
		     Treat pattern  as	a  regular  expression	and  match  it
		     against  the text using the rules for regular expressions
		     (see the regexp command and the re_syntax	page  for  de-
		     tails).  The  default  matching automatically passes both
		     the -lineanchor and -linestop options to the  regexp  en-
		     gine  (unless  -nolinestop	is used), so that ^$ match be-
		     ginning and end of	line, and ., [^	sequences  will	 never
		     match the newline character \n.

	      -nolinestop
		     This allows . and [^ sequences to match the newline char-
		     acter \n, which they will otherwise not do	(see the  reg-
		     exp  command for details).	This option is only meaningful
		     if	-regexp	is also	given, and an  error  will  be	thrown
		     otherwise.	 For  example,	to  match the entire text, use
		     "pathName search -nolinestop -regexp ".*" 1.0".

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

	      -count varName
		     The argument following -count gives the name of  a	 vari-
		     able;  if a match is found, the number of index positions
		     between beginning and end of the matching range  will  be
		     stored  in	 the variable. If there	are no embedded	images
		     or	windows	in the matching	range (and there are no	elided
		     characters	if -elide is not given), this is equivalent to
		     the number	of characters matched.	In  either  case,  the
		     range matchIdx to matchIdx	+ $count chars will return the
		     entire matched text.

	      -all   Find all matches in the given range and return a list  of
		     the  indices  of  the first character of each match. If a
		     -count varName switch is given, then varName is also  set
		     to	 a  list  containing  one  element for each successful
		     match. Note that, even for	exact searches,	 the  elements
		     of	 this list may be different, if	there are embedded im-
		     ages, windows or hidden text.  Searches with -all	behave
		     very  similarly  to  the Tcl command regexp -all, in that
		     overlapping matches are not normally returned. For	 exam-
		     ple, applying an -all search of the pattern "\w+" against
		     "hello there" will	just match twice, once for each	 word,
		     and  matching  "Z[a-z]+Z"	against	 "ZooZooZoo" will just
		     match once.

	      -overlap
		     When performing -all searches, the	 normal	 behaviour  is
		     that  matches  which  overlap an already-found match will
		     not be returned. This switch changes  that	 behaviour  so
		     that  all	matches	 which are not totally enclosed	within
		     another match are	returned.  For	example,  applying  an
		     -overlap  search  of  the	pattern	 "\w+"	against	"hello
		     there" will just match twice (i.e.	no different  to  just
		     -all),  but  matching "Z[a-z]+Z" against "ZooZooZoo" will
		     now match twice. An error will be thrown if  this	switch
		     is	used without -all.

	      -strictlimits
		     When  performing any search, the normal behaviour is that
		     the start and stop	limits are checked with	respect	to the
		     start  of the matching text. With the -strictlimits flag,
		     the entire	matching range must lie	inside the  start  and
		     stop limits specified for the match to be valid.

	      -elide Find  elided  (hidden) text as well. By default only dis-
		     played text is searched.

	      --     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 may be	within a single	line of	text,  or  run
	      across  multiple lines (if parts of the pattern can match	a new-
	      line). For regular expression matching one can use  the  various
	      newline-matching	features such as $ to match the	end of a line,
	      ^	to match the beginning of a line, and to control whether .  is
	      allowed  to  match  a  new-line.	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.  This	 means
	      that,  for  example, if the search is -forwards but stopIndex is
	      earlier in the text than startIndex, nothing will	ever be	found.
	      See  KNOWN  BUGS	below for a number of minor limitations	of the
	      pathName search command.

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

       pathName	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 sup-
	      ported:

	      pathName tag add 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 is not	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 ef-
		     fect.

	      pathName tag bind	tagName	?sequence? ?script?
		     This command associates script with the tag given by tag-
		     Name.   Whenever the event	sequence given by sequence oc-
		     curs for a	character that has been	tagged	with  tagName,
		     the  script will be invoked. This widget command is simi-
		     lar to the	bind command except that it operates on	 char-
		     acters in a text rather than entire widgets. See the bind
		     manual entry for complete details on the  syntax  of  se-
		     quence  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 cur-
		     rent 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-re-
		     lated 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  par-
		     ticular  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  cho-
		     sen  (see	the  manual entry for the bind command for de-
		     tails).  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.

	      pathName tag cget	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 path-
		     Name tag configure	widget command.

	      pathName tag configure tagName ?option?  ?value?	?option	 value
	      ...?
		     This  command is similar to the pathName configure	widget
		     command 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_ConfigureInfo 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 cor-
		     responding	sublist	of the value returned if no option  is
		     specified).  If one or more option-value pairs are	speci-
		     fied, then	the command modifies the  given	 option(s)  to
		     have the given value(s) in	tagName; in this case the com-
		     mand returns an empty string.  See	TAGS above for details
		     on	the options available for tags.

	      pathName tag delete tagName ?tagName ...?
		     Deletes all tag information for each of the tagName argu-
		     ments. The	command	removes	the tags from  all  characters
		     in	 the file and also deletes any other information asso-
		     ciated with the tags, such	as bindings and	display	infor-
		     mation. The command returns an empty string.

	      pathName tag lower 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.

	      pathName tag names ?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  "pathName
		     tag" widget command but have not been deleted by a	"path-
		     Name tag delete" widget command, even  if	no  characters
		     are  currently  marked  with  the	tag). The list will be
		     sorted in order from lowest priority to highest priority.

	      pathName tag nextrange 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 com-
		     mand'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.

	      pathName tag prevrange 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.

	      pathName tag raise 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.

	      pathName tag ranges 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.

	      pathName tag remove tagName index1 ?index2 index1	index2 ...?
		     Remove  the tag tagName from all of the characters	start-
		     ing at index1 and ending just before index2 (the  charac-
		     ter at index2 is not affected). A single command may con-
		     tain any number of	index1-index2 pairs. If	the  last  in-
		     dex2  is  omitted then the	tag is removed from the	single
		     character at index1. 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  com-
		     mand has no effect. This command returns an empty string.

       pathName	window option ?arg arg ...?
	      This  command is used to manipulate embedded windows. The	behav-
	      ior of the command depends on the	option argument	 that  follows
	      the window argument. The following forms of the command are cur-
	      rently supported:

	      pathName window cget index option
		     Returns the value of a configuration option for an	embed-
		     ded  window.   Index  identifies the embedded window, and
		     option specifies a	particular configuration option, which
		     must  be  one  of the ones	listed in the section EMBEDDED
		     WINDOWS.

	      pathName window configure	index ?option value ...?
		     Query or modify the configuration options for an embedded
		     window.  If  no  option  is specified, returns a list de-
		     scribing all of the available options  for	 the  embedded
		     window  at	index (see Tk_ConfigureInfo 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	corre-
		     sponding  sublist	of  the	value returned if no option is
		     specified). If one	or more	option-value pairs are	speci-
		     fied,  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 for	information on
		     the options that are supported.

	      pathName window create 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  config-
		     ure  the annotation. See EMBEDDED WINDOWS for information
		     on	the options  that  are	supported.  Returns  an	 empty
		     string.

	      pathName window names
		     Returns  a	 list whose elements are the names of all win-
		     dows currently embedded in	window.

       pathName	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 fol-
	      lowing forms:

	      pathName 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 win-
		     dow, and 40% of the text is off-screen to the right.  The
		     fractions refer only to the lines that are	actually visi-
		     ble in the	window:	if the lines in	 the  window  are  all
		     very  short,  so  that they are entirely visible, the re-
		     turned 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.

	      pathName xview moveto 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.

	      pathName xview scroll number what
		     This  command shifts the view in the window left or right
		     according to number and what. What	must be	 units,	 pages
		     or	 pixels. If what is units or pages then	number must be
		     an	integer, otherwise number may be specified in  any  of
		     the  forms	 acceptable to Tk_GetPixels, such as "2.0c" or
		     "1i" (the result is rounded to the	nearest	integer	value.
		     If	 no  units  are	given, pixels are assumed). 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 it is  pixels  then
		     the  view adjusts by number pixels. If number is negative
		     then characters farther to	the left become	visible; if it
		     is	 positive  then	characters farther to the right	become
		     visible.

       pathName	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 fol-
	      lowing forms:

	      pathName 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	visible	 pixel	of  the	 first
		     character	(or image, etc)	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 first pixel just after	the last visi-
		     ble 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.

	      pathName yview moveto fraction
		     Adjusts the view in the window so that the	pixel given by
		     fraction appears at the top of the	top line of  the  win-
		     dow.  Fraction is a fraction between 0 and	1; 0 indicates
		     the first pixel of	the first character in the text,  0.33
		     indicates the pixel that is one-third the way through the
		     text; and so on. Values close to 1	will  indicate	values
		     close to the last pixel in	the text (1 actually refers to
		     one pixel beyond the last pixel), but in such  cases  the
		     widget  will never	scroll beyond the last pixel, and so a
		     value of 1	will effectively be rounded back  to  whatever
		     fraction  ensures	the last pixel is at the bottom	of the
		     window, and some other pixel is at	the top.

	      pathName yview scroll number what
		     This command adjust the view in the window	up or down ac-
		     cording  to number	and what. What must be units, pages or
		     pixels. If	what is	units or pages then number must	be  an
		     integer,  otherwise number	may be specified in any	of the
		     forms acceptable to Tk_GetPixels, such as "2.0c" or  "1i"
		     (the  result  is rounded to the nearest integer value. If
		     no	units are given,  pixels  are  assumed).  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 it is pixels then the view adjusts by num-
		     ber pixels. If number is negative then earlier  positions
		     in	 the text become visible; if it	is positive then later
		     positions in the text become visible.

	      pathName yview ?-pickplace? index
		     Changes the view in the widget's  window  to  make	 index
		     visible.  If  the -pickplace option is not	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  win-
			    dow	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 pathName
		     see widget	command	(pathName see handles both x-  and  y-
		     motion to make a location visible,	whereas	the -pickplace
		     mode only handles motion in y).

	      pathName 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" is	depen-
       dent on the value of the	tcl_wordchars variable.	See tclvars(3tcl).

       [1]    Clicking	mouse button 1 positions the insertion cursor just be-
	      fore 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	start  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 start	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 but-
	      ton 1 was	pressed. If the	button is double-clicked before	 drag-
	      ging  then  the  selection  will	be  adjusted in	units of whole
	      words; if	it is triple-clicked then the selection	 will  be  ad-
	      justed in	units of whole lines.

       [5]    Clicking	mouse  button 1	with the Control key down will reposi-
	      tion 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  in-
	      sertion  cursor  moves  and the selection	is extended to include
	      the new character. Control-Left and Control-Right	move  the  in-
	      sertion  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. Con-
	      trol-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.

       [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  display  line and clear any selection in the	widget.	Shift-
	      Home moves the insertion cursor to the beginning of the  display
	      line and also extends the	selection to that point.

       [14]   End  and	Control-e  move	the insertion cursor to	the end	of the
	      display line and clear any selection in  the  widget.  Shift-End
	      moves  the cursor	to the end of the display line and extends the
	      selection	to that	point.

       [15]   Control-Home and Meta-< move the insertion cursor	to the	begin-
	      ning 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 se-
	      lection to that point.

       [17]   The Select key and Control-Space set the selection anchor	to the
	      position of the insertion	cursor.	They do	not affect the current
	      selection. Shift-Select and Control-Shift-Space adjust  the  se-
	      lection to the current position of the insertion cursor, select-
	      ing 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.  This  action  is	carried	 out  by  the  command
	      tk_textCopy.

       [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.  This  action  is	carried	 out  by  the  command
	      tk_textCut.  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  Con-
	      trol-y  inserts the contents of the clipboard at the position of
	      the insertion cursor. This action	is carried out by the  command
	      tk_textPaste.

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

       [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 after
	      copying it to the	clipboard.

       [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 cur-
       sor will	be displayed and no text modifications will take place.

       The behavior of texts can be changed by defining	new bindings for indi-
       vidual widgets or by redefining the class bindings.

KNOWN ISSUES
   ISSUES CONCERNING CHARS AND INDICES
       Before Tk 8.5, the widget used the string "chars" to refer to index po-
       sitions (which included characters, embedded windows and	 embedded  im-
       ages). As of Tk 8.5 the text widget deals separately and	correctly with
       "chars" and "indices".  For backwards compatibility, however, the index
       modifiers  "+N  chars" and "-N chars" continue to refer to indices. One
       must use	any of the full	forms "+N any chars" or	"-N any	chars" etc. to
       refer to	actual character indices. This confusion may be	fixed in a fu-
       ture release by making the widget correctly interpret "+N chars"	 as  a
       synonym for "+N any chars".

   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  num-
       ber  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 -in-
       sertofftime attribute to	0 avoid	this.

   KNOWN BUGS
       The pathName search -regexp sub-command attempts	to  perform  sophisti-
       cated  regexp  matching	across	multiple lines in an efficient fashion
       (since Tk 8.5), examining each line individually,  and  then  in	 small
       groups of lines,	whether	searching forwards or backwards. Under certain
       conditions the search result might differ from that obtained by	apply-
       ing  the	 same regexp to	the entire text	from the widget	in one go. For
       example,	when searching with a greedy regexp, the widget	will  continue
       to attempt to add extra lines to	the match as long as one of two	condi-
       tions are true: either Tcl's regexp library returns a code to  indicate
       a  longer match is possible (but	there are known	bugs in	Tcl which mean
       this code is not	always correctly returned);  or	 if  each  extra  line
       added  results in at least a partial match with the pattern. This means
       in the case where the first extra line added results in	no  match  and
       Tcl's  regexp system returns the	incorrect code and adding a second ex-
       tra line	would actually match, the text widget will  return  the	 wrong
       result. In practice this	is a rare problem, but it can occur, for exam-
       ple:
	      pack [text .t]
	      .t insert	1.0 "aaaa\nbbbb\ncccc\nbbbb\naaaa\n"
	      .t search	-regexp	-- {(a+|b+\nc+\nb+)+\na+} 1.0
       will not	find a match when one exists of	19  characters	starting  from
       the first "b".

       Whenever	 one  possible	match is fully enclosed	in another, the	search
       command will attempt to ensure only the larger match is returned.  When
       performing  backwards  regexp searches it is possible that Tcl will not
       always achieve this, in the case	where a	match is preceded  by  one  or
       more  short,  non-overlapping  matches,	all of which are preceded by a
       large match which actually encompasses all of them.  The	 search	 algo-
       rithm  used by the widget does not look back arbitrarily	far for	a pos-
       sible match which might cover large portions of the widget.  For	 exam-
       ple:
	      pack [text .t]
	      .t insert	1.0 "aaaa\nbbbb\nbbbb\nbbbb\nbbbb\n"
	      .t search	-regexp	-backward -- {b+\n|a+\n(b+\n)+}	end
       matches	at "5.0" when a	true greedy match would	match at "1.0".	 Simi-
       larly if	we add -all to this case, it matches at	all of	"5.0",	"4.0",
       "3.0"  and  "1.0", when really it should	only match at "1.0" since that
       match encloses all the others.

SEE ALSO
       entry(3tk), scrollbar(3tk)

KEYWORDS
       text, widget, tkvars

Tk				      8.5			     text(3tk)

NAME | SYNOPSIS | STANDARD OPTIONS | WIDGET-SPECIFIC OPTIONS | DESCRIPTION | INDICES | TAGS | MARKS | EMBEDDED WINDOWS | EMBEDDED IMAGES | THE SELECTION | THE INSERTION CURSOR | THE MODIFIED FLAG | THE UNDO MECHANISM | PEER WIDGETS | WIDGET COMMAND | BINDINGS | KNOWN ISSUES | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=text&sektion=3&manpath=Debian+8.1.0>

home | help