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 charac-
              ters may not be inserted or deleted and  no  inser-
              tion  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 dis-
              tances 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 char-
              acter 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 path-
       Name argument) and makes it into  a  text  widget.   Addi-
       tional  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 dif-
       ferent fonts and colors.  In addition, Tcl commands can be
       associated with tags so that scripts are invoked when par-
       ticular  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  indi-
       cate  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  num-
                   bered  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 abbre-
       viation is unambiguous.

       + count chars
              Adjust the index forward by count characters,  mov-
              ing  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, mov-
              ing 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 con-
              sists of any number of adjacent characters that are
              letters,  digits, or underscores, or a single char-
              acter 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 cur-
              rent 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 asso-
       ciated 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  num-
       ber 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 wid-
       get.  However, display  options  may  be  associated  with
       individual  tags using the ``pathName tag configure'' wid-
       get command.  If a character has  been  tagged,  then  the
       display  options  associated  with  the  tag  override the
       default display style.  The  following  options  are  cur-
       rently supported for tags:

       -background color
              Color  specifies  the  background  color to use for
              characters 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.

       -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  under-
              lines.   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 jus-
              tify 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 dis-
              play 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 base-
              line 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.  Pix-
              els  may  have any of the standard forms for screen
              distances.

       -overstrike boolean
              Specifies whether or not to draw a horizontal  rule
              through the middle of characters.  Boolean may have
              any of the forms accepted by 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 appear-
              ance  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 pix-
              els 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 unspeci-
              fied 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  under-
              line 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 val-
              ues 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  dis-
       play 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 particu-
       lar  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  con-
       taining 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 right  of
       the mark.  The gravity for a mark defaults to right.

       The  name space for marks is different from that for tags:
       the same name may be used for both a mark and a  tag,  but
       they will refer to different things.

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


EMBEDDED WINDOWS
       The third form of annotation in text widgets is an  embed-
       ded window.  Each embedded window annotation causes a win-
       dow to be displayed at a particular point  in   the  text.
       There may be any number of embedded windows in a text wid-
       get, 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 win-
       dow'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 char-
       acter's worth of index space in the text  widget,  and  it
       may be referred to either by the name of its embedded win-
       dow 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  win-
              dow  within  the  range of the line), bottom (align
              the bottom of the window with  the  bottom  of  the
              line's  area), or baseline (align the bottom of the
              window with the baseline of the line).

       -create script
              Specifies a Tcl script that  may  be  evaluated  to
              create  the window for the annotation.  If no -win-
              dow 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  annota-
              tion 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 dis-
              tance.

       -pady pixels
              Pixels specifies the amount of extra space to leave
              on  the  top and on the bottom of the embedded win-
              dow.  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 ay
              line.  If this option  is  specified  as  an  empty
              string,  it cancels the option, leaving it unspeci-
              fied 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  under-
              line 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 val-
              ues 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  dis-
       play 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 particu-
       lar  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  con-
       taining 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 right  of
       the mark.  The gravity for a mark defaults to right.

       The  name space for marks is different from that for tags:
       the same name may be used for both a mark and a  tag,  but
       they will refer to different things.

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


EMBEDDED WINDOWS
       The third form of annotation in text widgets is an  embed-
       ded window.  Each embedded window annotation causes a win-
       dow to be displayed at a particular point  in   the  text.
       There may be any number of embedded windows in a text wid-
       get, 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 win-
       dow'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 char-
       acter's worth of index space in the text  widget,  and  it
       may be referred to either by the name of its embedded win-
       dow 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  win-
              dow  within  the  range of the line), bottom (align
              the bottom of the window with  the  bottom  of  the
              line's  area), or baseline (align the bottom of the
              window with the baseline of the line).

       -create script
              Specifies a Tcl script that  may  be  evaluated  to
              create  the window for the annotation.  If no -win-
              dow 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  annota-
              tion 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 dis-
              tance.

       -pady pixels
              Pixels specifies the amount of extra space to leave
              on  the  top and on the bottom of the embedded win-
              dow.  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 ay
              line.  If this option  is  specified  as  an  empty
              string,  it cancels the option, leaving it unspeci-
              fied 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  under-
              line 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 val-
              ues 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  dis-
       play 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 particu-
       lar  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  con-
       taining 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 right  of
       the mark.  The gravity for a mark defaults to right.

       The  name space for marks is different from that for tags:
       the same name may be used for both a mark and a  tag,  but
       they will refer to different things.

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


