text(n)			     Ck Built-In Commands		       text(n)



______________________________________________________________________________

NAME
       text - Create and manipulate text widgets

SYNOPSIS
       text pathName ?options?

STANDARD OPTIONS
       attributes      selectAttributes		      selectForegroundxScrollCommand
       background      selectBackground		      takeFocusyScrollCommand
       foreground

       See the ``options'' manual entry for details on the standard options.

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

	      Specifies	 the  desired  height for the window, in screen lines.
	      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 characters may not be inserted or
	      deleted and no insertion cursor will be displayed, even  if  the
	      input focus is in the widget.

       Name:	       tabs
       Class:	       Tabs
       Command-Line Switch:-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 following the tab
	      character	 to  be positioned with its left edge at the tab posi-
	      tion.  Right means that the right edge of the text following the
	      tab  character  is  positioned  at  the tab position, and center
	      means that the text is centered at the  tab  position.   Numeric
	      means  that  the	decimal point in the text is positioned at the
	      tab position;  if there is no decimal point then the least  sig-
	      nificant	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
	      {2 left 4 6 center} creates three tab stops at two-column inter-
	      vals;   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 Ck
	      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 Ck uses
	      default tabs spaced every eight columns.

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

	      Specifies the desired width for the window in screen columns.

       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 sev-
	      eral screen lines if necessary to keep all the characters	 visi-
	      ble.  In char mode a screen line break may occur after any char-
	      acter; 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 con-
       figure aspects of the text such as its colors and attributes.  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 two different kinds of  annotations
       on  the	text, called tags and marks.  Tags allow different portions of
       the text to be displayed with different	attributes  and	 colors.   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 interest-
       ing  positions  in  the text as it is edited.  See MARKS below for more
       details.


INDICES
       Many of the widget commands for texts take one or more indices as argu-
       ments.  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 num-
		   bered from 1 for consistency with other UNIX programs  that
		   use	this  numbering scheme.	 Within a line, characters are
		   numbered from 0.

       @x,y	   Indicates the character that covers the place whose x and y
		   coordinates within the text's window are x and y.

       end	   Indicates the end of the text (the character just after the
		   last newline).

       mark	   Indicates the character just after the mark whose  name  is
		   mark.

       tag.first   Indicates  the  first  character  in the text that has been
		   tagged with tag.  This form generates an error if no	 char-
		   acters 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  er-
		   ror 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  ab-
       breviated 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 in-
	      dex 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 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  op-
	      tional.

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

       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 contain-
       ing the insertion cursor.


TAGS
       The first form of annotation in text widgets is a tag.  A tag is a tex-
       tual  string  that is associated with some of the characters in a text.
       Tags may contain arbitrary characters, but it is probably best to avoid
       using  the the characters `` '' (space), +, or -: these characters have
       special meaning in indices, so tags containing them can't  be  used  as
       indices.	 There may be any number of tags associated with characters in
       a text.	Each tag may refer to a single character, a range  of  charac-
       ters,  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  im-
       plementing  some	 of the tag-related functions described below.	When a
       tag is defined (by associating it with characters or setting  its  dis-
       play  options  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  two 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, attributes, and foreground
       options for the text widget.  However, display options may  be  associ-
       ated  with  individual tags using the ``pathName tag configure'' widget
       command.	 If a character has been tagged, then the display options  as-
       sociated	 with the tag override the default display style.  The follow-
       ing options are currently supported for tags:

       -attributes attrList
	      AttrList specifies the attributes to use for characters  associ-
	      ated with the tag.

       -background color
	      Color specifies the background color to use for characters asso-
	      ciated with the tag.

       -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 justification for each line on the dis-
	      play is determined by the first character of that display line.

       -lmargin1 columns
	      If the first character of a text line has a tag for  which  this
	      option  has  been specified, then columns specifies how much the
	      line should be indented from the left edge of the window.	 If  a
	      line  of	text wraps, this option only applies to the first line
	      on the display;  the -lmargin2 option controls  the  indentation
	      for subsequent lines.

       -lmargin2 columns
	      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 columns specifies how much the line should be indented from
	      the  left	 edge  of  the	window.	 This option is only used when
	      wrapping is enabled, and it only applies to the second and later
	      display lines for a text line.

       -rmargin columns
	      If  the  first  character	 of a display line has a tag for which
	      this option has been specified, then columns specifies how  wide
	      a margin to leave between the end of the line and the right edge
	      of the window.  This option is only used when  wrapping  is  en-
	      abled.   If a text line wraps, the right margin for each line on
	      the display is determined by the first character of that display
	      line.

       -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 dis-
	      play line.  If this option is specified as an empty  string,  it
	      cancels  the option, leaving it unspecified for the tag (the de-
	      fault).  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.

       -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 dis-
       play options conflict, then the options of the highest priority tag are
       used.   If a particular display option hasn't been specified for a par-
       ticular 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 de-
       fault style for the widget will be used.

       The  second  use for tags is in managing the selection.	See THE SELEC-
       TION 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  sin-
       gle  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	 asso-
       ciation with characters in the file.  Marks may be manipulated with the
       ``pathName mark'' widget command, and their current  locations  may  be
       determined by using the mark name as an index in widget commands.

       Each mark also has a gravity, which is either left or right.  The grav-
       ity for a mark specifies what happens to the mark when text is inserted
       at the point of the mark.  If a mark has left gravity, then the mark is
       treated as if it were attached to the character on  its	left,  so  the
       mark will remain to the left of any text inserted at the mark position.
       If the mark has right gravity, new text inserted at the	mark  position
       will  appear to the right of the mark.  The gravity for a mark defaults
       to right.

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

       Two marks have special significance.  First, the mark insert is associ-
       ated with the insertion cursor, as described under THE INSERTION CURSOR
       below.  Second, the mark current is associated with the character clos-
       est to the mouse and is adjusted automatically to track the mouse posi-
       tion 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  re-
       leased).	 Neither of these special marks may be deleted.


