NAME
       text - Create and manipulate text widgets

SYNOPSIS
       text pathName ?options?

STANDARD OPTIONS
       background      foreground     insertWidth     selectBorderWidth
       borderWidth     insertBackground               padXselectForeground
       cursor          insertBorderWidth              padYsetGrid
       exportSelection insertOffTime  relief          yScrollCommand
       font            insertOnTime   selectBackground

       See  the ``options'' manual entry for details on the stan-
       dard options.

WIDGET-SPECIFIC OPTIONS
       Name:           height
       Class:          Height
       Command-Line Switch:           -height

              Specifies the desired height  for  the  window,  in
              units of characters.  Must be at least one.

       Name:           state
       Class:          State
       Command-Line Switch:           -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.

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

              Specifies the desired width for the window in units
              of characters.  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.

       Name:           wrap
       Class:          Wrap
       Command-Line Switch:           -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 windows.  Tags allow different portions of the
       text to be displayed with different fonts and colors.   In
       addition, Tcl commands can be associated with tags so that
       commands are  invoked  when  particular  actions  such  as
       keystrokes  and  mouse  button presses occur in particular
       ranges of the text.  See TAGS below for more details.

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

       The  third  form of annotation allows arbitrary windows to
       be displayed in the text widget.  See  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  last  character  in  the text,
                   which is always a newline character.

       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.

       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.  There may be any number of tags
       associated with characters in a text.  Each tag may  refer
       to  a  single character, a range of characters, or several
       ranges of characters.  An individual  character  may  have
       any number of tags associated with it.

       A  priority order is defined among tags, and this order is
       used in implementing some  of  the  tag-related  functions
       described below.  When a tag is defined (by associating it
       with characters or setting its display options or  binding
       commands  to  it),  it is given a priority higher than any
       existing tag.  The priority order of tags may be redefined
       using  the  ``pathName  tag  raise''  and  ``pathName  tag
       lower'' widget commands.

       Tags serve three purposes in text  widgets.   First,  they
       control  the  way  information is displayed on the screen.
       By default, characters are displayed as determined by  the
       background, font, and foreground options for the text 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.

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

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

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

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


