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 three
       different  kinds  of annotations on the text, called tags,
       marks, and embedded windows.  Tags  allow  different  por-
       tions of the text to be displayed with different fonts and
       colors.  In addition, Tcl commands can be associated  with
       tags  so  that scripts are invoked when particular actions
       such as keystrokes and mouse button presses occur in  par-
       ticular  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.
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.

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

       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  win-
              dow.  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 deter-
              mined  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
       window 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
              window.  It may have any of the usual forms defined
              for a screen distance.

       -stretch boolean
              If the requested height of the embedded  window  is
              less  than  the  height  of the line in which it is
              displayed, this  option  can  be  used  to  specify
              whether  the  window should be stretched vertically
              to fill its line.  If the  -pady  option  has  been
              specified  as well, then the requested padding will
              be retained even if the window is stretched.

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


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

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

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

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

       The sel tag is automatically defined when a text widget is
       created, and it may not be deleted with the ``pathName tag
       delete'' widget  command.   Furthermore,  the  selectBack-
       ground,  selectBorderWidth,  and  selectForeground options
       for the text widget are tied to the -background,  -border-
       width,  and  -foreground options for the sel tag:  changes
       in either will automatically be reflected in the other.


THE INSERTION CURSOR
       The mark named insert has  special  significance  in  text
       widgets.   It  is defined automatically when a text widget
       is created and it may not be  unset  with  the  ``pathName
       mark  unset''  widget command.  The insert mark represents
       the position of the insertion cursor,  and  the  insertion
       cursor  will automatically be drawn at this point whenever
       the text widget has the input focus.