EMBEDDED WINDOWS
       The third form of annotation in text widgets is an  embed-
       ded window.  Each embedded window annotation causes a win-
       dow to be displayed at a particular point  in   the  text.
       There may be any number of embedded windows in a text wid-
       get, 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 win-
       dow'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 char-
       acter's worth of index space in the text  widget,  and  it
       may be referred to either by the name of its embedded win-
       dow 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  win-
              dow  within  the  range of the line), bottom (align
              the bottom of the window with  the  bottom  of  the
              line's  area), or baseline (align the bottom of the
              window with the baseline of the line).

       -create script
              Specifies a Tcl script that  may  be  evaluated  to
              create  the window for the annotation.  If no -win-
              dow 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  annota-
              tion 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 dis-
              tance.

       -pady pixels
              Pixels specifies the amount of extra space to leave
              on  the  top and on the bottom of the embedded win-
              dow.  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 ay
              line.  If this option  is  specified  as  an  empty
              string,  it cancels the option, leaving it unspeci-
              fied 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  under-
              line 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 val-
              ues 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  dis-
       play 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 particu-
       lar  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  con-
       taining 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 right  of
       the mark.  The gravity for a mark defaults to right.

       The  name space for marks is different from that for tags:
       the same name may be used for both a mark and a  tag,  but
       they will refer to different things.

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


EMBEDDED WINDOWS
       The third form of annotation in text widgets is an  embed-
       ded window.  Each embedded window annotation causes a win-
       dow to be displayed at a particular point  in   the  text.
       There may be any number of embedded windows in a text wid-
       get, 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 win-
       dow'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 char-
       acter's worth of index space in the text  widget,  and  it
       may be referred to either by the name of its embedded win-
       dow 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  win-
              dow  within  the  range of the line), bottom (align
              the bottom of the window with  the  bottom  of  the
              line's  area), or baseline (align the bottom of the
              window with the baseline of the line).

       -create script
              Specifies a Tcl script that  may  be  evaluated  to
              create  the window for the annotation.  If no -win-
              dow 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  annota-
              tion 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 dis-
              tance.

       -pady pixels
              Pixels specifies the amount of extra space to leave
              on  the  top and on the bottom of the embedded win-
              dow.  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 ay
              line.  If this option  is  specified  as  an  empty
              string,  it cancels the option, leaving it unspeci-
              fied 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  under-
              line 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 val-
              ues 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  dis-
       play 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 particu-
       lar  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  con-
       taining 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 right  of
       the mark.  The gravity for a mark defaults to right.

       The  name space for marks is different from that for tags:
       the same name may be used for both a mark and a  tag,  but
       they will refer to different things.

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


EMBEDDED WINDOWS
       The third form of annotation in text widgets is an  embed-
       ded window.  Each embedded window annotation causes a win-
       dow to be displayed at a particular point  in   the  text.
       There may be any number of embedded windows in a text wid-
       get, 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 win-
       dow'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 char-
       acter's worth of index space in the text  widget,  and  it
       may be referred to either by the name of its embedded win-
       dow 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  win-
              dow  within  the  range of the line), bottom (align
              the bottom of the window with  the  bottom  of  the
              line's  area), or baseline (align the bottom of the
              window with the baseline of the line).

       -create script
              Specifies a Tcl script that  may  be  evaluated  to
              create  the window for the annotation.  If no -win-
              dow 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  annota-
              tion 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 dis-
              tance.

       -pady pixels
              Pixels specifies the amount of extra space to leave
              on  the  top and on the bottom of the embedded win-
              dow.  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 ay
              line.  If this option  is  specified  as  an  empty
              string,  it cancels the option, leaving it unspeci-
              fied 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  under-
              line 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 val-
              ues 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  dis-
       play 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 particu-
       lar  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  con-
       taining 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 right  of
       the mark.  The gravity for a mark defaults to right.

       The  name space for marks is different from that for tags:
       the same name may be used for both a mark and a  tag,  but
       they will refer to different things.

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