THE SELECTION
       Selection  support  is  implemented via tags.  The sel tag is automati-
       cally defined when a text widget is created, and it may not be  deleted
       with  the ``pathName tag delete'' widget command.  Furthermore, the se-
       lectBackground, selectAttributes, and selectForeground options for  the
       text  widget  are tied to the -background, -attributes, and -foreground
       options for the sel tag:	 changes in either will automatically  be  re-
       flected 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 cur-
       sor  will automatically be moved to 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 character, and the last two elements
	      give the width and height of the area.  If the character is  not
	      visible on the screen then the return value is an empty list.

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

       pathName compare index1 op index2
	      Compares the indices given by index1 and index2 according to the
	      relational operator given by op, and returns 1 if the  relation-
	      ship  is satisfied and 0 if it isn't.  Op must be one of the op-
	      erators <, <=, ==, >=, >, 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 avail-
	      able options for pathName. 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  op-
	      tion-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 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 sin-
	      gle  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 coordinates of the  upper-left	corner
	      of  the area occupied by the line, the third and fourth elements
	      give the width and height of the area,  and  the	fifth  element
	      gives  the  position of the baseline for the line (always zero).
	      All of this information is measured in screen  coordinates.   If
	      the  current  wrap  mode is none and the line extends beyond the
	      boundaries of the window, the area returned reflects the	entire
	      area  of	the  line,  including the portions that are out of the
	      window.  If the line is shorter than the full width of the  win-
	      dow then the area returned reflects just the portion of the line
	      that is occupied by characters.  If the display line  containing
	      index  is	 not visible on the screen then the return value is an
	      empty list.

       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  re-
	      turned.  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  charac-
	      ter number.  Index may have any of the forms described under IN-
	      DICES 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  be-
	      fore the last newline instead.  If there is a single chars argu-
	      ment and no tagList, then the new text  will  receive  any  tags
	      that  are present on both the character before and the character
	      after the insertion point; if a tag is present on	 only  one  of
	      these  characters	 then  it will not be applied to the new text.
	      If tagList is specified then it consists of a list of tag names;
	      the new characters will receive all of the tags in this list and
	      no others, regardless of the tags present around	the  insertion
	      point.   If  multiple  chars-tagList argument pairs are present,
	      they produce the same effect as if a separate insert widget com-
	      mand  had been issued for each pair, in order.  The last tagList
	      argument may be omitted.

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

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

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

	      pathName mark 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 ar-
		     guments.  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 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;  oth-
	      erwise  an empty string is returned.  One or more of the follow-
	      ing switches (or abbreviations thereof) may be specified to con-
	      trol the search:

	      -forwards
		     The search will proceed forward through the text, finding
		     the first matching range starting	at  a  position	 later
		     than index.  This is the default.

	      -backwards
		     The  search will proceed backward through the text, find-
		     ing the matching range closest to index whose first char-
		     acter is before index.

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

	      -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 vari-
		     able; if a match is found, the number  of	characters  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 newlines are  removed
	      from  the	 ends of the lines before matching:  use the $ feature
	      in regular expressions to match the end of a  line.   For	 exact
	      matching	the newlines are retained.  If stopIndex is specified,
	      the search stops at that index: for forward searches,  no	 match
	      at   or  after  stopIndex	 will  be  considered;	 for  backward
	      searches, no match earlier in the text than  stopIndex  will  be
	      considered.   If	stopIndex  is omitted, the entire text will be
	      searched: when the beginning or end of the text is reached,  the
	      search continues at the other end until the starting location is
	      reached again;  if stopIndex is specified, no  wrap-around  will
	      occur.

       pathName see index
	      Adjusts  the  view  in the window so that the character given by
	      index is 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 sup-
	      ported:

	      pathName tag add tagName index1 ?index2 index1 index2 ...?
		     Associate	the  tag  tagName  with	 all of the characters
		     starting with index1 and ending just before  index2  (the
		     character	at index2 isn't tagged).  A single command may
		     contain any number of index1-index2 pairs.	 If  the  last
		     index2  is omitted then the single 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 cget tagName option
		     This  command  returns  the  current  value of the option
		     named option associated with the tag  given  by  tagName.
		     Option  may  have	any  of the values accepted by the tag
		     configure widget command.

	      pathName tag configure tagName ?option?  ?value?	?option	 value
	      ...?
		     This  command  is similar to the configure widget command
		     except that it modifies options associated with  the  tag
		     given  by	tagName	 instead  of modifying options for the
		     overall text widget.  If no option is specified, the com-
		     mand  returns  a list describing all of the available op-
		     tions for tagName.	 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 tagName; 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 tagName argu-
		     ments.   The command removes the tags from all characters
		     in the file and also deletes any other information	 asso-
		     ciated with the tags, such as bindings and display infor-
		     mation.  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  command  but	 haven't  been	deleted	 by  a
		     ``pathName	 tag delete'' widget command, even if no char-
		     acters are currently marked with the tag).	 The list will
		     be sorted in order from lowest priority to highest prior-
		     ity.

	      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 considered).   If  several
		     matching ranges exist, the first one is chosen.  The com-
		     mand'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 end 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 element of
		     the pair contains the index of the character  just	 after
		     the  last	one  in the range.  If there are no characters
		     tagged with tag then an empty string is returned.

	      pathName tag remove tagName index1 ?index2 index1 index2 ...?
		     Remove the tag tagName from all of the characters	start-
		     ing  at index1 and ending just before index2 (the charac-
		     ter at index2 isn't affected).  A single command may con-
		     tain  any number of index1-index2 pairs.  If the last in-
		     dex2 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 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 fol-
	      lowing forms:

	      pathName xview
		     Returns a list containing two elements.  Each element  is
		     a	real fraction between 0 and 1;	together they describe
		     the portion of the document's  horizontal	span  that  is
		     visible in the window.  For example, if the first element
		     is .2 and the second element is .6, 20% of	 the  text  is
		     off-screen	 to the left, the middle 40% is visible in the
		     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 win-
		     dow.  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  screen-
		     fuls.   If	 number is negative then characters farther to
		     the left become visible;  if it is positive then  charac-
		     ters 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 fol-
	      lowing 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
		     element gives the position of the	character  just	 after
		     the  last	one in the bottom line of the window, relative
		     to the text as a whole.  These are the same values passed
		     to scrollbars via the -yscrollcommand option.

	      pathName yview moveto fraction
		     Adjusts  the  view	 in  the  window so that the character
		     given by fraction appears on the top line of the  window.
		     Fraction  is a 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 ac-
		     cording 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  dis-
		     play;   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	-pick-
		     place  is	specified  then the widget chooses where index
		     appears in the window:

		     [1]    If index is already visible somewhere in the  win-
			    dow 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 window.

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

	      pathName yview number
		     This command makes the first character on the line	 after
		     the one given by number 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
       Ck  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  be-
	      fore  the	 character underneath the mouse cursor, sets the input
	      focus to this widget, and clears any selection in the widget.

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

       [3]    The  Left and Right keys move the insertion cursor one character
	      to the left or right;  they also	clear  any  selection  in  the
	      text.   Control-b	 and  Control-f	 behave	 the  same as Left and
	      Right, respectively.

       [4]    The Up and Down keys move the insertion cursor one  line	up  or
	      down  and	 clear	any selection in the text.  Control-p and Con-
	      trol-n behave the same as Up and Down, respectively.

       [5]    The Next and Prior keys move the	insertion  cursor  forward  or
	      backwards	 by one screenful and clear any selection in the text.
	      Control-v moves the view down one screenful without  moving  the
	      insertion cursor or adjusting the selection.

       [6]    Home and Control-a move the insertion cursor to the beginning of
	      its line and clear any selection in the widget.

       [7]    End and Control-e move the insertion cursor to the  end  of  the
	      line and clear any selection in the widget.

       [8]    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.

       [9]    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 cursor.

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

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

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

       [13]   Control-x moves the input focus to the next widget in focus  or-
	      der.

       [14]   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 cur-
       sor will be displayed and no text modifications will take place.

       The behavior of texts can be changed by defining new bindings for indi-
       vidual 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 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.	 The only known mode of operation where a text
       widget may not run efficiently is if it has a very large number of dif-
       ferent  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



Ck				      8.0			       text(n)
