NAME
       text - Create and manipulate text widgets

SYNOPSIS
       text pathName ?options?

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

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

WIDGET-SPECIFIC OPTIONS
       Command-Line Name:-height
       Database Name:  height
       Database Class: 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.

       Command-Line Name:-spacing1
       Database Name:  spacing1
       Database Class: Spacing1

              Requests additional space above each text  line  in
              the  widget,  using  any  of the standard forms for
              screen distances.  If a  line  wraps,  this  option
              only  applies  to  the  first  line on the display.
              This option may be overriden with -spacing1 options
              in tags.

       Command-Line Name:-spacing2
       Database Name:  spacing2
       Database Class: Spacing2

              For  lines  that wrap (so that they cover more than
              one line on  the  display)  this  option  specifies
              additional  space  to  provide  between the display
              lines that represent a single line  of  text.   The
              value may have any of the standard forms for screen
              distances.   This  option  may  be  overriden  with
              -spacing2 options in tags.

       Command-Line Name:-spacing3
       Database Name:  spacing3
       Database Class: Spacing3

              Requests  additional  space below each text line in
              the widget, using any of  the  standard  forms  for
              screen  distances.   If  a  line wraps, this option
              only applies to the last line on the display.  This
              option  may  be overriden with -spacing3 options in
              tags.

       Command-Line Name:-state
       Database Name:  state
       Database Class: State

              Specifies one of two states for the  text:   normal
              or   disabled.    If  the  text  is  disabled  then
              characters may not be inserted or  deleted  and  no
              insertion  cursor  will  be  displayed, even if the
              input focus is in the widget.

       Command-Line Name:-tabs
       Database Name:  tabs
       Database Class: Tabs

              Specifies a set of tab stops for the  window.   The
              option's   value  consists  of  a  list  of  screen
              distances giving the positions of  the  tab  stops.
              Each  position  may  optionally  be followed in the
              next list element by  one  of  the  keywords  left,
              right,  center,  or numeric, which specifies how to
              justify text relative to the tab stop.  Left is the
              default;  it  causes  the  text  following  the tab
              character to be positioned with its  left  edge  at
              the  tab position.  Right means that the right edge
              of  the  text  following  the  tab   character   is
              positioned  at  the  tab position, and center means
              that the text is  centered  at  the  tab  position.
              Numeric means that the decimal point in the text is
              positioned at the tab position;   if  there  is  no
              decimal  point  then the least significant digit of
              the number is positioned just to the  left  of  the
              tab  position;   if  there is no number in the text
              then  the  text  is  right-justified  at  the   tab
              position.   For  example,  -tabs  {2c  left  4c  6c
              center} creates three tab stops  at  two-centimeter
              intervals;   the  first  two use left justification
              and the third uses center  justification.   If  the
              list  of tab stops does not have enough elements to
              cover all of the tabs  in  a  text  line,  then  Tk
              extrapolates  new  tab  stops using the spacing and
              alignment from the last tab stop in the list.   The
              value of the tabs option may be overridden by -tabs
              options in tags.  If no -tabs option is  specified,
              or  if  it  is  specified as an empty list, then Tk
              uses default tabs spaced every eight (average size)
              characters.

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

              Specifies the desired width for the window in units
              of characters  in  the  font  given  by  the  -font
              option.   If  the font doesn't have a uniform width
              then the width of the character ``0''  is  used  in
              translating from character units to screen units.

       Command-Line Name:-wrap
       Database Name:  wrap
       Database Class: Wrap

              Specifies  how to handle lines in the text that are
              too long to be displayed in a single  line  of  the
              text's  window.   The value must be none or char or
              word.  A wrap mode of none means that each line  of
              text  appears  as  exactly  one line on the screen;
              extra characters that don't fit on the  screen  are
              not  displayed.   In  the  other modes each line of
              text will be broken up into several screen lines if
              necessary  to  keep all the characters visible.  In
              char mode a screen line break may occur  after  any
              character;  in  word mode a line break will only be
              made at word boundaries.