EMBEDDED WINDOWS
       The third form of annotation in text widgets is an  embed-
       ded window.  Each embedded window annotation causes a win-
       dow to be displayed at a particular point  in   the  text.
       There may be any number of embedded windows in a text wid-
       get, 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 win-
       dow'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 char-
       acter's worth of index space in the text  widget,  and  it
       may be referred to either by the name of its embedded win-
       dow 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  win-
              dow  within  the  range of the line), bottom (align
              the bottom of the window with  the  bottom  of  the
              line's  area), or baseline (align the bottom of the
              window with the baseline of the line).

       -create script
              Specifies a Tcl script that  may  be  evaluated  to
              create  the window for the annotation.  If no -win-
              dow 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  annota-
              tion 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 dis-
              tance.

       -pady pixels
              Pixels specifies the amount of extra space to leave
              on  the  top and on the bottom of the embedded win-
              dow.  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 ay
              line.  If this option  is  specified  as  an  empty
              string,  it cancels the option, leaving it unspeci-
              fied 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  under-
              line 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 val-
              ues 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  dis-
       play 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 particu-
       lar  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  con-
       taining 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 right  of
       the mark.  The gravity for a mark defaults to right.

       The  name space for marks is different from that for tags:
       the same name may be used for both a mark and a  tag,  but
       they will refer to different things.

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


EMBEDDED WINDOWS
       The third form of annotation in text widgets is an  embed-
       ded window.  Each embedded window annotation causes a win-
       dow to be displayed at a particular point  in   the  text.
       There may be any number of embedded windows in a text wid-
       get, 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 win-
       dow'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 char-
       acter's worth of index space in the text  widget,  and  it
       may be referred to either by the name of its embedded win-
       dow 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  win-
              dow  within  the  range of the line), bottom (align
              the bottom of the window with  the  bottom  of  the
              line's  area), or baseline (align the bottom of the
              window with the baseline of the line).

       -create script
              Specifies a Tcl script that  may  be  evaluated  to
              create  the window for the annotation.  If no -win-
              dow 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  annota-
              tion 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 dis-
              tance.

       -pady pixels
              Pixels specifies the amount of extra space to leave
              on  the  top and on the bottom of the embedded win-
              dow.  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 ay
              line.  If this option  is  specified  as  an  empty
              string,  it cancels the option, leaving it unspeci-
              fied 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  under-
              line 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 val-
              ues 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  dis-
       play 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 particu-
       lar  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  con-
       taining 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 right  of
       the mark.  The gravity for a mark defaults to right.

       The  name space for marks is different from that for tags:
       the same name may be used for both a mark and a  tag,  but
       they will refer to different things.

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


EMBEDDED WINDOWS
       The third form of annotation in text widgets is an  embed-
       ded window.  Each embedded window annotation causes a win-
       dow to be displayed at a particular point  in   the  text.
       There may be any number of embedded windows in a text wid-
       get, 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 win-
       dow'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 char-
       acter's worth of index space in the text  widget,  and  it
       may be referred to either by the name of its embedded win-
       dow 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  win-
              dow  within  the  range of the line), bottom (align
              the bottom of the window with  the  bottom  of  the
              line's  area), or baseline (align the bottom of the
              window with the baseline of the line).

       -create script
              Specifies a Tcl script that  may  be  evaluated  to
              create  the window for the annotation.  If no -win-
              dow 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  annota-
              tion 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 dis-
              tance.

       -pady pixels
              Pixels specifies the amount of extra space to leave
              on  the  top and on the bottom of the embedded win-
              dow.  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 ay
              line.  If this option  is  specified  as  an  empty
              string,  it cancels the option, leaving it unspeci-
              fied 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  under-
              line 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 val-
              ues 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  dis-
       play 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 particu-
       lar  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  con-
       taining 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 right  of
       the mark.  The gravity for a mark defaults to right.

       The  name space for marks is different from that for tags:
       the same name may be used for both a mark and a  tag,  but
       they will refer to different things.

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


EMBEDDED WINDOWS
       T