tk4.2 User Commands - text






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 dis-
          tances.  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 dis-
          tances.  If a line wraps, this option only  applies  to
          the last line on the display.  This option may be over-
          riden with -spacing3 options in tags.

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

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

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

          Specifies a set of  tab  stops  for  the  window.   The
          option's  value  consists of a list of screen distances
          giving the positions of the tab stops.   Each  position
          may  optionally be followed in the next list element by
          one of the keywords left, right,  center,  or  numeric,
          which specifies how to justify text relative to the tab
          stop.  Left is the default; it causes the text  follow-
          ing  the  tab  character to be positioned with its left
          edge at the tab position.  Right means that  the  right
          edge  of  the text following the tab character is posi-
          tioned 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 charac-
          ter 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 char-
          acters visible.  In char mode a screen line  break  may
          occur  after  any  character; in word mode a line break
          will only be made at word boundaries.





DESCRIPTION

     The text command creates a new window (given by the pathName
     argument)  and  makes  it  into  a  text widget.  Additional
     options, described above, may be specified  on  the  command
     line  or  in the option database to configure aspects of the
     text such as its default background color and  relief.   The
     text command returns the path name of the new window.

     A text widget displays one or more lines of text and  allows
     that  text  to  be  edited.  Text widgets support three dif-
     ferent kinds of annotations on the text, called tags, marks,
     and  embedded 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
     scripts are invoked when particular actions  such  as  keys-
     trokes  and  mouse button presses occur in particular ranges
     of the text.  See TAGS below for more details.

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

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



INDICES

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

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

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

     @x,y        Indicates the character that  covers  the  pixel
                 whose x and y coordinates within the text's win-
                 dow 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  abbreviation
     is unambiguous.

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

     - count chars
          Adjust the index backward by count  characters,  moving
          to  earlier  lines  in the text if necessary.  If there
          are fewer than count characters in the text before  the
          current  index, then set the index to the first charac-
          ter 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 charac-
          ter 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 char-
          acter at the indicated character position,  adjust  the
          character  position  to  refer to the last character of
          the line (the newline).  Spaces on either side of count
          are optional.

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

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

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

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

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



TAGS

     The first form of annotation in text widgets is  a  tag.   A
     tag  is a textual string that is associated with some of the
     characters in a text.  Tags may  contain  arbitrary  charac-
     ters, but it is probably best to avoid using the the charac-
     ters `` '' (space), +, or -:  these characters have  special
     meaning in indices, so tags containing them can't be used as
     indices.  There may be any number of  tags  associated  with
     characters  in a text.  Each tag may refer to a single char-
     acter, a range of characters, or several ranges  of  charac-
     ters.   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 con-
     trol  the  way  information  is displayed on the screen.  By
     default, characters are displayed as determined by the back-
     ground,  font,  and  foreground options for the text widget.
     However, display options may be associated  with  individual
     tags  using  the  ``pathName tag configure'' widget command.
     If a character has been tagged,  then  the  display  options
     associated  with the tag override the default display style.
     The following options are currently supported for tags:

     -background color
          Color specifies the background color to use for charac-
          ters  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  con-
          junction  with the -relief 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.

     -fgstipple bitmap
          Bitmap specifies a bitmap that is  used  as  a  stipple
          pattern when drawing text and other foreground informa-
          tion such as underlines.  It may have any of the  forms
          accepted by Tk_GetBitmap.  If bitmap hasn't been speci-
          fied, 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 char-
          acters.   It  may  have  any  of  the forms accepted by
          Tk_GetFontStruct.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     The second purpose for tags  is  event  bindings.   You  can
     associate  bindings  with a tag in much the same way you can
     associate bindings with a widget class:  whenever particular
     X events occur on characters with the given tag, a given Tcl
     command will be executed.  Tag bindings can be used to  give
     behaviors  to ranges of characters; among other things, this
     allows  hypertext-like  features  to  be  implemented.   For
     details,  see the description of the tag bind widget command
     below.


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



MARKS

     The second form of annotation in text  widgets  is  a  mark.
     Marks  are used for remembering particular places in a text.
     They are something like tags, in that they  have  names  and
     they  refer  to places in the file, but a mark isn't associ-
     ated with particular characters.  Instead, a mark is associ-
     ated  with  the  gap  between two characters.  Only a single
     position may be associated with a mark at  any  given  time.
     If  the  characters  around a mark are deleted the mark will
     still remain;  it will just have  new  neighbor  characters.
     In  contrast, if the characters containing a tag are deleted
     then the tag will no longer have an association with charac-
     ters in the file.  Marks may be manipulated with the ``path-
     Name 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 posi-
     tion.  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  but-
     ton  is  down;   the update will be deferred until all mouse
     buttons have been released).  Neither of these special marks
     may be deleted.