WIDGET COMMAND
       The text command creates a new Tcl command whose  name  is
       the same as the path name of the text's window.  This com-
       mand may be used to invoke various operations on the  wid-
       get.  It has the following general form:
              pathName option ?arg arg ...?
       PathName  is the name of the command, which is the same as
       the text widget's path name.  Option and the  args  deter-
       mine  the  exact  behavior  of the command.  The following
       commands are possible for text widgets:

       pathName bbox index
              Returns a list  of  four  elements  describing  the
              screen  area  of the character given by index.  The
              first two elements of the list give  the  x  and  y
              coordinates  of  the  upper-left corner of the area
              occupied by the character, and the  last  two  ele-
              ments  give  the  width and height of the area.  If
              the character is  only  partially  visible  on  the
              screen,  then  the  return  value reflects just the
              visible part.  If the character is not  visible  on
              the  screen then the return value is an empty list.

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

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

       pathName configure ?option? ?value option value ...?
              Query or modify the configuration  options  of  the
              widget.   If no option is specified, returns a list
              describing all of the available options  for  path-
              Name  (see  Tk_ConfigureInfo for information on the
              format of this list).  If option is specified  with
              no  value, then the command returns a list describ-
              ing the one named option (this list will be identi-
              cal  to  the  corresponding  sublist  of  the value
              returned if no option is  specified).   If  one  or
              more  option-value  pairs  are  specified, then the
              command modifies the given widget option(s) to have
              the  given  value(s);   in  this  case  the command
              returns an empty string.  Option may  have  any  of
              the values accepted by the text command.
       pathName debug ?boolean?
              If  boolean  is specified, then it must have one of
              the   true   or   false    values    accepted    by
              Tcl_GetBoolean.   If  the  value is a true one then
              internal consistency checks will be  turned  on  in
              the  B-tree  code associated with text widgets.  If
              boolean has a false value then the debugging checks
              will  be  turned  off.   In either case the command
              returns an empty string.  If boolean is not  speci-
              fied then the command returns on or off to indicate
              whether or not debugging is turned on.  There is  a
              single debugging switch shared by all text widgets:
              turning debugging on or off in any widget turns  it
              on  or off for all widgets.  For widgets with large
              amounts of text, the consistency checks may cause a
              noticeable slow-down.

       pathName delete index1 ?index2?
              Delete  a  range  of  characters from the text.  If
              both index1 and index2 are specified,  then  delete
              all  the  characters starting with the one given by
              index1 and stopping just before  index2  (i.e.  the
              character  at  index2  is  not deleted).  If index2
              doesn't specify a position later in the  text  than
              index1  then  no characters are deleted.  If index2
              isn't specified then the single character at index1
              is  deleted.  It is not allowable to delete charac-
              ters in a way that would leave the text  without  a
              newline as the last character.  The command returns
              an empty string.

       pathName dlineinfo index
              Returns a list with five  elements  describing  the
              area occupied by the display line containing index.
              The first two elements of the list give the x and y
              coordinates  of  the  upper-left corner of the area
              occupied by the line, the third and fourth elements
              give  the  width  and  height  of the area, and the
              fifth element gives the position  of  the  baseline
              for  the  line,  measured  down from the top of the
              area.  All of this information is measured in  pix-
              els.  If the current wrap mode is none and the line
              extends beyond the boundaries of  the  window,  the
              area returned reflects the entire area of the line,
              including the portions that are out of the  window.
              If  the  line is shorter than the full width of the
              window then the area  returned  reflects  just  the
              portion  of the line that is occupied by characters
              and embedded windows.  If the display line contain-
              ing  index  is  not  visible on the screen then the
              return value is an empty list.

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

              key1 value1 index1 key2 value2 index2 ...

              The  possible  key  values  are  text, mark, tagon,
              tagoff, and window.  The corresponding value is the
              text,  mark  name,  tag  name, or window name.  The
              index information is the index of the start of  the
              text,  the mark, the tag transition, or the window.
              One or more of the following switches (or abbrevia-
              tions  thereof)  may  be  specified  to control the
              dump:

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

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

              -mark  Include  information about marks in the dump
                     results.

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

              -text  Include information about text in  the  dump
                     results.   The  value  is the text up to the
                     next element or the end of  range  indicated
                     by  index2.   A  text  element does not span
                     newlines.  A multi-line block of  text  that
                     contains  no  marks  or tag transitions will
                     still be dumped as a set  of  text  seqments
                     that  each  end with a newline.  The newline
                     is part of the value.

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

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

       pathName index index
              Returns the position corresponding to index in  the
              form  line.char  where  line is the line number and
              char is the character number.  Index may  have  any
              of the forms described under INDICES above.

       pathName insert index chars ?tagList chars tagList ...?
              Inserts  all of the chars arguments just before the
              character at index.  If index refers to the end  of
              the  text  (the  character  after the last newline)
              then the new text is inserted just before the  last
              newline  instead.  If there is a single chars argu-
              ment and no tagList, then the new text will receive
              any  tags  that  are  present on both the character
              before and the character after the insertion point;
              if a tag is present on only one of these characters
              then it will not be applied to the  new  text.   If
              tagList  is specified then it consists of a list of
              tag names;  the new characters will receive all  of
              the  tags in this list and no others, regardless of
              the tags present around the  insertion  point.   If
              multiple  chars-tagList argument pairs are present,
              they produce the  same  effect  as  if  a  separate
              insert  widget  command  had  been  issued for each
              pair, in order.  The last tagList argument  may  be
              omitted.

       pathName mark option ?arg arg ...?
              This  command  is  used  to  manipulate marks.  The
              exact behavior of the command depends on the option
              argument  that follows the mark argument.  The fol-
              lowing forms of  the  command  are  currently  sup-
              ported:

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

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

              pathName mark next index
                     Returns  the  name  of  the  next mark at or
                     after  index.   If  index  is  specified  in
                     numerical form, then the search for the next
                     mark begins at that index.  If index is  the
                     name of a mark, then the search for the next
                     mark begins  immediately  after  that  mark.
                     This  can  still  return  a mark at the same
                     position if there are multiple marks at  the
                     same  index.   These semantics mean that the
                     mark next operation  can  be  used  to  step
                     through  all  the  marks in a text widget in
                     the  same  order  as  the  mark  information
                     returned  by  the dump operation.  If a mark
                     has been set to the special end index,  then
                     it  appears  to be after end with respect to
                     the mark next operation.  An empty string is
                     returned  if there are no marks after index.

              pathName mark previous index
                     Returns the name of the mark  at  or  before
                     index.   If  index is specified in numerical
                     form, then the search for the previous  mark
                     begins  with  the character just before that
                     index.  If index is the name of a mark, then
                     the  search for the next mark begins immedi-
                     ately before  that  mark.   This  can  still
                     return  a mark at the same position if there
                     are multiple marks at the same index.  These
                     semantics mean that the mark previous opera-
                     tion can be used to  step  through  all  the
                     marks  in a text widget in the reverse order
                     as the mark information returned by the dump
                     operation.   An  empty string is returned if
                     there are no marks before index.

              pathName mark set markName index
                     Sets the mark named markName to  a  position
                     just  before  the  character  at  index.  If
                     markName already exists, it  is  moved  from
                     its old position; if it doesn't exist, a new
                     mark is created.  This  command  returns  an
                     empty string.
              pathName mark unset markName ?markName markName
                     ...?
                     Remove the mark corresponding to each of the
                     markName  arguments.  The removed marks will
                     not be usable in indices  and  will  not  be
                     returned  by future calls to ``pathName mark
                     names''.   This  command  returns  an  empty
                     string.

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

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

              pathName scan dragto x y
                     This command computes the difference between
                     its x and y arguments and the x and y  argu-
                     ments  to the last scan mark command for the
                     widget.  It then  adjusts  the  view  by  10
                     times  the  difference in coordinates.  This
                     command is typically associated  with  mouse
                     motion  events in the widget, to produce the
                     effect of dragging the text  at  high  speed
                     through  the window.  The return value is an
                     empty string.

       pathName search ?switches? pattern index ?stopIndex?
              Searches the text in pathName starting at index for
              a  range  of characters that matches pattern.  If a
              match is found, the index of the first character in
              the  match  is  returned  as  result;  otherwise an
              empty string is returned.  One or more of the  fol-
              lowing  switches  (or abbreviations thereof) may be
              specified to control the search:

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

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

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

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

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

              -count varName
                     The argument following -count gives the name
                     of a variable; if a match is found, the num-
                     ber of characters in the matching range will
                     be stored in the variable.

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

              The matching range must be entirely within a single
              line  of text.  For regular expression matching the
              newlines are removed from the  ends  of  the  lines
              before  matching:   use  the  $  feature in regular
              expressions to match the end of a line.  For  exact
              matching  the  newlines are retained.  If stopIndex
              is specified, the search stops at that  index:  for
              forward  searches,  no  match at or after stopIndex
              will be  considered;   for  backward  searches,  no
              match  earlier  in  the text than stopIndex will be
              considered.  If stopIndex is  omitted,  the  entire
              text will be searched: when the beginning or end of
              the text is reached, the search  continues  at  the
              other  end  until  the starting location is reached
              again;  if stopIndex is specified,  no  wrap-around
              will occur.

       pathName see index
              Adjusts  the view in the window so that the charac-
              ter given by index is completely visible.  If index
              is  already  visible then the command does nothing.
              If index is a short distance out of view, the  com-
              mand  adjusts  the  view  just enough to make index
              visible at the edge of the window.  If index is far
              out  of view, then the command centers index in the
              window.

       pathName tag option ?arg arg ...?
              This command is used to manipulate tags.  The exact
              behavior  of  the  command  depends  on  the option
              argument that follows the tag argument.   The  fol-
              lowing  forms  of  the  command  are currently sup-
              ported:

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

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

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

                     It  is possible for the current character to
                     have multiple tags, and for each of them  to
                     have   a  binding  for  a  particular  event
                     sequence.  When this occurs, one binding  is
                     invoked  for each tag, in order from lowest-
                     priority to highest priority.  If there  are
                     multiple matching bindings for a single tag,
                     then the most  specific  binding  is  chosen
                     (see  the  manual entry for the bind command
                     for details).  continue and  break  commands
                     within  binding scripts are processed in the
                     same way as for bindings  created  with  the
                     bind command.

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

              pathName tag cget tagName option
                     This command returns the  current  value  of
                     the  option named option associated with the
                     tag given by tagName.  Option may  have  any
                     of  the values accepted by the tag configure
                     widget command.

              pathName tag configure tagName  ?option?  ?value?
                     ?option  value ...?
                     This command is  similar  to  the  configure
                     widget   command  except  that  it  modifies
                     options associated with  the  tag  given  by
                     tagName instead of modifying options for the
                     overall text widget.  If no option is speci-
                     fied,  the command returns a list describing
                     all of the  available  options  for  tagName
                     (see Tk_ConfigureInfo for information on the
                     format of this list).  If option  is  speci-
                     fied with no value, then the command returns
                     a list describing the one named option (this
                     list  will be identical to the corresponding
                     sublist of the value returned if  no  option
                     is  specified).  If one or more option-value
                     pairs are specified, then the command  modi-
                     fies  the  given option(s) to have the given
                     value(s) in tagName; in this case  the  com-
                     mand  returns  an  empty  string.   See TAGS
                     above for details on the  options  available
                     for tags.

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

              pathName tag lower tagName ?belowThis?
                     Changes  the priority of tag tagName so that
                     it is just lower in priority  than  the  tag
                     whose  name  is  belowThis.  If belowThis is
                     omitted, then tagName's priority is  changed
                     to make it lowest priority of all tags.

              pathName tag names ?index?
                     Returns  a list whose elements are the names
                     of all the tags that are active at the char-
                     acter  position given by index.  If index is
                     omitted, then the return value will describe
                     all  of  the  tags  that  exist for the text
                     (this includes all tags that have been named
                     in  a  ``pathName  tag''  widget command but
                     haven't been deleted  by  a  ``pathName  tag
                     delete''  widget command, even if no charac-
                     ters are currently  marked  with  the  tag).
                     The list will be sorted in order from lowest
                     priority to highest priority.

              pathName tag nextrange tagName index1 ?index2?
                     This command searches the text for  a  range
                     of  characters tagged with tagName where the
                     first character of the range is  no  earlier
                     than  the  character  at index1 and no later
                     than the character  just  before  index2  (a
                     range starting at index2 will not be consid-
                     ered).  If several  matching  ranges  exist,
                     the  first  one  is  chosen.   The command's
                     return value is a list containing  two  ele-
                     ments,  which  are  the  index  of the first
                     character of the range and the index of  the
                     character  just  after  the  last one in the
                     range.  If no matching range is  found  then
                     the  return  value  is  an empty string.  If
                     index2 is not given then it defaults to  the
                     end of the text.
              pathName tag prevrange tagName index1 ?index2?
                     This  command  searches the text for a range
                     of characters tagged with tagName where  the
                     first  character  of the range is before the
                     character at index1 and no earlier than  the
                     character  at  index2  (a  range starting at
                     index2  will  be  considered).   If  several
                     matching  ranges  exist,  the one closest to
                     index1  is  chosen.   The  command's  return
                     value  is  a  list  containing two elements,
                     which are the index of the  first  character
                     of  the range and the index of the character
                     just after the last one in the range.  If no
                     matching  range  is  found  then  the return
                     value is an empty string.  If index2 is  not
                     given  then  it defaults to the beginning of
                     the text.

              pathName tag raise tagName ?aboveThis?
                     Changes the priority of tag tagName so  that
                     it  is  just higher in priority than the tag
                     whose name is aboveThis.   If  aboveThis  is
                     omitted,  then tagName's priority is changed
                     to make it highest priority of all tags.

              pathName tag ranges tagName
                     Returns a list describing all of the  ranges
                     of  text that have been tagged with tagName.
                     The first two elements of the list  describe
                     the first tagged range in the text, the next
                     two elements describe the second range,  and
                     so  on.  The first element of each pair con-
                     tains the index of the  first  character  of
                     the  range,  and  the  second element of the
                     pair contains the  index  of  the  character
                     just  after  the  last one in the range.  If
                     there are no characters tagged with tag then
                     an empty string is returned.

              pathName tag remove tagName index1 ?index2 index1
                     index2 ...?
                     Remove the tag tagName from all of the char-
                     acters  starting  at  index1 and ending just
                     before index2 (the character at index2 isn't
                     affected).  A single command may contain any
                     number of index1-index2 pairs.  If the  last
                     index2  is omitted then the single character
                     at index1 is tagged.  If there are no  char-
                     acters  in  the specified range (e.g. index1
                     is past the end of the  file  or  index2  is
                     less  than or equal to index1) then the com-
                     mand has no effect.  This command returns an
                     empty string.
       pathName window option ?arg arg ...?
              This  command  is  used to manipulate embedded win-
              dows.  The behavior of the command depends  on  the
              option argument that follows the tag argument.  The
              following forms of the command are  currently  sup-
              ported:

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

              pathName window configure index ?option value ...?
                     Query or modify  the  configuration  options
                     for  an  embedded  window.   If no option is
                     specified, returns a list describing all  of
                     the  available options for the embedded win-
                     dow  at  index  (see  Tk_ConfigureInfo   for
                     information on the format of this list).  If
                     option is specified with no value, then  the
                     command  returns  a  list describing the one
                     named option (this list will be identical to
                     the   corresponding  sublist  of  the  value
                     returned if no option is specified).  If one
                     or  more  option-value  pairs are specified,
                     then  the   command   modifies   the   given
                     option(s)  to  have  the given value(s);  in
                     this  case  the  command  returns  an  empty
                     string.   See  EMBEDDED WINDOWS for informa-
                     tion on the options that are supported.

              pathName window create index ?option value ...?
                     This command creates a  new  window  annota-
                     tion,  which  will appear in the text at the
                     position given  by  index.   Any  number  of
                     option-value  pairs may be specified to con-
                     figure the annotation.  See EMBEDDED WINDOWS
                     for information on the options that are sup-
                     ported.  Returns an empty string.

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

       pathName xview option args
              This command is used to query and change the  hori-
              zontal position of the text in the widget's window.
              It can take any of the following forms:

              pathName xview
                     Returns  a  list  containing  two  elements.
                     Each  element  is  a real fraction between 0
                     and 1;  together they describe  the  portion
                     of  the  document's  horizontal span that is
                     visible in the window.  For example, if  the
                     first  element  is .2 and the second element
                     is .6, 20% of the text is off-screen to  the
                     left,  the middle 40% is visible in the win-
                     dow, and 40% of the text  is  off-screen  to
                     the  right.  The fractions refer only to the
                     lines that are actually visible in the  win-
                     dow:   if  the  lines  in the window are all
                     very short, so that they are entirely  visi-
                     ble, the returned fractions will be 0 and 1,
                     even if there are other lines  in  the  text
                     that  are much wider than the window.  These
                     are the same values passed to scrollbars via
                     the -xscrollcommand option.

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

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

       pathName yview ?args?
              This command is used to query and change the verti-
              cal position of the text in  the  widget's  window.
              It can take any of the following forms:

              pathName yview
                     Returns a list containing two elements, both
                     of which are real fractions between 0 and 1.
                     The  first element gives the position of the
                     first character in the top line in the  win-
                     dow,  relative  to  the text as a whole (0.5
                     means it is halfway through  the  text,  for
                     example).   The  second  element  gives  the
                     position of the  character  just  after  the
                     last  one  in the bottom line of the window,
                     relative to the text as a whole.  These  are
                     the same values passed to scrollbars via the
                     -yscrollcommand option.

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

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

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

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

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

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

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

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

              pathName yview number
                     This command makes the  first  character  on
                     the line after the one given by number visi-
                     ble at the top of the window.   Number  must
                     be an integer.  This command used to be used
                     for scrolling, but now it is obsolete.