DESCRIPTION
       The text 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 configure
       aspects of the text such as its default  background  color
       and relief.  The text command returns the path name of the
       new window.

       A text widget displays one  or  more  lines  of  text  and
       allows  that text to be edited.  Text widgets support four
       different kinds of annotations on the text,  called  tags,
       marks,  embedded  windows  or embedded images.  Tags allow
       different portions  of  the  text  to  be  displayed  with
       different fonts and colors.  In addition, Tcl commands can
       be associated with tags so that scripts are  invoked  when
       particular  actions  such  as  keystrokes and mouse button
       presses occur in particular ranges of the text.  See  TAGS
       below for more details.

       The second form of annotation consists of marks, which are
       floating markers in the text.   Marks  are  used  to  keep
       track  of  various interesting positions in the text as it
       is edited.  See MARKS below for more details.

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

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


INDICES
       Many of the widget commands for texts  take  one  or  more
       indices  as  arguments.   An  index  is  a  string used to
       indicate a particular place within a text, such as a place
       to  insert  characters  or  one  endpoint  of  a  range of
       characters to delete.  Indices have the syntax
              base modifier modifier modifier ...
       Where base gives a starting point and the modifiers adjust
       the  index  from  the starting point (e.g. move forward or
       backward one character).  Every index must contain a base,
       but the modifiers are optional.

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

       line.char   Indicates  char'th  character  on  line  line.
                   Lines are numbered from 1 for consistency with
                   other UNIX programs that  use  this  numbering
                   scheme.    Within   a   line,  characters  are
                   numbered from 0.   If  char  is  end  then  it
                   refers  to the newline character that ends the
                   line.

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

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

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

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

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

       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
       abbreviation is unambiguous.

       + count chars
              Adjust  the  index  forward  by  count  characters,
              moving to later lines in the text if necessary.  If
              there are fewer than count characters in  the  text
              after  the current index, then set the index to the
              last character in the text.  Spaces on either  side
              of count are optional.

       - count chars
              Adjust  the  index  backward  by  count characters,
              moving to earlier lines in the text  if  necessary.
              If  there  are  fewer  than count characters in the
              text before the current index, then set  the  index
              to  the  first  character  in  the text.  Spaces on
              either side of count are optional.

       + count lines
              Adjust the index forward by count lines,  retaining
              the  same  character  position within the line.  If
              there are fewer than count  lines  after  the  line
              containing the current index, then set the index to
              refer to the same character position  on  the  last
              line  of  the  text.  Then, if the line is not long
              enough to contain  a  character  at  the  indicated
              character  position,  adjust the character position
              to refer to the last character  of  the  line  (the
              newline).   Spaces  on  either  side  of  count are
              optional.

       - count lines
              Adjust the index backward by count lines, retaining
              the  same  character  position within the line.  If
              there are fewer than count lines  before  the  line
              containing the current index, then set the index to
              refer to the same character position on  the  first
              line  of  the  text.  Then, if the line is not long
              enough to contain  a  character  at  the  indicated
              character  position,  adjust the character position
              to refer to the last character  of  the  line  (the
              newline).   Spaces  on  either  side  of  count are
              optional.

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

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

       wordstart
              Adjust the index to refer to the first character of
              the  word  containing  the  current  index.  A word
              consists of any number of adjacent characters  that
              are  letters,  digits,  or underscores, or a single
              character that is not one of these.

       wordend
              Adjust the index to refer  to  the  character  just
              after  the  last  one  of  the  word containing the
              current index.  If the current index refers to  the
              last character of the text then it is not modified.

       If more than one modifier is present then they are applied
       in  left-to-right order.  For example, the index ``end - 1
       chars'' refers to the next-to-last character in  the  text
       and  ``insert  wordstart  -  1 c'' refers to the character
       just before the first  one  in  the  word  containing  the
       insertion cursor.