WINDOWS
       The third form of annotation in text widgets is a  window.
       Window  support  isn't  implemented yet, but when it is it
       will be described here.


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

       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
              Inserts chars into the text just before the charac-
              ter at index and returns an empty  string.   It  is
              not  possible  to  insert characters after the last
              newline of the text.

       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 names
                     Returns a list whose elements are the  names
                     of all the marks that are currently set.

              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 y
                     Records  y  and the current view in the text
                     window;  used 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 y
                     This command computes the difference between
                     its y argument and the  y  argument  to  the
                     last  scan  mark command for the widget.  It
                     then adjusts the view up or down by 10 times
                     the  difference in y-coordinates.  This com-
                     mand  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 tag option ?arg arg ...?
              This command is used to manipulate tags.  The exact
              behavior of the command depends on the option argu-
              ment that follows the tag argument.  The  following
              forms of the command are currently supported:

              pathName tag add tagName 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).  If index2  is  omitted  then
                     the  single  character  at index1 is tagged.
                     If there are no characters in the  specified
                     range  (e.g.  index1  is past the end of the
                     file or index2 is  less  than  or  equal  to
                     index1)  then  the  command  has  no effect.
                     This command returns an empty string.

              pathName tag bind tagName ?sequence? ?command?
                     This command associates command with the tag
                     given   by   tagName.   Whenever  the  event
                     sequence given  by  sequence  occurs  for  a
                     character that has been tagged with tagName,
                     the command 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 command 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 command is ``+'' then
                     command  augments an existing binding rather
                     than replacing it).  In this case the return
                     value  is  an  empty  string.  If command is
                     omitted then the command returns the command
                     associated  with  tagName  and  sequence (an
                     error occurs if there is no  such  binding).
                     If  both  command  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.  Enter events trigger for
                     a character  when  it  becomes  the  current
                     character  (i.e.  the  current mark moves to
                     just in front  of  that  character).   Leave
                     events  trigger  for  a  character  when  it
                     ceases to be the current item (i.e. the cur-
                     rent mark moves away from that character, or
                     the character is deleted).  These events are
                     different  than  Enter  and Leave events for
                     windows.   Mouse  and  keyboard  events  are
                     directed to the current character.

                     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,  the  binding
                     from the highest priority tag is used.  If a
                     particular tag doesn't have a  binding  that
                     matches  an  event,  then the tag is ignored
                     and  tags  with  lower  priority   will   be
                     checked.

                     If  bindings are created for the widget as a
                     whole using the  bind  command,  then  those
                     bindings  will  supplement the tag bindings.
                     This means that a single event  can  trigger
                     two  Tcl  scripts,  one  for  a widget-level
                     binding and one for a tag-level binding.

              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.

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

              pathNametag 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?
                     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).   If  index2  is omitted then the
                     single character at index1 is untagged.   If
                     there  are  no  characters  in the specified
                     range (e.g. index1 is past the  end  of  the
                     file  or  index2  is  less  than or equal to
                     index1) then  the  command  has  no  effect.
                     This command returns an empty string.

       pathName yview ?-pickplace? what
              This  command changes the view in the widget's win-
              dow so that the line given by what  is  visible  in
              the  window.   What  may be either an absolute line
              number, where 0 corresponds to the  first  line  of
              the  file,  or  an  index  with  any  of  the forms
              described under  INDICES  above.   The  first  form
              (absolute  line  number)  is  used  in the commands
              issued by scrollbars to control the widget's  view.
              If  the -pickplace option isn't specified then what
              will appear at the top of the  window.   If  -pick-
              place  is  specified  then the widget chooses where
              what appears in the window:

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

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

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

              [4]    Otherwise, what will be centered in the win-
                     dow.

              The  -pickplace  option  is  typically  used  after
              inserting text to make sure that the insertion cur-
              sor is still visible on the screen.   This  command
              returns an empty string.
BINDINGS
       Tk  automatically  creates  class  bindings for texts that
       give them the following default behavior:

       [1]    Pressing mouse button 1 in an  text  positions  the
              insertion  cursor  just before the character under-
              neath the mouse cursor and sets the input focus  to
              this widget.

       [2]    Dragging  with  mouse button 1 strokes out a selec-
              tion between the insertion cursor and the character
              under the mouse.

       [3]    If  you  double-press  mouse button 1 then the word
              under the mouse cursor will be selected, the inser-
              tion  cursor will be positioned at the beginning of
              the word, and dragging the mouse will stroke out  a
              selection whole words at a time.

       [4]    If  you  triple-press  mouse button 1 then the line
              under the mouse cursor will be selected, the inser-
              tion  cursor will be positioned at the beginning of
              the line, and dragging the mouse will stroke out  a
              selection whole line at a time.

       [5]    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 selection was made in word or
              line mode then it will be  adjusted  in  this  same
              mode.

       [6]    The  view  in  the text can be adjusted by dragging
              with mouse button 2.

       [7]    If the input focus is in a text widget and  charac-
              ters  are typed on the keyboard, the characters are
              inserted just before the insertion cursor.

       [8]    Control+h and the Backspace and Delete  keys  erase
              the character just before the insertion cursor.

       [9]    Control+v inserts the current selection just before
              the insertion cursor.

       [10]   Control+d  deletes  the  selected  characters;   an
              error  occurs  if the selection is not in this wid-
              get.

       If the text is disabled using the state option,  then  the
       text's view can still be adjusted and text in the text can
       still be selected, but no insertion cursor  will  be  dis-
       played 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.  The only known mode of operation
       where a text widget may not run efficiently is if it has a
       very  large  number  of  different tags.  Hundreds of tags
       should be fine, or even a thousand, but tens of  thousands
       of  tags  will  make texts consume a lot of memory and run
       slowly.


KEYWORDS
       text, widget
