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

       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,
              moving to later lines in the text if necessary.  If
              there are fewer than count characters in  the  text
              after  the current index, then set the index to the
              last character in the text.  Spaces on either  side
              of count are optional.

       - count chars
              Adjust the index backward by count characters, 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_Get-
              Boolean.  If the value is a true one then  internal
              consistency  checks will be turned on in the B-tree
              code associated with text widgets.  If boolean  has
              a  false  value  then  the debugging checks will be
              turned off.  In either case the command returns  an
              empty string.  If boolean is not specified then the
              command returns on or off to  indicate  whether  or
              not  debugging  is  turned  on.   There is a single
              debugging switch shared by all text widgets:  turn-
              ing  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