BINDINGS
       Tk automatically creates class  bindings  for  texts  that
       give them the following default behavior.  In the descrip-
       tions below, ``word'' refers to a contiguous group of let-
       ters, digits, or ``_'' characters, or any single character
       other than these.

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

       [2]    Double-clicking with mouse  button  1  selects  the
              word  under  the  mouse and positions the insertion
              cursor at the  beginning  of  the  word.   Dragging
              after  a  double  click will stroke out a selection
              consisting of whole words.

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

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

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

       [6]    If any normal printing characters are  typed,  they
              are  inserted at the point of the insertion cursor.
       [7]    The view in the widget can be adjusted by  dragging
              with  mouse button 2.  If mouse button 2 is clicked
              without moving the mouse, the selection  is  copied
              into  the text at the position of the mouse cursor.
              The Insert key also inserts the selection,  but  at
              the position of the insertion cursor.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       [23]   The Delete key deletes the selection, if  there  is
              one  in  the  widget.  If there is no selection, it
              deletes the character to the right of the insertion
              cursor.
       [24]   Backspace  and  Control-h  delete the selection, if
              there is one in the widget.  If there is no  selec-
              tion,  they delete the character to the left of the
              insertion cursor.

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

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

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

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

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

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

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

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

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


PERFORMANCE ISSUES
       Text  widgets  should  run  efficiently under a variety of
       conditions.  The text widget uses about 2-3 bytes of  main
       memory  for  each  byte  of  text,  so  texts containing a
       megabyte or more should be practical on most workstations.
       Text  is  represented  internally  with  a modified B-tree
       structure that makes operations relatively efficient  even
       with  large texts.  Tags are included in the B-tree struc-
       ture in a way that allows tags to  span  large  ranges  or
       have  many  disjoint  smaller ranges without loss of effi-
       ciency.  Marks are also implemented in a way  that  allows
       large  numbers of marks.  In most cases it is fine to have
       large numbers of unique tags, or a tag that has many  dis-
       tinct ranges.
       One  performance problem can arise if you have hundreds or
       thousands of different tags that all  have  the  following
       characteristics: the first and last ranges of each tag are
       near the beginning and end of the text, respectively, or a
       single tag range covers most of the text widget.  The cost
       of adding and deleting tags like this is  proportional  to
       the  number  of  other  tags with the same properties.  In
       contrast, there is no problem  with  having  thousands  of
       distinct  tags  if  their overall ranges are localized and
       spread uniformly throughout the text.

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

       The  display  line  with the insert cursor is redrawn each
       time the cursor blinks, which causes a  steady  stream  of
       graphics  traffic.   Set  the insertOffTime attribute to 0
       avoid this.

KEYWORDS
       text, widget