EMBEDDED WINDOWS

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

     When an embedded window is added to a text widget  with  the
     window  create widget command, several configuration options
     may be associated with it.  These options may  be   modified
     later with the window configure widget command.  The follow-
     ing options are currently supported:

     -align where
          If the window is not as tall as the line in which it is
          displayed,  this  option determines where the window is
          displayed in the line.  Where  must  have  one  of  the
          values top (align the top of the window with the top of
          the line), center (center the window within  the  range
          of  the  line),  bottom (align the bottom of the window
          with the bottom of the line's area), or baseline (align
          the  bottom  of  the  window  with  the baseline of the
          line).

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

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

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

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

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



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 application
          or  by another window within this application, then the
          sel tag will be removed  from  all  characters  in  the
          text.

     The sel tag is automatically defined when a text  widget  is
     created,  and  it may not be deleted with the ``pathName tag
     delete'' widget command.  Furthermore, the selectBackground,
     selectBorderWidth, and selectForeground options for the text
     widget are tied to the -background, -borderwidth, and -fore-
     ground  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 widg-
     ets.   It  is  defined  automatically  when a text widget is
     created and it may not be unset  with  the  ``pathName  mark
     unset''  widget  command.   The  insert  mark represents the
     position of the insertion cursor, and the  insertion  cursor
     will  automatically be drawn at this point whenever the text
     widget has the input focus.