TAGS
       The  first form of annotation in text widgets is a tag.  A
       tag is a textual string that is associated  with  some  of
       the  characters  in  a  text.   Tags may contain arbitrary
       characters, but it is probably best to avoid using the the
       characters  ``  '' (space), +, or -: these characters have
       special meaning in indices, so tags containing them  can't
       be  used  as  indices.   There  may  be any number of tags
       associated with characters in a text.  Each tag may  refer
       to  a  single character, a range of characters, or several
       ranges of characters.  An individual  character  may  have
       any number of tags associated with it.

       A  priority order is defined among tags, and this order is
       used in implementing some  of  the  tag-related  functions
       described below.  When a tag is defined (by associating it
       with characters or setting its display options or  binding
       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 commands.

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

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

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

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

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

       -fgstipple bitmap
              Bitmap specifies a bitmap that is used as a stipple
              pattern when  drawing  text  and  other  foreground
              information such as underlines.  It may have any of
              the forms  accepted  by  Tk_GetBitmap.   If  bitmap
              hasn't  been specified, or if it is specified as an
              empty string, then a solid fill will be used.

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

       -foreground color
              Color specifies the color to use when drawing  text
              and    other   foreground   information   such   as
              underlines.  It may have any of the forms  accepted
              by Tk_GetColor.

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


       -lmargin1 pixels
              If the first character of a text line has a tag for
              which this option has been specified,  then  pixels
              specifies how much the line should be indented from
              the left edge of the window.  Pixels may  have  any
              of  the  standard forms for screen distances.  If a
              line of text wraps, this option only applies to the
              first  line  on  the display;  the -lmargin2 option
              controls the indentation for subsequent lines.

       -lmargin2 pixels
              If the first character of a display line has a  tag
              for  which  this  option has been specified, and if
              the display line is not the first for its text line
              (i.e.,  the  text  line  has  wrapped), then pixels
              specifies how much the line should be indented from
              the  left  edge of the window.  Pixels may have any
              of the standard forms for screen  distances.   This
              option  is  only used when wrapping is enabled, and
              it only applies to the  second  and  later  display
              lines for a text line.

       -offset pixels
              Pixels  specifies  an  amount  by  which the text's
              baseline  should  be  offset  vertically  from  the
              baseline  of  the  overall  line,  in  pixels.  For
              example,  a  positive  offset  can  be   used   for
              superscripts  and a negative offset can be used for
              subscripts.  Pixels may have any  of  the  standard
              forms for screen distances.

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

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

       -rmargin pixels
              If  the first character of a display line has a tag
              for which this  option  has  been  specified,  then
              pixels specifies how wide a margin to leave between
              the end of the line  and  the  right  edge  of  the
              window.   Pixels may have any of the standard forms
              for screen distances.  This  option  is  only  used
              when  wrapping  is  enabled.  If a text line wraps,
              the right margin for each line on  the  display  is
              determined  by  the first character of that display
              line.

       -spacing1 pixels
              Pixels specifies how much additional  space  should
              be  left  above  each  text  line, using any of the
              standard forms for screen  distances.   If  a  line
              wraps,  this  option only applies to the first line
              on the display.

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

       -spacing3 pixels
              Pixels  specifies  how much additional space should
              be left below each text  line,  using  any  of  the
              standard  forms  for  screen  distances.  If a line
              wraps, this option only applies to the last line on
              the display.

       -tabs tabList
              TabList  specifies  a  set of tab stops in the same
              form as for the -tabs option for the  text  widget.
              This  option  only  applies to a display line if it
              applies to the  first  character  on  that  display
              line.   If  this  option  is  specified as an empty
              string,  it  cancels   the   option,   leaving   it
              unspecified  for  the  tag  (the  default).  If the
              option is specified as a non-empty string  that  is
              an  empty list, such as -tags { }, then it requests
              default 8-character tabs as described for the  tags
              widget option.

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

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

       If a character has several tags associated with it, and if
       their  display  options  conflict, then the options of the
       highest priority tag are used.  If  a  particular  display
       option  hasn't  been specified for a particular tag, or if
       it is specified as an empty string, then that option  will
       never  be  used;   the  next-highest-priority tag's option
       will used instead.   If  no  tag  specifies  a  particular
       display option, then the default style for the widget will
       be used.

       The second purpose for tags is event  bindings.   You  can
       associate bindings with a tag in much the same way you can
       associate  bindings  with  a   widget   class:    whenever
       particular  X  events  occur  on characters with the given
       tag, a given 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
       tag bind widget command below.

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


MARKS
       The  second  form of annotation in text widgets is a mark.
       Marks are used for  remembering  particular  places  in  a
       text.   They  are  something  like tags, in that they have
       names and they refer to places in the  file,  but  a  mark
       isn't  associated  with particular characters.  Instead, a
       mark is associated with the gap  between  two  characters.
       Only  a  single  position may be associated with a mark at
       any given time.  If  the  characters  around  a  mark  are
       deleted the mark will still remain;  it will just have new
       neighbor  characters.   In  contrast,  if  the  characters
       containing  a  tag are deleted then the tag will no longer
       have an association with characters in  the  file.   Marks
       may  be  manipulated  with  the  ``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 different things.

       Two marks have  special  significance.   First,  the  mark
       insert   is  associated  with  the  insertion  cursor,  as
       described under THE INSERTION CURSOR below.   Second,  the
       mark  current  is associated with the character closest to
       the mouse and is adjusted automatically to track the mouse
       position  and  any  changes to the text in the widget (one
       exception:  current is not updated in  response  to  mouse
       motions  if  a  mouse  button is down;  the update will be
       deferred until all  mouse  buttons  have  been  released).
       Neither of these special marks may be deleted.


EMBEDDED WINDOWS
       The  third  form  of  annotation  in  text  widgets  is an
       embedded window.  Each embedded window annotation causes a
       window to be displayed at a particular point in  the text.
       There may be any number of  embedded  windows  in  a  text
       widget,  and  any widget may be used as an embedded window
       (subject to the usual rules for geometry management, which
       require  the  text window to be the parent of the embedded
       window or a  descendant  of  its  parent).   The  embedded
       window's  position  on  the  screen will be updated as the
       text is modified or scrolled, and it will  be  mapped  and
       unmapped  as  it moves into and out of the visible area of
       the  text  widget.   Each  embedded  window  occupies  one
       character's  worth  of index space in the text widget, and
       it may be referred to either by the name of  its  embedded
       window or by its position in the widget's index space.  If
       the range  of  text  containing  the  embedded  window  is
       deleted then the window is destroyed.

       When an embedded window is added to a text widget with the
       window  create  widget  command,   several   configuration
       options  may  be associated with it.  These options may be
       modified later with the 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 displayed, this option determines  where  the
              window  is  displayed in the line.  Where must have
              one of the values top (align the top of the  window
              with  the  top  of  the  line),  center (center the
              window within the range of the line), bottom (align
              the  bottom  of  the  window with the bottom of the
              line's area), or baseline (align the bottom of  the
              window with the baseline of the line).

       -create script
              Specifies  a  Tcl  script  that may be evaluated to
              create  the  window  for  the  annotation.   If  no
              -window   option   has   been   specified  for  the
              annotation this script will be evaluated  when  the
              annotation  is about to be displayed on the screen.
              Script must create a window for the annotation  and
              return  the  name of that window as its result.  If
              the annotation's window  should  ever  be  deleted,
              script  will  be  evaluated again the next time the
              annotation is displayed.

       -padx pixels
              Pixels specifies the amount of extra space to leave
              on  each  side of the embedded window.  It may have
              any  of  the  usual  forms  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 vertically
              to fill its line.  If the  -pady  option  has  been
              specified  as well, then the requested padding will
              be retained even if the window is stretched.

       -window pathName
              Specifies the name of a window to  display  in  the
              annotation.


EMBEDDED IMAGES
       The  final  form  of  annotation  in  text  widgets  is an
       embedded image.  Each embedded image annotation causes  an
       image  to be displayed at a particular point in  the text.
       There may be any number  of  embedded  images  in  a  text
       widget, and a particular image may be embedded in multiple
       places in the same  text  widget.   The  embedded  image's
       position  on  the  screen  will  be updated as the text is
       modified or scrolled.  Each embedded  image  occupies  one
       character's  worth  of index space in the text widget, and
       it may be referred  to  either  by  its  position  in  the
       widget's  index space, or the name it is assigned when the
       image is inserted into the text widget widh 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
       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   image
       configure.

       When  an embedded image is added to a text widget with the
       image create widget command, several configuration options
       may  be associated with it.  These options may be modified
       later  with  the  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 displayed,  this  option  determines  where  the
              image  is  displayed  in the line.  Where must have
              one of the values top (align the top of  the  image
              with the top of the line), center (center the image
              within the range of the line),  bottom  (align  the
              bottom  of  the image with the bottom of the line's
              area), or baseline (align the bottom of  the  image
              with the baseline of the line).

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

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

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

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


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

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

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

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

       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 selectForeground
       options for the text widget are tied to  the  -background,
       -borderwidth,  and  -foreground  options  for the sel tag:
       changes in either will automatically be reflected  in  the
       other.


THE INSERTION CURSOR
       The  mark  named  insert  has special significance in text
       widgets.  It is defined automatically when a  text  widget
       is  created  and  it  may not be unset with the ``pathName
       mark unset'' widget command.  The insert  mark  represents
       the  position  of  the insertion cursor, and the insertion
       cursor will automatically be drawn at this point  whenever
       the text widget has the input focus.


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  widget'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 relationship is satisfied and
              0 if it isn't.  Op must be one of the operators  <,
              <=,  ==,  >=,  >,  or  !=.   If  op is == then 1 is
              returned if the  two  indices  refer  to  the  same
              character,  if op is < then 1 is returned if index1
              refers to an earlier character  in  the  text  than
              index2, and so on.


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

       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
              doesn't  specify  a position later in the text than
              index1 then no characters are deleted.   If  index2
              isn't specified then the single character at index1
              is  deleted.   It  is  not  allowable   to   delete
              characters  in  a  way  that  would  leave the text
              without a  newline  as  the  last  character.   The
              command returns an empty string.

       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, and window.  The corresponding value is the
              text, mark name, tag name,  or  window  name.   The
              index  information is the index of the start of the
              text, the mark, the tag transition, or the  window.
              One   or   more   of  the  following  switches  (or
              abbreviations thereof) may be specified to  control
              the dump:

              -all   Return information about all elements: text,
                     marks, tags, 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  seqments
                     that  each  end with a newline.  The newline
                     is part of the value.

              -window
                     Include information about  embedded  windows
                     in  the dump results.  The value of a window
                     is its Tk pathname, unless  the  window  has
                     not  been  created  yet.   (It  must  have a
                     create  script.)   In  this  case  an  empty
                     string  is  returned, and you must query the
                     window by its index  position  to  get  more
                     information.


       pathName get index1 ?index2?
              Return  a  range  of characters from the text.  The
              return value will be all the characters in the text
              starting  with  the  one  whose index is index1 and
              ending just before the one whose  index  is  index2
              (the character at index2 will not be returned).  If
              index2 is omitted  then  the  single  character  at
              index1  is returned.  If there are no characters in
              the specified range (e.g. index1 is past the end of
              the file or index2 is less than or equal to index1)
              then an empty string is returned.  If the specified
              range  contains  embedded  windows,  no information
              about them is included in the returned string.

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

              pathName image cget index option
                     Returns the value of a configuration  option
                     for an embedded 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  corresponding  sublist  of  the   value
                     returned if no option is specified).  If one
                     or more option-value  pairs  are  specified,
                     then   the   command   modifies   the  given
                     option(s) to have the  given  value(s);   in
                     this  case  the  command  returns  an  empty
                     string.  See EMBEDDED IMAGES for information
                     on the options that are supported.

              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
                     configure  the annotation.  Returns a unique
                     identifier that may be used as an  index  to
                     refer  to  this  image.  See EMBEDDED IMAGES
                     for information  on  the  options  that  are
                     supported,   and   a   description   of  the
                     identifier returned.

              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 character 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  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
              supported:

              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  immediately  after  that  mark.
                     This  can  still  return  a mark at the same
                     position if there are multiple marks at  the
                     same  index.   These semantics mean that the
                     mark next operation  can  be  used  to  step
                     through  all  the  marks in a text widget in
                     the  same  order  as  the  mark  information
                     returned  by  the dump operation.  If a mark
                     has been set to the special end index,  then
                     it  appears  to be after end with respect to
                     the mark next operation.  An empty string is
                     returned  if there are no marks after index.


              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 mark previous
                     operation can be used to  step  through  all
                     the  marks  in  a text widget in the reverse
                     order as the mark  information  returned  by
                     the  dump  operation.   An  empty  string is
                     returned if there are no marks before index.

              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 doesn't 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 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  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 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;   otherwise  an
              empty  string  is  returned.   One  or  more of the
              following switches (or abbreviations  thereof)  may
              be specified to control the search:

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

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

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

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

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

              -count varName
                     The argument following -count gives the name
                     of a variable; if  a  match  is  found,  the
                     number  of 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,
                     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.

              -elide Find  elidden  (hidden)  text  as  well.  By
                     default only displayed 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 must be entirely within a single
              line  of text.  For regular expression matching the
              newlines are removed from the  ends  of  the  lines
              before  matching:   use  the  $  feature in regular
              expressions to match the end of a line.  For  exact
              matching  the  newlines are retained.  If stopIndex
              is specified, the search stops at that  index:  for
              forward  searches,  no  match at or after stopIndex
              will be  considered;   for  backward  searches,  no
              match  earlier  in  the text than stopIndex will be
              considered.  If stopIndex is  omitted,  the  entire
              text will be searched: when the beginning or end of
              the text is reached, the search  continues  at  the
              other  end  until  the starting location is reached
              again;  if stopIndex is specified,  no  wrap-around
              will occur.

       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
              supported:

              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
                     isn't tagged).  A single command may contain
                     any  number  of index1-index2 pairs.  If the
                     last  index2  is  omitted  then  the  single
                     character at index1 is tagged.  If there are
                     no characters in the specified  range  (e.g.
                     index1 is past the end of the file or index2
                     is less than or equal to  index1)  then  the
                     command has no effect.

              pathName tag bind tagName ?sequence? ?script?
                     This  command associates script with the tag
                     given  by  tagName.   Whenever   the   event
                     sequence  given  by  sequence  occurs  for a
                     character that has been tagged with tagName,
                     the  script  will  be  invoked.  This widget
                     command  is  similar  to  the  bind  command
                     except  that  it operates on characters 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  command  returns the
                     script associated with tagName and  sequence
                     (an   error  occurs  if  there  is  no  such
                     binding).  If both script and  sequence  are
                     omitted  then  the command returns a list of
                     all the sequences for  which  bindings  have
                     been defined for tagName.

                     The  only  events  for which bindings may be
                     specified are those related to the mouse and
                     keyboard (such as Enter, Leave, ButtonPress,
                     Motion, and  KeyPress)  or  virtual  events.
                     Event  bindings  for  a  text widget use the
                     current mark described  under  MARKS  above.
                     An  Enter  event triggers for a tag when the
                     tag first becomes  present  on  the  current
                     character,  and a Leave event triggers for a
                     tag when it ceases  to  be  present  on  the
                     current  character.   Enter and Leave events
                     can happen either because the  current  mark
                     moved  or  because  the  character  at  that
                     position changed.  Note  that  these  events
                     are  different  than  Enter and Leave events
                     for windows.  Mouse and keyboard events  are
                     directed  to  the  current  character.  If a
                     virtual event is used  in  a  binding,  that
                     binding  can  trigger  only  if  the virtual
                     event is defined  by  an  underlying  mouse-
                     related or keyboard-related event.

                     It  is possible for the current character to
                     have multiple tags, and for each of them  to
                     have   a  binding  for  a  particular  event
                     sequence.  When this occurs, one binding  is
                     invoked  for each tag, in order from lowest-
                     priority to highest priority.  If there  are
                     multiple matching bindings for a single tag,
                     then the most  specific  binding  is  chosen
                     (see  the  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 tag configure
                     widget command.

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

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

              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 haven't been deleted by a ``pathName 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
                     command's return value is a list  containing
                     two  elements,  which  are  the index of the
                     first character of the range and  the  index
                     of  the character just after the last one in
                     the range.  If no matching  range  is  found
                     then  the  return  value is an empty string.
                     If index2 is not given then it  defaults  to
                     the end of the text.

              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  starting  at  index1  and ending
                     just before index2 (the character at  index2
                     isn't   affected).   A  single  command  may
                     contain any number of  index1-index2  pairs.
                     If  the  last  index2  is  omitted  then the
                     single character at index1  is  tagged.   If
                     there  are  no  characters  in the specified
                     range (e.g. index1 is past the  end  of  the
                     file  or  index2  is  less  than or equal to
                     index1) then  the  command  has  no  effect.
                     This command returns an empty string.

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

              pathName window cget index option
                     Returns  the value of a configuration option
                     for an embedded  window.   Index  identifies
                     the  embedded window, and option specifies a
                     particular configuration option, which  must
                     be  one  of  the  ones listed in 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   corresponding  sublist  of  the  value
                     returned if no option is specified).  If one
                     or  more  option-value  pairs are specified,
                     then  the   command   modifies   the   given
                     option(s)  to  have  the given value(s);  in
                     this  case  the  command  returns  an  empty
                     string.     See    EMBEDDED    WINDOWS   for
                     information  on   the   options   that   are
                     supported.

              pathName window create index ?option value ...?
                     This    command   creates   a   new   window
                     annotation, which will appear in the text at
                     the  position given by index.  Any number of
                     option-value  pairs  may  be  specified   to
                     configure   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 windows 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 following 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  window.
                     These   are   the   same  values  passed  to
                     scrollbars via the -xscrollcommand option.

              pathName xview moveto fraction
                     Adjusts the  view  in  the  window  so  that
                     fraction  of the horizontal span of the text
                     is off-screen to the left.   Fraction  is  a
                     fraction between 0 and 1.

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

       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 following 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  character  in  the  top  line  in the
                     window, relative to the text as a whole (0.5
                     means  it  is  halfway through the text, for
                     example).   The  second  element  gives  the
                     position  of  the  character  just after the
                     last one in the bottom line of  the  window,
                     relative  to the text as a whole.  These are
                     the same values passed to scrollbars via the
                     -yscrollcommand option.

              pathName yview moveto fraction
                     Adjusts  the  view in the window so that the
                     character given by fraction appears  on  the
                     top  line  of  the  window.   Fraction  is a
                     fraction between 0 and 1;  0  indicates  the
                     first  character in the text, 0.33 indicates
                     the character one-third the way through  the
                     text, and so on.

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

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

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

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

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

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

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


              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  beginning  of  the word.  Dragging
              after a double click will stroke  out  a  selection
              consisting of whole words.

       [3]    Triple-clicking  with  mouse  button  1 selects the
              line under the mouse and  positions  the  insertion
              cursor  at  the  beginning  of  the line.  Dragging
              after a triple click will stroke  out  a  selection
              consisting of whole lines.

       [4]    The  ends  of  the  selection  can  be  adjusted by
              dragging with mouse button 1 while the Shift key is
              down;   this  will  adjust the end of the selection
              that was nearest to the mouse cursor when button  1
              was  pressed.   If  the  button  is  double-clicked
              before dragging then the selection will be adjusted
              in  units  of whole words;  if it is triple-clicked
              then the selection will be  adjusted  in  units  of
              whole lines.

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

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

       [7]    The  view in the widget can be adjusted by dragging
              with mouse button 2.  If mouse button 2 is  clicked
              without  moving  the mouse, the selection is copied
              into the text at the position of the mouse  cursor.
              The  Insert  key also inserts the selection, but at
              the position of the insertion cursor.

       [8]    If the mouse is dragged out  of  the  widget  while
              button  1  is pressed, the entry will automatically
              scroll to make more text visible (if there is  more
              text  off-screen  on  the side where the mouse left
              the window).

       [9]    The Left and Right keys move the  insertion  cursor
              one  character  to  the  left  or right;  they also
              clear any selection in the text.  If Left or  Right
              is   typed  with  the  Shift  key  down,  then  the
              insertion  cursor  moves  and  the   selection   is
              extended  to  include  the new character.  Control-
              Left and Control-Right move the insertion cursor by
              words,  and  Control-Shift-Left  and Control-Shift-
              Right move the insertion cursor by words  and  also
              extend  the  selection.   Control-b  and  Control-f
              behave the same as Left  and  Right,  respectively.
              Meta-b  and  Meta-f behave the same as Control-Left
              and Control-Right, respectively.

       [10]   The Up and Down keys move the insertion cursor  one
              line  up  or  down  and  clear any selection in the
              text.  If Up or Right is typed with the  Shift  key
              down,  then  the  insertion  cursor  moves  and the
              selection is extended to include the new character.
              Control-Up  and  Control-Down  move  the  insertion
              cursor by paragraphs (groups of lines separated  by
              blank  lines),  and  Control-Shift-Up  and Control-
              Shift-Down move the insertion cursor by  paragraphs
              and  also  extend  the  selection.   Control-p  and
              Control-n  behave  the  same  as   Up   and   Down,
              respectively.

       [11]   The  Next  and Prior keys move the insertion cursor
              forward or backwards by one screenful and clear any
              selection  in  the  text.  If the Shift key is held
              down  while  Next  or  Prior  is  typed,  then  the
              selection is extended to include the new character.
              Control-v moves the view down one screenful without
              moving   the  insertion  cursor  or  adjusting  the
              selection.

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

       [13]   Home and Control-a move the insertion cursor to the
              beginning  of  its  line and clear any selection in
              the widget.  Shift-Home moves the insertion  cursor
              to  the  beginning of the line and also extends the
              selection to that point.

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

       [15]   Control-Home  and  Meta-< move the insertion cursor
              to  the  beginning  of  the  text  and  clear   any
              selection  in the widget.  Control-Shift-Home moves
              the insertion cursor to the beginning of  the  text
              and also extends the selection to that point.

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

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

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

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

       [20]   The  F16   key   (labelled   Copy   on   many   Sun
              workstations) or Meta-w copies the selection in the
              widget to the clipboard, if there is a selection.

       [21]   The F20 key (labelled Cut on many Sun workstations)
              or  Control-w copies the selection in the widget to
              the clipboard and deletes the selection.  If  there
              is  no selection in the widget then these keys have
              no effect.

       [22]   The  F18  key   (labelled   Paste   on   many   Sun
              workstations)  or Control-y inserts the contents of
              the clipboard at  the  position  of  the  insertion
              cursor.

       [23]   The  Delete  key deletes the selection, if there is
              one in the widget.  If there is  no  selection,  it
              deletes the character to the right of the insertion
              cursor.

       [24]   Backspace and Control-h delete  the  selection,  if
              there  is  one  in  the  widget.   If  there  is no
              selection, they delete the character to the left of
              the insertion cursor.

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

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

       [27]   Control-k  deletes from the insertion cursor to the
              end of its line; if the insertion cursor is already
              at  the  end  of a line, then Control-k deletes the
              newline character.

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

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

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

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

       If  the  widget  is disabled using the -state option, then
       its view can still be  adjusted  and  text  can  still  be
       selected, but no insertion cursor will be displayed and no
       text modifications will take place.

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


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.

KEYWORDS
