text man page on UnixWare

Man page or keyword search:  
man Server   3616 pages
apropos Keyword Search (all sections)
Output format
UnixWare logo
[printable version]

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

______________________________________________________________________________

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
       [-height 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.   [-spacing1 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.   [-spacing2 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  dis‐
       tances.	 This  option may be overriden with -spacing2 options in tags.
       [-spacing3 spacing3] Requests additional space below each text line  in
       the widget, using any of the standard forms for screen distances.  If a
       line wraps, this option only applies to the last line on	 the  display.
       This   option   may  be	overriden  with	 -spacing3  options  in	 tags.
       [-state 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.	 [-tabs 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 position.
       Right means that the right edge of the text following the tab character
       is  positioned  at  the tab position, and center means that the text is
       centered at the tab position.  Numeric means that the decimal point  in
       the  text  is  positioned  at the tab position;	if there is no decimal
       point then the least significant digit of the number is positioned just
       to  the	left  of  the tab position;  if there is no number in the text
       then the text is right-justified at the	tab  position.	 For  example,
       -tabs  {2c left 4c 6c center} creates three tab stops at two-centimeter
       intervals;  the first two use left justification	 and  the  third  uses
       center  justification.	If  the list of tab stops does not have enough
       elements to cover all of the tabs in a text line, then Tk  extrapolates
       new tab stops using the spacing and alignment from the last tab stop in
       the list.  The value of the tabs option	may  be	 overridden  by	 -tabs
       options	in  tags.  If no -tabs option is specified, or if it is speci‐
       fied as an empty list, then Tk uses default  tabs  spaced  every	 eight
       (average	 size) characters.  [-width width] Specifies the desired width
       for the window in units of characters in the font given	by  the	 -font
       option.	If the font doesn't have a uniform width then the width of the
       character ``0'' is used in translating from character units  to	screen
       units.  [-wrap wrap] Specifies how to handle lines in the text that are
       too long to be displayed in a single line of the	 text's	 window.   The
       value  must  be	none  or char or word.	A wrap mode of none means that
       each line of text appears as exactly one line  on  the  screen;	 extra
       characters  that	 don't	fit  on	 the screen are not displayed.	In the
       other modes each line of text will be broken  up	 into  several	screen
       lines  if necessary to keep all the characters visible.	In char mode a
       screen line break may occur after any character; in word	 mode  a  line
       break will only be made at word boundaries.
_________________________________________________________________

DESCRIPTION
       The  text command creates a new window (given by the 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  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 four different kinds of annotations │
       on  the	text, called tags, marks, embedded windows or embedded images.
       Tags allow different portions of the text to be displayed with  differ‐
       ent fonts and colors.  In addition, Tcl commands can be associated with
       tags so that scripts are invoked when particular actions such  as  key‐
       strokes	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 interest‐
       ing 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.

       The fourth form of annotation allows Tk images to be embedded in a text │
       widget.	See EMBEDDED IMAGES 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.  If char is end then it refers to the new‐
		   line character that ends the line.

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

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

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

       tag.first   Indicates  the  first  character  in the text that has been
		   tagged with tag.  This form generates an error if no	 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
		   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.

       imageName							       │
		   Indicates  the position of the embedded image whose name is │
		   imageName.  This form generates an error  if	 there	is  no │
		   embedded image by the given name.

       If  the	base  could  match more than one of the above forms, such as a
       mark and imageName both having the same value, then the form earlier in
       the  above  list takes precedence.  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 abbrevia‐
       tion 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 character in the text.	 Spaces on either side
	      of count are optional.

       + count lines
	      Adjust the index forward by  count  lines,  retaining  the  same
	      character	 position  within  the	line.  If there are fewer than
	      count lines after the line containing the	 current  index,  then
	      set  the	index  to  refer to the same character position on the
	      last line of the text.  Then, if the line is not long enough  to
	      contain  a character at the indicated character position, adjust
	      the character position to refer to the  last  character  of  the
	      line  (the  newline).   Spaces  on  either  side	of  count  are
	      optional.

       - count lines
	      Adjust the index backward by count  lines,  retaining  the  same
	      character	 position  within  the	line.  If there are fewer than
	      count lines before the line containing the current  index,  then
	      set  the	index  to  refer to the same character position on the
	      first line of the text.  Then, if the line is not long enough to
	      contain  a character at the indicated character position, adjust
	      the character position to refer to the  last  character  of  the
	      line  (the  newline).   Spaces  on  either  side	of  count  are
	      optional.

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

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

       wordstart
	      Adjust  the  index  to  refer to the first character of the word
	      containing the current index.  A word 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
       implementing some of the tag-related functions described below.	When a
       tag  is	defined (by associating it with characters or setting its dis‐
       play 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 com‐
       mands.

       Tags serve three purposes in text widgets.  First, they control the way
       information is displayed on the screen.	 By  default,  characters  are
       displayed as determined by the background, font, and foreground options
       for the text 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 characters asso‐
	      ciated  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_GetPix‐
	      els.  This option is used in conjunction with the -relief option
	      to give a 3-D appearance to the background for characters; it is
	      ignored unless the -background option has been set for the tag.

       -fgstipple bitmap
	      Bitmap specifies a bitmap that is used as a stipple pattern when
	      drawing  text  and  other	 foreground information such as under‐
	      lines.  It may have any of the forms accepted  by	 Tk_GetBitmap.
	      If  bitmap  hasn't  been	specified, or if it is specified as an
	      empty string, then a solid fill will be used.

       -font fontName
	      FontName is the name of a font to use  for  drawing  characters.
	      It may have any of the forms accepted by Tk_GetFontStruct.

       -foreground color
	      Color  specifies	the  color  to use when drawing text and other
	      foreground information such as 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 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.  Pix‐
	      els may have any of the standard forms for screen distances.  If
	      a line of text wraps, this option only applies to the first line
	      on the display;  the -lmargin2 option controls  the  indentation
	      for subsequent lines.

       -lmargin2 pixels
	      If  the  first  character	 of a display line has a tag for which
	      this option has been specified, and if the display line  is  not
	      the  first  for its text line (i.e., the text line has wrapped),
	      then pixels specifies how much the line should be indented  from
	      the  left	 edge of the window.  Pixels may have any of the stan‐
	      dard 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	super‐
	      scripts  and a negative offset can be used for subscripts.  Pix‐
	      els may have any of the standard forms for screen distances.

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

       -relief relief
	      Relief specifies the 3-D relief to use for drawing  backgrounds,
	      in  any  of  the forms accepted by Tk_GetRelief.	This option is
	      used in conjunction with the -borderwidth option to give	a  3-D
	      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 dis‐
	      play line.

       -spacing1 pixels
	      Pixels  specifies how much additional space should be left above
	      each text line, 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.

       -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 dis‐
	      tances.  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 dis‐
	      play 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_Get‐
	      Boolean.

       -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
       default style for the widget will be used.

       The second purpose for tags is event bindings.  You can associate bind‐
       ings 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 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
       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
       descendant  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 window 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  cre‐
       ate  widget  command,  several  configuration options may be associated
       with it.	 These options may be  modified later with the window  config‐
       ure widget command.  The following options are currently supported:

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

       -create script
	      Specifies	 a Tcl script that may be evaluated to create the win‐
	      dow for the annotation.  If no -window option has been specified
	      for  the annotation this script will be evaluated when the anno‐
	      tation is about to be displayed on the screen.  Script must cre‐
	      ate a window for the annotation and return the name of that win‐
	      dow as its result.  If the annotation's window  should  ever  be
	      deleted,	script will be evaluated again the next time the anno‐
	      tation 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	verti‐
	      cally  to fill its line.	If the -pady option has been specified
	      as well, then the requested padding will be retained even if the
	      window is stretched.

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

EMBEDDED IMAGES								       │
       The  final  form	 of  annotation	 in text widgets is an embedded image. │
       Each embedded image annotation causes an image to  be  displayed	 at  a │
       particular  point  in   the  text.  There may be any number of embedded │
       images in a text widget, and a particular image may be embedded in mul‐ │
       tiple places in the same text widget.  The embedded image's position on │
       the screen will be updated as the text is modified or  scrolled.	  Each │
       embedded	 image	occupies  one  character's worth of index space in the │
       text widget, and it may be referred to either by its  position  in  the │
       widget's	 index	space,	or  the	 name it is assigned when the image is │
       inserted into the text widget widh image create.	 If the range of  text │
       containing the embedded image is deleted then that copy of the image is │
       removed from the screen.						       │

       When an embedded image is added to a text widget with the image	create │
       widget  command,	 a  name  unique  to  this  instance  of  the image is │
       returned.  This name may then be used to refer to this image  instance. │
       The  name  is  taken  to	 be  the  value of the -name option (described │
       below).	If the -name option is not provided, the -image name  is  used │
       instead.	  If  the imageName is already in use in the text widget, then │
       #nn is added to the end of the imageName,  where	 nn  is	 an  arbitrary │
       integer.	  This	insures	 the  imageName	 is unique.  Once this name is │
       assigned to this instance of the image, it does not change, even though │
       the -image or -name values can be changed with image configure.	       │

       When  an embedded image is added to a text widget with the image create │
       widget command, several configuration options may  be  associated  with │
       it.   These options may be modified later with the image configure wid‐ │
       get command.  The following options are currently supported:	       │

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

       -image image							       │
	      Specifies the name of the Tk image to display in the annotation. │
	      If image is not a valid Tk image, then an error is returned.     │

       -name ImageName							       │
	      Specifies	 the  name  by which this image instance may be refer‐ │
	      enced in the text widget. If ImageName is not supplied, then the │
	      name  of	the  Tk	 image	is  used instead.  If the imageName is │
	      already in use, #nn is appended  to  the	end  of	 the  name  as │
	      described above.						       │

       -padx pixels							       │
	      Pixels specifies the amount of extra space to leave on each side │
	      of the embedded image.  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 image.	It may have any of the │
	      usual forms defined for a screen distance.

THE 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 selectFore‐
       ground options for the text widget are tied to the  -background,	 -bor‐
       derwidth,  and  -foreground options for the sel tag:  changes in either
       will automatically be reflected in the other.

THE INSERTION CURSOR
       The mark named insert has special significance in text widgets.	It  is
       defined	automatically  when a text widget is created and it may not be
       unset with the ``pathName mark unset'' widget command.  The insert mark
       represents the position of the insertion cursor, and the insertion cur‐
       sor 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 wid‐
       get'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 only
	      partially visible on the screen, then the return value  reflects
	      just  the	 visible part.	If the character is not visible on the
	      screen then the return value is an empty list.

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

       pathName compare index1 op index2
	      Compares the indices given by index1 and index2 according to the
	      relational  operator given by op, and returns 1 if the relation‐
	      ship 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 avail‐
	      able 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 corresponding sublist
	      of the value returned if no option is  specified).   If  one  or
	      more option-value pairs are specified, then the command modifies
	      the given widget option(s) to have the given value(s);  in  this
	      case  the	 command returns an empty string.  Option may have any
	      of the values accepted by the text command.

       pathName debug ?boolean?
	      If boolean is specified, then it must have one of	 the  true  or
	      false values accepted by Tcl_GetBoolean.	If the value is a true
	      one then internal consistency checks will be turned on in the B-
	      tree  code associated with text widgets.	If boolean has a false
	      value then the debugging checks will be turned off.   In	either
	      case  the	 command  returns  an empty string.  If boolean is not
	      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, 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 window, the	area  returned
	      reflects	the  entire  area  of the line, including the portions
	      that are out of the window.  If the line	is  shorter  than  the
	      full  width  of  the window then the area returned reflects just
	      the portion of the line  that  is	 occupied  by  characters  and
	      embedded	windows.   If the display line 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  win‐
	      dow.   The corresponding value is the text, mark name, tag name,
	      or window name.  The index information is the index of the start
	      of  the  text, the mark, the tag transition, or the window.  One
	      or more of the following switches (or 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  newline
		     is part of the value.

	      -window
		     Include  information  about  embedded windows in the dump
		     results.  The value of  a	window	is  its	 Tk  pathname,
		     unless  the  window  has  not been created yet.  (It must
		     have a 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 image option ?arg arg ...?
	      This  command is used to manipulate embedded images.  The behav‐
	      ior of the command depends on the option argument	 that  follows
	      the  tag	argument.  The following forms of the command are cur‐
	      rently supported:

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

	      pathName image configure index ?option value ...?
		     Query or modify the configuration options for an embedded
		     image.   If  no  option  is  specified,  returns  a  list
		     describing all of the available options for the  embedded
		     image  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	corre‐
		     sponding  sublist	of  the value returned if no option is
		     specified).  If one or more option-value pairs are speci‐
		     fied,  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 IMAGES for infor‐
		     mation on the options that are supported.

	      pathName image create index ?option value ...?
		     This command creates a new image annotation,  which  will
		     appear  in	 the text at the position given by index.  Any
		     number of option-value pairs may be specified to  config‐
		     ure the annotation.  Returns a unique identifier that may
		     be used as an index to refer to this image.  See EMBEDDED
		     IMAGES for information on the options that are supported,
		     and a description of the identifier returned.

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

       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
	      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 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
		     attached  to.  If direction is specified, it must be left
		     or right; the gravity of markName is  set	to  the	 given
		     value.

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

	      pathName mark next index
		     Returns the name of the next mark at or after index.   If
		     index is specified in numerical form, then the search for
		     the next mark begins at that index.  If index is the name
		     of a mark, then the search for the next mark begins imme‐
		     diately 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 wid‐
		     get in the same order as the mark information returned by
		     the  dump	operation.  If a mark has been set to the spe‐
		     cial end index, then it appears  to  be  after  end  with
		     respect  to  the mark next operation.  An empty string is
		     returned if there are no marks after index.

	      pathName mark previous index
		     Returns the name of the mark  at  or  before  index.   If
		     index is specified in numerical form, then the search for
		     the previous mark begins with the character  just	before
		     that  index.   If	index  is the name of a mark, then the
		     search for the next mark begins 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 markName
		     arguments.	 The removed  marks  will  not	be  usable  in
		     indices  and  will	 not  be  returned  by future calls to
		     ``pathName mark names''.  This command returns  an	 empty
		     string.

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

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

	      pathName scan dragto x y
		     This  command computes the difference between its x and y
		     arguments and the x and y 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 wid‐
		     get, 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;  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 or after  the	 posi‐
		     tion given by 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
		     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 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 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 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 bind tagName ?sequence? ?script?
		     This command associates script with the tag given by tag‐
		     Name.  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 simi‐
		     lar  to the bind command except that it operates on char‐
		     acters in a text rather than  entire  widgets.   See  the
		     bind  manual  entry for complete details on the syntax of
		     sequence and the substitutions performed on script before
		     invoking  it.   If all arguments are specified then a new
		     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  com‐
		     mand  returns  the	 script	 associated  with  tagName and
		     sequence (an error occurs if there is no  such  binding).
		     If	 both script and sequence are omitted then the command
		     returns a list of all the sequences  for  which  bindings
		     have been defined for tagName.

		     The  only	events for which bindings may be specified are │
		     those related to the mouse and keyboard (such  as	Enter, │
		     Leave,  ButtonPress,  Motion,  and	 KeyPress)  or virtual │
		     events.  Event bindings for a text widget use the current │
		     mark  described  under MARKS above.  An Enter event trig‐ │
		     gers 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 cur‐ │
		     rent mark moved or because the character at that position │
		     changed.  Note that these events are different than Enter │
		     and Leave events for windows.  Mouse and keyboard	events │
		     are  directed  to	the  current  character.  If a virtual │
		     event is used in a binding, that binding can trigger only │
		     if	 the  virtual event is defined by an underlying mouse- │
		     related or keyboard-related event.

		     It is possible for the current character to have multiple
		     tags,  and	 for each of them to have a binding for a par‐
		     ticular 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	 bind‐
		     ings  for a single tag, then the most specific binding is
		     chosen (see the manual entry for  the  bind  command  for
		     details).	 continue  and	break  commands within binding
		     scripts are processed in the same	way  as	 for  bindings
		     created with the bind command.

		     If	 bindings  are created for the widget as a whole using
		     the bind command, then those bindings will supplement the
		     tag  bindings.   The  tag bindings will be invoked first,
		     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.

	      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
		     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 cor‐
		     responding	 sublist of the value returned if no option is
		     specified).  If one or more option-value pairs are speci‐
		     fied,  then  the  command modifies the given option(s) to
		     have the given value(s) in tagName; in this case the com‐
		     mand returns an empty string.  See TAGS above for details
		     on the options available for tags.

	      pathName tag delete tagName ?tagName ...?
		     Deletes all tag information for each of the tagName 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 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  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
		     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 behav‐
	      ior of the command depends on the option argument	 that  follows
	      the  tag	argument.  The following forms of the command are cur‐
	      rently supported:

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

	      pathName window configure index ?option value ...?
		     Query or modify the configuration options for an embedded
		     window.   If  no  option  is  specified,  returns	a list
		     describing all of the available options for the  embedded
		     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	corre‐
		     sponding  sublist	of  the value returned if no option is
		     specified).  If one or more option-value pairs are speci‐
		     fied,  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 infor‐
		     mation 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  config‐
		     ure 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 win‐
		     dows 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 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
		     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  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
       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  but‐
	      ton 1 was pressed.  If the button is double-clicked before drag‐
	      ging 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  reposi‐
	      tion 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 cursor by words, and Control-Shift-Left  and  Con‐
	      trol-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	 para‐
	      graphs  (groups of lines separated by blank lines), and Control-
	      Shift-Up and Control-Shift-Down move  the	 insertion  cursor  by
	      paragraphs  and  also  extend the selection.  Control-p and Con‐
	      trol-n behave the same as Up and Down, respectively.

       [11]   The Next and Prior keys move the	insertion  cursor  forward  or
	      backwards	 by one screenful and clear any selection in the text.
	      If the Shift key is held down while Next or Prior is typed, then
	      the  selection  is  extended to include the new character.  Con‐
	      trol-v moves the view down  one  screenful  without  moving  the
	      insertion 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 begin‐
	      ning of the text and clear any selection in  the	widget.	  Con‐
	      trol-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 clipboard, if there is
	      a selection.

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

       [22]   The  F18	key  (labelled Paste on many Sun workstations) or Con‐
	      trol-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 cursor.

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

       [26]   Meta-d deletes the word to the right of the 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 character.

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

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

Tk				      4.0			       text(n)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server UnixWare

List of man pages available for UnixWare

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net