WIDGET COMMAND

     The text command creates a new Tcl command whose name is the
     same  as  the  path name of the text's window.  This command
     may be used to invoke various operations on the widget.   It
     has the following general form:
          pathName option ?arg arg ...?
     PathName is the name of the command, which is  the  same  as
     the  text widget's path name.  Option and the args determine
     the exact behavior of the command.  The  following  commands
     are possible for text widgets:

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

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

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

     pathName configure ?option? ?value option value ...?
          Query  or  modify  the  configuration  options  of  the
          widget.   If  no  option  is  specified, returns a list
          describing all of the available  options  for  pathName
          (see  Tk_ConfigureInfo for information on the format of
          this list).  If option is specified with no value, then
          the  command  returns  a  list describing the one named
          option (this list will be identical to the  correspond-
          ing  sublist  of  the  value  returned  if no option is
          specified).  If one or more  option - value  pairs  are
          specified,  then  the command modifies the given widget
          option(s) to have the given value(s);  in this case the
          command  returns  an empty string.  Option may have any
          of the values accepted by the text command.

     pathName debug ?boolean?
          If boolean is specified, then it must have one  of  the
          true  or  false  values accepted by Tcl_GetBoolean.  If
          the value is  a  true  one  then  internal  consistency
          checks  will be turned on in the B-tree code associated
          with text widgets.  If boolean has a false  value  then
          the  debugging  checks  will  be turned off.  In either
          case the command returns an empty string.   If  boolean
          is  not specified then the command returns on or off to
          indicate whether or not debugging is turned on.   There
          is  a  single debugging switch shared by all text widg-
          ets:  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 charac-
          ters are deleted.  If index2 isn't specified  then  the
          single  character  at  index1  is  deleted.   It is not
          allowable to delete characters  in  a  way  that  would
          leave the text without a newline as the last character.
          The command returns an empty string.

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

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

          key1 value1 index1 key2 value2 index2 ...

          The possible key values are text, mark, tagon,  tagoff,
          and  window.  The corresponding value is the text, mark
          name, tag name, or window name.  The index  information
          is  the  index  of the start of the text, the mark, the
          tag transition, or the window.  One or more of the fol-
          lowing  switches  (or  abbreviations  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 evaluated:  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  new-
               line is part of the value.

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

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

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

     pathName insert index chars ?tagList chars tagList ...?
          Inserts all of the  chars  arguments  just  before  the
          character  at index.  If index refers to the end of the
          text (the character after the last  newline)  then  the
          new  text  is  inserted  just  before  the last newline
          instead.  If there is a single chars  argument  and  no
          tagList,  then  the new text will receive any tags that
          are present on both the character before and the  char-
          acter 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 oth-
          ers, regardless of the tags present around  the  inser-
          tion  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 omit-
          ted.

     pathName mark option ?arg arg ...?
          This command is used to manipulate  marks.   The  exact
          behavior  of the command depends on the option argument
          that follows the mark argument.  The following forms of
          the command are currently supported:

          pathName mark gravity markName ?direction?
               If direction is not  specified,  returns  left  or
               right to indicate which of its adjacent characters
               markName is attached to.  If direction  is  speci-
               fied,  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 char-
               acter  just  before  that  index.  If index is the
               name of a mark, then the search for the next  mark
               begins  immediately  before  that  mark.  This can
               still return a mark at the same position if  there
               are  multiple  marks  at  the  same  index.  These
               semantics mean that the  mark  previous  operation
               can  be  used  to  step through all the marks in a
               text widget in  the  reverse  order  as  the  mark
               information  returned  by  the dump operation.  An
               empty string is returned if  there  are  no  marks
               before index.

          pathName mark set markName index
               Sets the mark named markName to  a  position  just
               before   the  character  at  index.   If  markName
               already exists, it is moved from its old position;
               if  it doesn't exist, a new mark is created.  This
               command returns an empty string.

          pathName mark unset markName ?markName markName ...?
               Remove the mark corresponding to each of the mark-
               Name  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  asso-
               ciated  with  a  mouse button press in the widget.
               It returns an empty string.

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

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

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

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

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

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

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

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

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

          The matching range must be  entirely  within  a  single
          line of text.  For regular expression matching the new-
          lines 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  new-
          lines  are  retained.   If  stopIndex is specified, the
          search stops at that index:  for forward  searches,  no
          match  at  or  after stopIndex will be considered;  for
          backward searches, no match earlier in  the  text  than
          stopIndex will be considered.  If stopIndex is omitted,
          the entire text will be searched:  when  the  beginning
          or  end of the text is reached, the search continues at
          the other end until the starting  location  is  reached
          again;   if stopIndex is specified, no wrap-around will
          occur.

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

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

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

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

               The only events for which bindings may  be  speci-
               fied  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  posi-
               tion  changed.   Note  that  these events are dif-
               ferent 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, one binding is invoked for each tag,
               in order from lowest-priority to highest priority.
               If there are multiple matching bindings for a sin-
               gle tag, then the most specific binding is  chosen
               (see  the  manual  entry  for the bind command for
               details).   continue  and  break  commands  within
               binding  scripts  are processed in the same way as
               for bindings created with the bind command.

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

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

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

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

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

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

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

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

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

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

          ...?
          pathName tag remove tagName  index1  ?index2  index1  index2
               Remove  the tag tagName from all of the characters
               starting at index1 and ending just  before  index2
               (the  character at index2 isn't affected).  A sin-
               gle command may contain  any  number  of  index1 -
               index2  pairs.  If the last index2 is omitted then
               the single character  at  index1  is  tagged.   If
               there  are  no  characters  in the specified range
               (e.g. index1 is past the end of the file or index2
               is  less than or equal to index1) then the command
               has no effect.   This  command  returns  an  empty
               string.

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

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

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

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

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

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

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

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

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

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

          pathName yview
               Returns a list containing two  elements,  both  of
               which  are  real  fractions  between 0 and 1.  The
               first element gives  the  position  of  the  first
               character  in the top line in the window, relative
               to the text as a whole (0.5 means  it  is  halfway
               through  the  text, for example).  The second ele-
               ment gives the  position  of  the  character  just
               after  the last one in the bottom line of the win-
               dow, 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 charac-
               ter  given  by fraction appears on the top line of
               the window.  Fraction is a fraction between 0  and
               1;   0  indicates the first character in the text,
               0.33 indicates the  character  one-third  the  way
               through the text, and so on.

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

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

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

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

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

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

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

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



BINDINGS

     Tk automatically creates class bindings for texts that  give
     them  the  following  default behavior.  In the descriptions
     below, ``word'' refers to a  contiguous  group  of  letters,
     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  dragging
          with  mouse button 1 while the Shift key is down;  this
          will adjust the end of the selection that  was  nearest
          to  the mouse cursor when button 1 was pressed.  If the
          button  is  double-clicked  before  dragging  then  the
          selection will be adjusted in units of whole words;  if
          it  is  triple-clicked  then  the  selection  will   be
          adjusted in units of whole lines.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     [28] Control-o opens a new line by inserting a newline char-
          acter  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 modif-
     ications will take place.

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



PERFORMANCE ISSUES

     Text widgets should run efficiently under a variety of  con-
     ditions.   The  text  widget  uses  about  2-3 bytes of main
     memory for each byte of text, so texts containing a megabyte
     or  more  should be practical on most workstations.  Text is
     represented internally with a modified B-tree structure that
     makes operations relatively efficient even with large texts.
     Tags are included in the B-tree  structure  in  a  way  that
     allows  tags  to  span  large  ranges  or have many disjoint
     smaller ranges without loss of efficiency.  Marks  are  also
     implemented in a way that allows large numbers of marks.  In
     most cases it is fine to have large numbers of unique  tags,
     or a tag that has many distinct ranges.

     One performance problem can arise if you  have  hundreds  or
     thousands  of  different  tags  that  all have the following
     characteristics:  the first and last ranges of each tag  are
     near  the  beginning and end of the text, respectively, or a
     single tag range covers most of the text widget.   The  cost
     of adding and deleting tags like this is proportional to the
     number of other tags with the same properties.  In contrast,
     there  is  no problem with having thousands of distinct tags
     if their overall ranges are localized and  spread  uniformly
     throughout the text.

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

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


KEYWORDS

     text, widget