tk_textCopy man page on AIX

Printed from http://www.polarhome.com/service/man/?qf=tk_textCopy&af=0&tf=2&of=AIX

text(n)			     Tk Built-In Commands		       text(n)

______________________________________________________________________________

NAME
       text,  tk_textCopy,  tk_textCut,	 tk_textPaste  - Create and manipulate
       text 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
       [-autoseparators autoSeparators] Specifies a boolean that says  whether
       separators  are automatically inserted in the undo stack. Only meaning‐
       ful when the -undo option is true.   [-blockcursor blockCursor]	Speci‐ │
       fies  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 insertion cursor.	[-end‐
       line endLine] Specifies an integer line	index  representing  the  last │
       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   end	  at   the   very   last  line	in  the	 textual  data	store.
       [-height height] Specifies the desired height for the window, in	 units
       of  characters in the font given by the -font option.  Must be at least
       one.   [-inactiveselectbackground inactiveSelectBackground]   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.  [-maxundo maxUndo] Specifies
       the maximum number of compound undo actions on the undo stack.  A  zero
       or  a  negative	value imply an unlimited undo stack.  [-spacing1 spac‐
       ing1] Requests additional space above each text	line  in  the  widget,
       using any of the standard forms for screen distances.  If a line wraps,
       this option only applies to the first line on the display.  This option
       may be overridden with -spacing1 options in tags.  [-spacing2 spacing2]
       For lines that wrap (so that they cover more than one line on the  dis‐
       play)  this  option  specifies  additional space to provide between the
       display lines that represent a single line of text.  The value may have
       any  of	the  standard  forms for screen distances.  This option may be
       overridden  with	 -spacing2  options  in	 tags.	  [-spacing3 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.	[-startline 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 textual data store.	[-state state]	Speci‐
       fies  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.	[-tabs tabs] Specifies a set of tab stops for the window.  The
       option's	 value consists of a list of screen distances giving the posi‐
       tions 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 jus‐
       tify text relative to the tab stop.  Left is the default; it causes the
       text following the tab character to be positioned with its left edge at
       the tab position.  Right means that the right edge of the text  follow‐
       ing  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 posi‐
       tion.   For  example,  “-tabs {2c left 4c 6c center}” creates three tab
       stops at two-centimeter intervals;  the first two use  left  justifica‐
       tion 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
	      always  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”.
       [-tabstyle 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 tabular (the default) or wordprocessor.  Note  that  tabs
       are  interpreted 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 asso‐
       ciated  with the n'th tab stop defined for that line.  If the tab char‐
       acter'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 fallback.  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.  [-undo undo] Specifies a
       boolean that  says  whether  the	 undo  mechanism  is  active  or  not.
       [-width width]  Specifies  the desired width for the window in units of
       characters 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.  [-wrap wrap]	Speci‐
       fies  how to handle lines in the text that are too long to be displayed
       in a single line of the text's window.  The value must be none or  char
       or  word.   A wrap mode of none means that each line of text appears as
       exactly one line on the screen;	extra characters that do  not  fit  on
       the  screen  are	 not  displayed.  In the other modes each line of text
       will be broken up into several screen lines if necessary	 to  keep  all
       the  characters	visible.   In  char mode a screen line break may occur
       after any character; in word mode a line break will  only  be  made  at
       word boundaries.
_________________________________________________________________

DESCRIPTION
       The  text 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
       relief.	The text command returns the path name of the new window.

       A  text	widget displays one or more lines of text and allows that text
       to be edited.  Text widgets support four different kinds of annotations
       on  the	text, called tags, marks, embedded windows or embedded images.
       Tags allow different portions of the text to be displayed with  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
       details.

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

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

       The  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
		   embedded 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
		   embedded image by the given name.

       If the base could match more than one of the above  forms,  such	 as  a
       mark and imageName both having the same value, then the form earlier in
       the above list takes precedence.	 If modifiers follow the  base	index,
       each  one  of  them  must have one of the forms listed below.  Keywords
       such as chars and wordend may be abbreviated as long as	the  abbrevia‐
       tion 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 │
	      index 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  histori‐ │
	      cal  reasons,  if neither modifier is given then the count actu‐ │
	      ally takes place in units of index positions  (see  indices  for │
	      details).	  This	behaviour  may	be  changed  in a future major │
	      release, so if you need an index count, you  are	encouraged  to │
	      use indices instead 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 │
	      embedded	window.	  If  the display submodifier 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? 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 │
	      submodifier  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 │
	      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.

       - 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 posi‐ │
	      tion, adjust the character position to refer to the last charac‐ │
	      ter  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 count‐ │
	      ing 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 │
	      submodifier  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 │
	      index refers to the last character of the text then  it  is  not │
	      modified.	  If the display submodifier is given, this only exam‐ │
	      ines 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 │
       insertion  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
       indices.	 There may be any number of tags associated with characters in
       a  text.	  Each tag may refer to a single character, a range of charac‐
       ters, or several ranges of characters.	An  individual	character  may
       have any number of tags associated with it.

       A  priority  order  is  defined	among  tags, and this order is used in
       implementing some of the tag-related functions described below.	When a
       tag  is	defined (by associating it with characters or setting its 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
       using the “pathName tag raise” and “pathName  tag  lower”  widget  com‐
       mands.

       Tags serve three purposes in text widgets.  First, they control the way
       information is displayed on the screen.	 By  default,  characters  are
       displayed  as  determined  by  the  -background, -font, and -foreground
       options for the text widget.  However, display options may  be  associ‐
       ated  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 fol‐
       lowing options are currently 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_GetBitmap.  If bitmap has not been specified,	or  if	it  is
	      specified as an empty string, then a solid fill will be used for
	      the background.

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

       -elide boolean
	      Elide specifies whether the data should be elided.  Elided  data
	      (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	 char‐
	      acter 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 indentation 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
	      indented	from the left edge of the window.  Pixels may have any
	      of the standard forms for screen distances.  This option is only
	      used when wrapping is enabled, and it only applies to the second
	      and later display lines for a text line.

       -offset pixels
	      Pixels specifies an amount by which the text's  baseline	should
	      be  offset  vertically from the baseline of the overall line, in
	      pixels.  For example, a positive offset can be used  for	super‐
	      scripts  and a negative offset can be used for subscripts.  Pix‐
	      els 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 3-D relief to use for drawing  backgrounds,
	      in  any  of  the forms accepted by Tk_GetRelief.	This option is
	      used in conjunction with the -borderwidth option to give	a  3-D
	      appearance  to  the  background  for  characters;	 it is ignored
	      unless the -background option has been set for the tag.

       -rmargin pixels
	      If the first 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
	      character of that display line.

       -spacing1 pixels
	      Pixels  specifies how much additional space should be left above
	      each text line, using any of the standard forms for screen  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
	      requests default 8-character tabs as  described  for  the	 -tags
	      widget 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
       default 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	 bind‐ │
       ings 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 charac‐
       ters  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
       inserted at the point of the mark.  If a mark has  left	gravity,  then
       the  mark  is  treated  as  if it were attached to the character on its
       left, so the mark will remain to the left of any text inserted  at  the
       mark position.  If the mark has right gravity, new text inserted at the
       mark position will appear to the 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 dif‐
       ferent 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
       released).  Neither of these special marks may be  deleted.   With  the │
       exception 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
       windows	in  a  text  widget, and any widget may be used as an embedded
       window (subject to the  usual  rules  for  geometry  management,	 which
       require	the  text  window to be the parent of the embedded window or a
       descendant of its parent).   The	 embedded  window's  position  on  the
       screen will be updated as the text is modified or scrolled, and it will
       be mapped and unmapped as it moves into and out of the visible area  of
       the  text  widget.   Each  embedded window occupies one 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
       associated 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 dis‐
	      played.

       -padx pixels
	      Pixels specifies the amount of extra space to leave on each side
	      of  the  embedded	 window.   It  may have any of the usual forms
	      defined for a screen distance.

       -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 associa‐ │
	      tion  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
       particular  point  in   the  text.  There may be any number of embedded
       images in a text widget, and a particular image may be embedded in mul‐
       tiple places in the same text widget.  The embedded image's position on
       the screen will be updated as the text is modified or  scrolled.	  Each
       embedded	 image	occupies  one  unit's worth of index space in the text │
       widget, and it may be referred to either by its position	 in  the  wid‐
       get'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
       image  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
       instance.   The	name  is  taken	 to  be	 the value of the -name option
       (described below).  If the -name option is  not	provided,  the	-image
       name  is	 used instead.	If the imageName is already in use in the text
       widget, then #nn is added to the end of the imageName, where nn	is  an
       arbitrary  integer.   This  insures the imageName is unique.  Once this
       name is assigned to this instance of the image,	it  does  not  change,
       even  though  the  -image  or -name values can be changed with pathName
       image configure.

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

       -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
	      already in use, #nn is appended  to  the	end  of	 the  name  as
	      described above.

       -padx pixels
	      Pixels specifies the amount of extra space to leave on each side
	      of the embedded image.  It may  have  any	 of  the  usual	 forms
	      defined for a screen distance.

       -pady pixels
	      Pixels  specifies	 the amount of extra space to leave on the top
	      and on the bottom of the embedded image.	It may have any of the
	      usual forms defined for a screen distance.

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

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

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

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

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

       The sel tag is automatically defined when a text widget is created, and
       it  may	not  be deleted with the “pathName tag delete” widget command.
       Furthermore, the selectBackground, selectBorderWidth,  and  selectFore‐
       ground  options	for the text widget are tied to the -background, -bor‐
       derwidth, and -foreground options for the sel tag:  changes  in	either
       will  automatically  be	reflected in the other.	 Also the -inactivese‐ │
       lectbackground 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
       details.

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
       action 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	every‐
       thing  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 control.

       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
       automatically 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 │
       capabilities  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 │
       issues 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 │
       contain 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 com‐ │
       plete lines in the peer widget have been deleted from another  widget), │
       then it is impossible for new lines to be inserted.  The peer will sim‐ │
       ply become 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 │
       meaningful to the peer.	The configuration options -startline and -end‐ │
       line may be used to control how much of the  underlying	data  is  con‐ │
       tained 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
	      partially visible on the screen, then the return value  reflects
	      just  the	 visible part.	If the character is not visible on the
	      screen then the return value is an empty list.

       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
	      operators	 <,  <=,  ==,  >=,  >,	or  !=.	 If op is == then 1 is
	      returned if the two indices refer to the same character,	if  op
	      is < then 1 is returned if index1 refers to an earlier character
	      in the text than index2, and so on.

       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 │
	      option given.  Valid counting options are -chars, -displaychars, │
	      -displayindices, -displaylines, -indices, -lines,	 -xpixels  and │
	      -ypixels.	 The  default  value,  if  no  option is specified, is │
	      -indices. 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 fol‐ │
	      lows:							       │

	      -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 │
		     enabled), 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 │
		     display line, zero will be returned.  To count the	 total │
		     number  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
		     arguments 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
		     results. Tag information is returned as tagon and	tagoff
		     elements that indicate the begin and end of each range of
		     each tag, respectively.

	      -text  Include information about text in the dump results.   The
		     value  is	the  text up to the next element or the end of
		     range indicated by index2.	 A text element does not  span
		     newlines.	 A  multi-line	block of text that contains no
		     marks or tag transitions will still be dumped as a set of
		     text  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  create 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
	      index2  is  omitted  then	 the  single  character	 at  index1 is
	      returned.	 If there are no characters  in	 the  specified	 range
	      (e.g.  index1 is past the end of the file or index2 is less than
	      or equal to index1) then an empty string is  returned.   If  the
	      specified	 range contains embedded windows, no information about
	      them is included in the  returned	 string.   If  multiple	 index
	      pairs  are  given, multiple ranges of text will be returned in a
	      list.  Invalid ranges will not be represented with empty strings
	      in  the  list.   The  ranges are returned in the order passed to
	      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 behav‐
	      ior of the command depends on the option argument	 that  follows
	      the  tag	argument.  The following forms of the command are cur‐
	      rently supported:

	      pathName image cget index option
		     Returns the value of a configuration option for an embed‐
		     ded  image.   Index  identifies  the  embedded image, and
		     option 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
		     describing 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 infor‐
		     mation 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
	      INDICES 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
	      after the last newline) then  the	 new  text  is	inserted  just
	      before  the  last	 newline  instead.  If there is a single chars
	      argument and no tagList, then the new text will receive any tags
	      that  are present on both the character before and the character
	      after the insertion point; if a tag is present on	 only  one  of
	      these  characters	 then  it will not be applied to the new text.
	      If tagList is specified then it consists of a list of tag names;
	      the new characters will receive all of the tags in this list and
	      no others, regardless of the tags present around	the  insertion
	      point.   If  multiple  chars-tagList argument pairs are present,
	      they produce the same effect as if a  separate  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
		     attached  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
		     index.

	      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
		     semantics mean that the pathName mark previous  operation
		     can  be used to step through all the marks in a text wid‐
		     get 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
		     arguments.	  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 │
		     include  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 │
	      insert for an explanation of  the	 handling  of  the  tagList... │
	      arguments, 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 gener‐ │
	      ated.							       │

	      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
		     command  is typically associated with mouse motion events
		     in the widget, to produce the effect of dragging the text
		     at high speed through the window.	The return value is an
		     empty string.

       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 follow‐
	      ing switches (or abbreviations thereof) may be specified to con‐
	      trol 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
		     default.

	      -regexp
		     Treat  pattern  as	 a  regular  expression	 and  match it
		     against the text using the rules for regular  expressions
		     (see the regexp command for details).  The default match‐ │
		     ing  automatically	 passes	 both  the   -lineanchor   and │
		     -linestop	 options   to	the   regexp   engine  (unless │
		     -nolinestop is used), so that ^$ match beginning 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 │
		     images,  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 │
		     example, 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
		     effect.

	      pathName tag bind tagName ?sequence? ?script?
		     This command associates script with the tag given by tag‐
		     Name.  Whenever the  event	 sequence  given  by  sequence
		     occurs 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
		     sequence and the substitutions performed on script before
		     invoking  it.   If all arguments are specified then a new
		     binding is created, replacing any	existing  binding  for
		     the  same sequence and tagName (if the first character of
		     script is “+” then script augments	 an  existing  binding
		     rather than replacing it).	 In this case the return value
		     is an empty string.  If script is omitted then  the  com‐
		     mand  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 trig‐
		     gers for a tag when the tag first becomes present on  the
		     current  character,  and a Leave event triggers for a tag
		     when it ceases to be present on  the  current  character.
		     Enter and Leave events can happen either because the cur‐
		     rent mark moved or because the character at that position
		     changed.  Note that these events are different than Enter
		     and Leave events for windows.  Mouse and keyboard	events
		     are  directed  to	the  current  character.  If a virtual
		     event is used in a binding, that binding can trigger only
		     if	 the  virtual event is defined by an underlying mouse-
		     related or keyboard-related event.

		     It is possible for the current character to have multiple
		     tags,  and	 for each of them to have a binding for a 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	 bind‐
		     ings  for a single tag, then the most specific binding is
		     chosen (see the manual entry for  the  bind  command  for
		     details).	 continue  and	break  commands within binding
		     scripts are processed in the same	way  as	 for  bindings
		     created with the bind command.

		     If	 bindings  are created for the widget as a whole using
		     the bind command, then those bindings will supplement the
		     tag  bindings.   The  tag bindings will be invoked first,
		     followed by bindings for the window as a whole.

	      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
		     contain  any  number of index1-index2 pairs.  If the last
		     index2 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  tag	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
		     describing 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 infor‐
		     mation 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
		     window, and 40% of the text is off-screen to  the	right.
		     The  fractions  refer only to the lines that are actually
		     visible in the window:  if the lines in  the  window  are
		     all  very	short,	so that they are entirely visible, the
		     returned fractions will be 0 and 1,  even	if  there  are
		     other lines in the text that are much wider than the win‐
		     dow.  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 indi‐
		     cates 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
		     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 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 -pick‐
		     place 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
       dependent on the value of the tcl_wordchars variable.  See tclvars(n).

       [1]    Clicking mouse button 1  positions  the  insertion  cursor  just
	      before the character underneath the mouse cursor, sets the input
	      focus to this widget, and clears any selection  in  the  widget.
	      Dragging with mouse button 1 strokes out a selection between the
	      insertion cursor and the character under the mouse.

       [2]    Double-clicking with mouse button 1 selects the word  under  the
	      mouse  and  positions  the  insertion cursor at the 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
	      adjusted 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 insertion cursor moves and  the  selection  is  extended  to
	      include  the new character.  Control-Left and Control-Right move
	      the insertion cursor by words, and Control-Shift-Left  and  Con‐
	      trol-Shift-Right	move  the  insertion  cursor by words and also
	      extend the selection.  Control-b and Control-f behave  the  same
	      as  Left	and Right, respectively.  Meta-b and Meta-f behave the
	      same as Control-Left and Control-Right, respectively.

       [10]   The Up and Down keys move the insertion cursor one  line	up  or
	      down  and	 clear	any  selection in the text.  If Up or Right is
	      typed with the Shift key down, then the insertion	 cursor	 moves
	      and  the	selection  is  extended	 to include the new character.
	      Control-Up and Control-Down move the insertion cursor  by	 para‐
	      graphs  (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 Con‐
	      trol-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.	  Con‐
	      trol-Shift-Home  moves  the insertion cursor to the beginning of
	      the text and also extends the selection to that point.

       [16]   Control-End and Meta-> move the insertion cursor to the  end  of
	      the  text and clear any selection in the widget.	Control-Shift-
	      End moves the cursor to the end of  the  text  and  extends  the
	      selection to that point.

       [17]   The Select key and Control-Space set the selection anchor to the
	      position of the insertion cursor.	 They do not affect  the  cur‐
	      rent selection.  Shift-Select and Control-Shift-Space adjust the
	      selection to the	current	 position  of  the  insertion  cursor,
	      selecting	 from  the anchor to the insertion cursor if there was
	      not any selection previously.

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

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

       [20]   The F16 key (labelled Copy on many Sun workstations)  or	Meta-w
	      copies the selection in the widget to the clipboard, if there is
	      a	 selection.   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 │
       positions  (which  included  characters,	 embedded windows and embedded │
       images).	 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 future 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
       number of other tags with the same properties.  In contrast,  there  is
       no  problem  with  having  thousands  of distinct tags if their overall
       ranges are localized and spread uniformly throughout the text.

       Very long text lines can be expensive, especially  if  they  have  many
       marks and tags within them.

       The display line with the insert cursor is redrawn each time the cursor
       blinks, which causes a steady stream  of	 graphics  traffic.   Set  the
       insertOffTime 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  cer‐ │
       tain  conditions	 the  search result might differ from that obtained by │
       applying the same regexp to the entire text from the widget in one  go. │
       For  example, when searching with a greedy regexp, the widget will con‐ │
       tinue to attempt to add extra lines to the match as long as one of  two │
       conditions  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 extra line would actually match, the text widget will return the │
       wrong result.  In practice this is a rare problem, but  it  can	occur, │
       for example:							       │
	      pack [text .t]						       │
       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]						       │
       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(n), scrollbar(n)

KEYWORDS
       text, widget, tkvars

Tk				      8.5			       text(n)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server AIX

List of man pages available for AIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net