text man page on SmartOS

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

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

______________________________________________________________________________

NAME
       text,  tk_textCopy,  tk_textCut,	 tk_textPaste  - Create and manipulate
       text widgets

SYNOPSIS
       text pathName ?options?
       tk_textCopy pathName
       tk_textCut pathName
       tk_textPaste pathName

STANDARD OPTIONS
       -background	     -highlightthickness  -relief
       -borderwidth	     -insertbackground	  -selectbackground
       -cursor		     -insertborderwidth	  -selectborderwidth
       -exportselection	     -insertofftime	  -selectforeground
       -font		     -insertontime	  -setgrid
       -foreground	     -insertwidth	  -takefocus
       -highlightbackground  -padx		  -xscrollcommand
       -highlightcolor	     -pady		  -yscrollcommand

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

WIDGET-SPECIFIC OPTIONS
       [-autoseparators autoSeparators] Specifies a boolean that says  whether
       separators  are automatically inserted in the undo stack. Only meaning‐
       ful when the -undo option is true.   [-blockcursor blockCursor]	Speci‐
       fies  a	boolean that says whether the blinking insertion cursor should
       be drawn as a character-sized rectangular block. If false (the default)
       a  thin vertical line is used for the insertion cursor.	[-endline end‐
       Line] Specifies an integer line index  representing  the	 line  of  the
       underlying  textual  data store that should be just after the last line
       contained in the widget. This allows a text widget to  reflect  only  a
       portion	of  a  larger  piece of text. Instead of an integer, the empty
       string can be provided to this configuration option, which will config‐
       ure  the widget to end at the very last line in the textual data store.
       [-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.   [-inactiveselectbackground inactiveSelectBackground]   Specifies
       the  colour to use for the selection (the sel tag) when the window does
       not have the input focus. If empty, {}, then no selection is shown when
       the  window  does  not  have the focus.	[-insertunfocussed insertUnfo‐
       cussed] Specifies how to display the insertion cursor when  the	widget │
       does  not have the focus. Must be none (the default) which means to not │
       display the cursor, hollow which means to  display  a  hollow  box,  or │
       solid  which  means  to display a solid box. Note that hollow and solid │
       will appear very similar when the -blockcursor option is false.	[-max‐
       undo maxUndo]  Specifies the maximum number of compound undo actions on
       the undo stack. A zero or a negative  value  imply  an  unlimited  undo
       stack.	[-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 overridden 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 overridden 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 overridden with -spacing3 options in tags.  [-start‐
       line startLine] Specifies an integer line index representing the	 first
       line  of	 the underlying textual data store that should be contained in
       the widget. This allows a text widget to reflect only a	portion	 of  a
       larger  piece  of  text. Instead of an integer, the empty string can be
       provided to this configuration option, which will configure the	widget
       to   start   at	the  very  first  line	in  the	 textual  data	store.
       [-state state] Specifies one of two states for the text: normal or dis‐
       abled.  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 of which is a distance rel‐
       ative to the left edge of the widget (excluding borders, padding, etc).
       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 posi‐
       tion;  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.  Tab  distances  must	be strictly positive, and must
	      always increase from one tab stop to the next (if not, an	 error
	      is  thrown).  The value of the -tabs option may be overridden by
	      -tabs options in tags.

	      If no -tabs option is specified, or if it	 is  specified	as  an
	      empty  list, then Tk uses default tabs spaced every eight (aver‐
	      age size) characters.  To achieve a different standard  spacing,
	      for example every 4 characters, simply configure the widget with
	      “-tabs "[expr {4 * [font	measure	 $font	0]}]  left"  -tabstyle
	      wordprocessor”.
       [-tabstyle tabStyle]   Specifies	 how  to  interpret  the  relationship
       between tab stops on a line and tabs in the  text  of  that  line.  The
       value  must  be	tabular (the default) or wordprocessor. Note that tabs
       are interpreted as they are encountered in the text. If the  tab	 style
       is tabular then the n'th tab character in the line's text will be asso‐
       ciated with the n'th tab stop defined for that line. If the tab charac‐
       ter's  x coordinate falls to the right of the n'th tab stop, then a gap
       of a single space will be inserted as a fallback. If the tab  style  is
       wordprocessor  then  any	 tab character being laid out will use (and be
       defined by) the first tab stop to the right of the preceding characters
       already laid out on that line. The value of the -tabstyle option may be
       overridden by -tabstyle options	in  tags.   [-undo undo]  Specifies  a
       boolean	that  says  whether  the  undo	mechanism  is  active  or not.
       [-width width] Specifies the desired width for the window in  units  of
       characters  in the font given by the -font option. If the font does not
       have a uniform width then the width of the character  “0”  is  used  in
       translating  from character units to screen units.  [-wrap wrap] Speci‐
       fies 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 do not fit on the
       screen are not displayed. In the other modes each line of text will  be
       broken  up into several screen lines if necessary to keep all the char‐
       acters visible.	In char mode a screen line break may occur  after  any
       character;  in  word mode a line break will only be made at word bound‐
       aries.
_________________________________________________________________

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 floating markers in the text
       called “marks”.	Marks are used to keep track  of  various  interesting
       positions  in  the  text	 as  it	 is  edited.  See MARKS below for more
       details.

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

       The fourth form of annotation allows Tk images to be embedded in a text
       widget. See EMBEDDED IMAGES below for more details.

       The text widget also has a built-in undo/redo mechanism. See  THE  UNDO
       MECHANISM below for more details.

       The  text  widget  allows  for  the creation of peer widgets. These are
       other text widgets which share the same underlying data	(text,	marks,
       tags, images, etc).  See PEER WIDGETS 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.	  Most
       modifiers  (as  documented  below) allow an optional submodifier. Valid
       submodifiers are any and display. If the	 submodifier  is  abbreviated,
       then  it must be followed by whitespace, but otherwise there need be no
       space between the submodifier and the  following	 modifier.   Typically
       the  display  submodifier adjusts the meaning of the following modifier
       to make it refer to visual or  non-elided  units	 rather	 than  logical
       units,  but  this  is  explained	 for each relevant case below. Lastly,
       where count is used as part of a modifier, it can be positive or	 nega‐
       tive,  so “base - -3 lines” is perfectly valid (and equivalent to “base
       +3lines”).

       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 abbreviation is
       unambiguous.

       + count ?submodifier? 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 index in the text. Spaces on either side of
	      count are optional. If the display submodifier is given,	elided
	      characters  are  skipped	over  without being counted. If any is
	      given, then all characters are counted. For historical  reasons,
	      if neither modifier is given then the count actually takes place
	      in units of index positions (see INDICES for details). This  be‐
	      haviour may be changed in a future major release, so if you need
	      an index count, you are encouraged to use indices instead	 wher‐
	      ever possible.

       - count ?submodifier? 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 index in the text  (1.0).  Spaces  on	either
	      side of count are optional. If the display submodifier is given,
	      elided characters are skipped over without being counted. If any
	      is  given,  then all characters are counted. For historical rea‐
	      sons, if neither modifier is given then the count actually takes
	      place  in	 units	of  index positions (see INDICES for details).
	      This behavior may be changed in a future major  release,	so  if
	      you  need	 an  index  count,  you	 are encouraged to use indices
	      instead wherever possible.

       + count ?submodifier? indices
	      Adjust the index forward by count	 index	positions,  moving  to
	      later  lines  in	the text if necessary. If there are fewer than
	      count index positions in the text after the current index,  then
	      set  the index to the last index position in the text. Spaces on
	      either side of count are optional. Note that an  index  position
	      is  either  a  single  character	or  a single embedded image or
	      embedded window. If the display  submodifier  is	given,	elided
	      indices are skipped over without being counted. If any is given,
	      then all indices are counted; this is also the default behaviour
	      if no modifier is given.

       - count ?submodifier? indices
	      Adjust  the  index  backward by count index positions, moving to
	      earlier lines in the text if necessary. If there are fewer  than
	      count index positions in the text before the current index, then
	      set the index to the first index position	 (1.0)	in  the	 text.
	      Spaces on either side of count are optional. If the display sub‐
	      modifier is given, elided indices are skipped over without being
	      counted.	If any is given, then all indices are counted; this is
	      also the default behaviour if no modifier is given.

       + count ?submodifier? 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. If the display submodifier is given, then each	visual
	      display  line  is	 counted separately.  Otherwise, if any (or no
	      modifier) is given, then each logical line (no matter  how  many
	      times  it is visually wrapped) counts just once. If the relevant
	      lines are not wrapped, then these two methods  of	 counting  are
	      equivalent.

       - count ?submodifier? lines
	      Adjust  the index backward by count logical 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.
	      If  the  display	submodifier is given, then each visual display
	      line is counted separately. Otherwise, if any (or	 no  modifier)
	      is given, then each logical line (no matter how many times it is
	      visually wrapped) counts just once. If the  relevant  lines  are
	      not wrapped, then these two methods of counting are equivalent.

       ?submodifier? linestart
	      Adjust the index to refer to the first index on the line. If the
	      display submodifier is given, this is the	 first	index  on  the
	      display line, otherwise on the logical line.

       ?submodifier? lineend
	      Adjust  the  index  to  refer to the last index on the line (the
	      newline). If the display submodifier is given, this is the  last
	      index on the display line, otherwise on the logical line.

       ?submodifier? 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. If the display sub‐
	      modifier	is  given,  this  only examines non-elided characters,
	      otherwise all characters (elided or not) are examined.

       ?submodifier? 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  the display submodifier is given, this only exam‐
	      ines non-elided characters, otherwise all characters (elided  or
	      not) are examined.

       If  more than one modifier is present then they are applied in left-to-
       right order. For example, the index “end - 1 chars” refers to the next-
       to-last	character  in  the text and “insert wordstart - 1 c” refers to
       the character just before the first one	in  the	 word  containing  the
       insertion  cursor.  Modifiers  are  applied  one by one in this left to
       right order, and after each step the resulting index is constrained  to
       be  a  valid  index in the text widget. So, for example, the index “1.0
       -1c +1c” refers to the index “2.0”.

       Where modifiers result in index changes by display lines, display chars
       or  display  indices,  and the base refers to an index inside an elided
       tag, that base index is considered to be equivalent to the  first  fol‐
       lowing non-elided index.

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 characters “ ” (space), +, or -: these characters  have  spe‐
       cial  meaning  in  indices,  so	tags containing them cannot 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 dis‐
       played 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 cur‐
       rently 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_Get‐
	      Bitmap. If bitmap has not been specified, or if it is  specified
	      as an empty string, then a solid fill will be used for the back‐
	      ground.

       -borderwidth pixels
	      Pixels specifies the width of a border to draw  around  the  tag
	      using  any  of  the  forms accepted by Tk_GetPixels. This option
	      should be used in conjunction with the -relief option to provide
	      the desired border.

       -elide boolean
	      Elide  specifies	whether the data should be elided. Elided data
	      (characters, images, embedded windows, etc.)  is	not  displayed
	      and  takes  no  space  on screen, but further on behaves just as
	      normal data.

       -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 has not 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_GetFont.

       -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  non-elided character of a display line has a tag
	      for which this option has been specified,	 then  justify	deter‐
	      mines how to justify the line. It must be one of left, right, or
	      center. If a line wraps, then the justification for each line on
	      the  display  is determined by the first non-elided character of
	      that display line.

       -lmargin1 pixels
	      If the first non-elided 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  win‐
	      dow.  Pixels  may have any of the standard forms for screen dis‐
	      tances. 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 non-elided character of a display line  has	a  tag
	      for  which  this	option	has been specified, and if the display
	      line is not the first for its text line (i.e., the text line has
	      wrapped),	 then  pixels  specifies  how  much the line should be
	      indented from the left edge of the window.  Pixels may have  any
	      of  the standard forms for screen distances. This option is only
	      used when wrapping is enabled, and it only applies to the second
	      and later display lines for a text line.

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

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

       -relief relief
	      Relief specifies the relief style to use for drawing the border,
	      in any of the forms accepted by  Tk_GetRelief.  This  option  is
	      used  in	conjunction  with the -borderwidth option to enable to
	      the desired border appearance.

       -rmargin pixels
	      If the first non-elided 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	 wrap‐
	      ping is enabled. If a text line wraps, the right margin for each
	      line on the display is determined by the first non-elided	 char‐
	      acter of that display line.

       -spacing1 pixels
	      Pixels  specifies how much additional space should be left above
	      each text line, using any of the standard forms for screen  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 non-elided character on
	      that display line. If this  option  is  specified	 as  an	 empty
	      string,  it  cancels  the option, leaving it unspecified for the
	      tag (the default). If the option is  specified  as  a  non-empty
	      string  that  is	an  empty  list,  such	as  -tags { }, then it
	      requests default 8-character tabs as  described  for  the	 -tags
	      widget option.

       -tabstyle style
	      Style  specifies	either	the  tabular or wordprocessor style of
	      tabbing to use for the text widget. This option only applies  to
	      a	 display  line if it applies to the first non-elided character
	      on that display line. If this option is specified	 as  an	 empty
	      string,  it  cancels  the option, leaving it unspecified for the
	      tag (the default).

       -underline boolean
	      Boolean specifies whether or not to draw an underline underneath
	      characters.  It  may  have any of the forms accepted by Tcl_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 has not 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 “pathName tag bind” widget command below. Tag
       bindings are shared between all peer widgets  (including	 any  bindings
       for the special sel tag).

       The  third use for tags is in managing the selection. See THE SELECTION
       below. With the exception of the special sel tag, all tags  are	shared
       between	peer  text  widgets,  and may be manipulated on an equal basis
       from any such widget. The sel tag exists separately  and	 independently
       in each peer text widget (but any tag bindings to sel are shared).

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 is not associated with particular characters. Instead, a mark is
       associated  with the gap between two characters. Only a single position
       may be associated with a mark at any  given  time.  If  the  characters
       around a mark are deleted the mark will still remain; it will just have
       new neighbor characters. In contrast, if the  characters	 containing  a
       tag  are	 deleted  then the tag will no longer have an association with
       characters in the file. Marks may be  manipulated  with	the  “pathName
       mark”  widget command, and their current locations may be determined by
       using the mark name as an index in widget commands.

       Each mark also has a “gravity”, which is	 either	 left  or  right.  The
       gravity	for  a	mark  specifies	 what happens to the mark when text is
       inserted at the point of the mark. If a mark has left gravity, then the
       mark is treated as if it were attached to the character on its left, so
       the mark will remain to the left of any text inserted at the mark posi‐
       tion.  If  the  mark  has  right gravity, new text inserted at the mark
       position will appear to the left of the mark (so that the mark  remains
       rightmost). The gravity for a mark defaults to right.

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

       Two  marks have special significance. First, the mark insert is 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.  With  the
       exception of these two special marks, all marks are shared between peer
       text widgets, and may be manipulated on an equal basis from any peer.

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  win‐
       dows 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  wid‐
       get.  Each  embedded window occupies one unit'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. Similarly if the text widget as a whole is deleted, then
       the window is destroyed.

       When an embedded window is added to a text  widget  with	 the  pathName
       window  create  widget  command,	 several  configuration options may be
       associated with it. These options may be modified later with the	 path‐
       Name  window  configure	widget command. The following options are cur‐
       rently 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. Two substitutions will be performed in script
	      before evaluation. %W will be substituted by  the	 name  of  the
	      parent  text  widget,  and %% will be substituted by a single %.
	      If the annotation's window should ever be deleted,  script  will
	      be evaluated again the next time the annotation is displayed.

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

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

       -stretch boolean
	      If  the requested height of the embedded window is less than the
	      height of the line in which it is displayed, this option can  be
	      used  to	specify	 whether the window should be stretched 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.
	      Note  that  if a pathName has been set, then later configuring a
	      window to the empty string will not  delete  the	widget	corre‐
	      sponding to the old pathName.  Rather it will remove the associ‐
	      ation between the old pathName and the text widget. If  multiple
	      peer  widgets are in use, it is usually simpler to use the -cre‐
	      ate option if embedded windows are desired in each peer.

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 particu‐
       lar point in the text. There may be any number of embedded images in  a
       text  widget, and a particular image may be embedded in multiple 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 unit'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 with pathName 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 pathName
       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  wid‐
       get,  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  pathName	 image
       configure.

       When  an	 embedded  image  is  added to a text widget with the pathName
       image create widget command, several configuration options may be asso‐
       ciated  with  it. These options may be modified later with the pathName
       image configure widget 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.

       [4]    Whenever the sel tag range changes a virtual event <<Selection>>
	      is generated.

       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 -select‐
       foreground options for the text widget are  tied	 to  the  -background,
       -borderwidth,  and  -foreground	options	 for  the  sel tag: changes in
       either will automatically be reflected in the other.  Also  the	-inac‐
       tiveselectbackground  option  for  the  text  widget is used instead of
       -selectbackground when the text widget does not have  the  focus.  This
       allows  programmatic  control over the visualization of the sel tag for
       foreground and background windows, or to have  sel  not	shown  at  all
       (when  -inactiveselectbackground is empty) for background windows. Each
       peer text widget has its own sel tag which can be separately configured
       and set.

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.

THE MODIFIED FLAG
       The text widget can keep track of changes to the content of the	widget
       by means of the modified flag. Inserting or deleting text will set this
       flag. The flag can be queried,  set  and	 cleared  programmatically  as
       well.  Whenever	the flag changes state a <<Modified>> virtual event is
       generated. See the pathName  edit  modified  widget  command  for  more
       details.

THE UNDO MECHANISM
       The  text  widget  has  an  unlimited undo and redo mechanism (when the
       -undo widget option is true) which  records  every  insert  and	delete
       action on a stack.

       Boundaries (called “separators”) are inserted between edit actions. The
       purpose of these separators is to group inserts, deletes	 and  replaces
       into one compound edit action. When undoing a change everything between
       two separators will be undone. The undone changes are then moved to the
       redo stack, so that an undone edit can be redone again.	The redo stack
       is cleared whenever new edit actions are recorded on  the  undo	stack.
       The  undo and redo stacks can be cleared to keep their depth under con‐
       trol.

       Separators are inserted automatically when the  -autoseparators	widget
       option  is true. You can insert separators programmatically as well. If
       a separator is already present at the top of the undo  stack  no	 other
       will  be inserted. That means that two separators on the undo stack are
       always separated by at least one insert or delete action.

       The undo mechanism is also linked to the modified flag. This means that
       undoing	or redoing changes can take a modified text widget back to the
       unmodified state or vice versa. The modified flag will be set automati‐
       cally  to  the appropriate state. This automatic coupling does not work
       when the modified flag has been set by the user,	 until	the  flag  has
       been reset again.

       See  below  for the pathName edit widget command that controls the undo
       mechanism.

PEER WIDGETS
       The text widget has a separate store of all its	data  concerning  each
       line's  textual contents, marks, tags, images and windows, and the undo
       stack.

       While this data store cannot be accessed directly (i.e. without a  text
       widget  as an intermediary), multiple text widgets can be created, each
       of which present different views on the same underlying data. Such text
       widgets are known as peer text widgets.

       As  text	 is added, deleted, edited and coloured in any one widget, and
       as images, marks, tags are adjusted, all such changes will be reflected
       in all peers.

       All  data  and markup is shared, except for a few small details. First,
       the sel tag may be set and configured (in its  display  style)  differ‐
       ently  for  each peer. Second, each peer has its own insert and current
       mark positions (but all other marks are shared). Third,	embedded  win‐
       dows,  which  are  arbitrary  other  widgets,  cannot be shared between
       peers. This means the -window option of embedded	 windows  is  indepen‐
       dently  set  for	 each  peer (it is advisable to use the -create script
       capabilities to allow each peer to create its own embedded  windows  as
       needed).	 Fourth,  all  of the configuration options of each peer (e.g.
       -font, etc) can be set independently,  with  the	 exception  of	-undo,
       -maxundo,  -autoseparators  (i.e.  all  undo,  redo  and modified state
       issues are shared).

       Finally any single peer need not contain all lines from the  underlying
       data  store.  When  creating  a peer, a contiguous range of lines (e.g.
       only lines 52 through 125) may be specified. This allows a peer to con‐
       tain  just a small portion of the overall text. The range of lines will
       expand and contract as text is inserted or deleted. The peer will  only
       ever  display  complete	lines of text (one cannot share just part of a
       line). If the peer's contents contracts to nothing (i.e.	 all  complete
       lines  in  the peer widget have been deleted from another widget), then
       it is impossible for new lines to be inserted.  The  peer  will	simply
       become  an  empty  shell on which the background can be configured, but
       which will never show any content (without  manual  reconfiguration  of
       the  start  and end lines). Note that a peer which does not contain all
       of the underlying data store still has indices numbered from  “1.0”  to
       “end”.	It  is simply that those indices reflect a subset of the total
       data, and data outside the contained range is  not  accessible  to  the
       peer.  This  means that the command peerName index end may return quite
       different values in different peers. Similarly, commands like  peerName
       tag  ranges will not return index ranges outside that which is meaning‐
       ful to the peer. The configuration options -startline and -endline  may
       be  used to control how much of the underlying data is contained in any
       given text widget.

       Note that peers are really peers. Deleting the “original”  text	widget
       will not cause any other peers to be deleted, or otherwise affected.

       See  below  for the pathName peer widget command that controls the cre‐
       ation of peer widgets.

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  par‐
	      tially  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 is not. 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 count ?options? index1 index2
	      Counts the number of relevant things between the two indices. If
	      index1 is after index2, the result will  be  a  negative	number
	      (and  this  holds	 for each of the possible options). The actual
	      items which are counted depend on the options given. The	result
	      is  a  list  of  integers,  one  for the result of each counting
	      option given. Valid counting options are -chars,	-displaychars,
	      -displayindices,	-displaylines,	-indices, -lines, -xpixels and
	      -ypixels. The default value,  if	no  option  is	specified,  is
	      -indices.	 There	is an additional possible option -update which
	      is a modifier. If given, then all subsequent options ensure that
	      any  possible out of date information is recalculated. This cur‐
	      rently only has any effect for the  -ypixels  count  (which,  if
	      -update  is not given, will use the text widget's current cached
	      value for each line). The count options are interpreted as  fol‐
	      lows:

	      -chars count all characters, whether elided or not. Do not count
		     embedded windows or images.

	      -displaychars
		     count all non-elided characters.

	      -displayindices
		     count all non-elided characters, windows and images.

	      -displaylines
		     count all display lines (i.e. counting one for each  time
		     a line wraps) from the line of the first index up to, but
		     not including the	display	 line  of  the	second	index.
		     Therefore if they are both on the same display line, zero
		     will be returned. By definition displaylines are  visible
		     and therefore this only counts portions of actual visible
		     lines.

	      -indices
		     count all characters and embedded windows or images (i.e.
		     everything	 which	counts	in  text-widget	 index space),
		     whether they are elided or not.

	      -lines count all logical lines (irrespective of  wrapping)  from
		     the  line of the first index up to, but not including the
		     line of the second index. Therefore if they are  both  on
		     the  same	line, zero will be returned. Logical lines are
		     counted whether they are currently	 visible  (non-elided)
		     or not.

	      -xpixels
		     count  the	 number	 of  horizontal	 pixels from the first
		     pixel of the first index to (but not including) the first
		     pixel  of	the  second  index. To count the total desired
		     width of  the  text  widget  (assuming  wrapping  is  not
		     enabled), first find the longest line and then use “.text
		     count -xpixels "${line}.0" "${line}.0 lineend"”.

	      -ypixels
		     count the number of vertical pixels from the first	 pixel
		     of the first index to (but not including) the first pixel
		     of the second index. If both indices are on the same dis‐
		     play line, zero will be returned. To count the total num‐
		     ber of vertical pixels in the  text  widget,  use	“.text
		     count  -ypixels  1.0  end”,  and  to ensure this is up to
		     date, use “.text count -update -ypixels 1.0 end”.

	      The command returns a positive or negative integer corresponding
	      to the number of items counted between the two indices. One such
	      integer is returned for each counting option given, so a list is
	      returned	if  more  than	one  option  was supplied. For example
	      “.text count -xpixels -ypixels 1.3 4.5” is perfectly  valid  and
	      will return a list of two elements.

       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.

	      When debugging is turned on, the drawing routines	 of  the  text
	      widget  set the global variables tk_textRedraw and tk_textRelay‐
	      out to the lists of indices that	are  redrawn.  The  values  of
	      these variables are tested by Tk's test suite.

       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  does
	      not  specify  a  position	 later in the text than index1 then no
	      characters are deleted.  If index2 is  not  specified  then  the
	      single  character	 at  index1 is deleted. It is not allowable to
	      delete characters in a way that would leave the text  without  a
	      newline  as  the	last  character.  The command returns an empty
	      string. If more indices are given, multiple ranges of text  will
	      be  deleted.   All indices are first checked for validity before
	      any deletions are made. They are sorted and the text is  removed
	      from  the last range to the first range so deleted text does not
	      cause an undesired  index	 shifting  side-effects.  If  multiple
	      ranges  with  the	 same  start index are given, then the longest
	      range is used. If overlapping ranges are given, then  they  will
	      be  merged into spans that do not cause deletion of text outside
	      the given ranges due to text shifted during deletion.

       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,	image,
	      and  window. The corresponding value is the text, mark name, tag
	      name, image name, or window name. The index information  is  the
	      index  of	 the start of the text, mark, tag transition, image or
	      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,
		     images 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.

	      -image Include information about images in the dump results.

	      -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 segments that each end with a newline.  The  newline
		     is part of the value.

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

       pathName edit option ?arg arg ...?
	      This command controls the undo mechanism and the modified	 flag.
	      The exact behavior of the command depends on the option argument
	      that follows the edit argument. The following forms of the  com‐
	      mand are currently supported:

	      pathName edit modified ?boolean?
		     If boolean is not specified, returns the modified flag of
		     the widget.  The insert, delete, edit undo and edit  redo
		     commands  or the user can set or clear the modified flag.
		     If boolean is specified, sets the modified	 flag  of  the
		     widget to boolean.

	      pathName edit redo
		     When  the -undo option is true, reapplies the last undone
		     edits provided no other edits were done since then.  Gen‐
		     erates  an error when the redo stack is empty. Does noth‐
		     ing when the -undo option is false.

	      pathName edit reset
		     Clears the undo and redo stacks.

	      pathName edit separator
		     Inserts a separator (boundary) on the  undo  stack.  Does
		     nothing when the -undo option is false.

	      pathName edit undo
		     Undoes  the  last	edit  action  when the -undo option is
		     true. An edit action is defined as	 all  the  insert  and
		     delete  commands  that  are recorded on the undo stack in
		     between two separators. Generates an error when the  undo
		     stack  is	empty.	Does  nothing when the -undo option is
		     false.

       pathName get ?-displaychars? ?--? 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. If multiple index pairs
	      are given, multiple ranges of text will be returned in  a	 list.
	      Invalid ranges will not be represented with empty strings in the
	      list. The ranges are returned in the order  passed  to  pathName
	      get.  If	the  -displaychars  option is given, then, within each
	      range, only those	 characters  which  are	 not  elided  will  be
	      returned.	 This  may  have  the effect that some of the returned
	      ranges are empty strings.

       pathName image option ?arg arg ...?
	      This command is used to manipulate embedded images. The behavior
	      of  the  command depends on the option argument that follows the
	      tag argument. The following forms of the command	are  currently
	      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 describ‐
		     ing  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  information  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 pathName insert
	      widget command had been issued for each pair, in order. The last
	      tagList argument may be omitted.

       pathName mark option ?arg arg ...?
	      This  command is used to manipulate marks. The exact behavior of
	      the command depends on the option argument that follows the mark
	      argument.	 The 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 pathName dump operation. If a mark has	 been  set  to
		     the  special  end	index, then it appears to be after end
		     with respect to the  pathName  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	seman‐
		     tics  mean	 that the pathName 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
		     pathName 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 does not 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 peer option args
	      This command is used to create and query widget  peers.  It  has
	      two forms, depending on option:

	      pathName peer create newPathName ?options?
		     Creates  a	 peer  text widget with the given newPathName,
		     and any optional standard configuration options  (as  for
		     the text command). By default the peer will have the same
		     start and end line as the parent widget, but these can be
		     overridden with the standard configuration options.

	      pathName peer names
		     Returns  a	 list  of  peers of this widget (this does not
		     include the widget itself). The order within this list is
		     undefined.

       pathName replace index1 index2 chars ?tagList chars tagList ...?
	      Replaces	the range of characters between index1 and index2 with
	      the given characters and	tags.  See  the	 section  on  pathName
	      insert  for  an  explanation  of	the handling of the tagList...
	      arguments, and the section on pathName delete for an explanation
	      of  the  handling	 of  the  indices. If index2 corresponds to an
	      index earlier in the text than index1, an error will  be	gener‐
	      ated.

	      The  deletion  and insertion are arranged so that no unnecessary
	      scrolling of the window or movement of insertion cursor  occurs.
	      In  addition the undo/redo stack are correctly modified, if undo
	      operations are active in the text widget. The 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 pathName 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 pathName
		     scan mark command for the widget.	It  then  adjusts  the
		     view by 10 times the difference in coordinates. This com‐
		     mand is typically associated with mouse motion events  in
		     the widget, to produce the effect of dragging the text at
		     high speed through the window. The	 return	 value	is  an
		     empty string.

       pathName 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 following
	      switches	(or abbreviations thereof) may be specified to control
	      the search:

	      -forwards
		     The search will proceed forward through the text, finding
		     the  first	 matching range starting at or after the 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 (it is not allowed to be at index).
		     Note  that,  for a variety of reasons, backwards searches
		     can be substantially slower than forwards searches	 (par‐
		     ticularly	when using -regexp), so it is recommended that
		     performance-critical code use forward searches.

	      -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	and  the  re_syntax  page  for
		     details).	The default matching automatically passes both
		     the -lineanchor  and  -linestop  options  to  the	regexp
		     engine  (unless  -nolinestop  is  used), so that ^$ match
		     beginning and end of line, and ., [^ sequences will never
		     match the newline character \n.

	      -nolinestop
		     This allows . and [^ sequences to match the newline char‐
		     acter \n, which they will otherwise not do (see the  reg‐
		     exp  command for details). This option is only meaningful
		     if -regexp is also given, and an  error  will  be	thrown
		     otherwise.	 For  example,	to  match the entire text, use
		     “pathName search -nolinestop -regexp ".*" 1.0”.

	      -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 index positions
		     between beginning and end of the matching range  will  be
		     stored  in	 the variable. If there are no embedded images
		     or windows in the matching range (and there are no elided
		     characters if -elide is not given), this is equivalent to
		     the number of characters matched.	In  either  case,  the
		     range matchIdx to matchIdx + $count chars will return the
		     entire matched text.

	      -all   Find all matches in the given range and return a list  of
		     the  indices  of  the first character of each match. If a
		     -count varName switch is given, then varName is also  set
		     to	 a  list  containing  one  element for each successful
		     match. Note that, even for exact searches,	 the  elements
		     of	 this  list  may  be  different, if there are embedded
		     images, windows  or  hidden  text.	  Searches  with  -all
		     behave  very similarly to the Tcl command regexp -all, in
		     that overlapping matches are not normally	returned.  For
		     example,  applying	 an  -all  search of the pattern “\w+”
		     against “hello there” will just  match  twice,  once  for
		     each  word,  and  matching “Z[a-z]+Z” against “ZooZooZoo”
		     will just match once.

	      -overlap
		     When performing -all searches, the	 normal	 behaviour  is
		     that  matches  which  overlap an already-found match will
		     not be returned. This switch changes  that	 behaviour  so
		     that  all	matches	 which are not totally enclosed within
		     another match are	returned.  For	example,  applying  an
		     -overlap  search  of  the	pattern	 “\w+”	against “hello
		     there” will just match twice (i.e. no different  to  just
		     -all),  but  matching “Z[a-z]+Z” against “ZooZooZoo” will
		     now match twice. An error will be thrown if  this	switch
		     is used without -all.

	      -strictlimits
		     When  performing any search, the normal behaviour is that
		     the start and stop limits are checked with respect to the
		     start  of the matching text. With the -strictlimits flag,
		     the entire matching range must lie inside the  start  and
		     stop limits specified for the match to be valid.

	      -elide Find  elided  (hidden) text as well. By default only dis‐
		     played text is searched.

	      --     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 may be within a single line of text,  or  run
	      across  multiple lines (if parts of the pattern can match a new-
	      line). For regular expression matching one can use  the  various
	      newline-matching	features such as $ to match the end of a line,
	      ^ to match the beginning of a line, and to control whether .  is
	      allowed  to  match  a  new-line.	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.  This	 means
	      that,  for  example, if the search is -forwards but stopIndex is
	      earlier in the text than startIndex, nothing will ever be found.
	      See  KNOWN  BUGS	below for a number of minor limitations of the
	      pathName search command.

       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 is not 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 command
		     returns the script associated with tagName	 and  sequence
		     (an  error	 occurs	 if there is no such binding). If both
		     script and sequence are omitted then the command  returns
		     a	list of all the sequences for which bindings have been
		     defined for tagName.

		     The only events for which bindings may be	specified  are
		     those  related  to the mouse and keyboard (such as Enter,
		     Leave, ButtonPress,  Motion,  and	KeyPress)  or  virtual
		     events.  Event bindings for a text widget use the current
		     mark described under MARKS above. An Enter event triggers
		     for  a tag when the tag first becomes present on the cur‐
		     rent character, and a Leave event triggers for a tag when
		     it	 ceases	 to be present on the current character. Enter
		     and Leave events can happen either	 because  the  current
		     mark  moved  or  because  the  character at that position
		     changed. Note that these events are different than	 Enter
		     and  Leave	 events for windows. Mouse and keyboard events
		     are directed to the current 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 bindings
		     for a single tag, then the most specific binding is  cho‐
		     sen  (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 path‐
		     Name tag configure widget command.

	      pathName tag configure tagName ?option?  ?value?	?option	 value
	      ...?
		     This  command is similar to the pathName configure widget
		     command except that it modifies options  associated  with
		     the tag given by tagName instead of modifying options for
		     the overall text widget. If no option is  specified,  the
		     command  returns  a  list 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 have not been deleted by a “path‐
		     Name tag delete” widget command, even  if	no  characters
		     are  currently  marked  with  the	tag). The list will be
		     sorted in order from lowest priority to highest priority.

	      pathName tag nextrange tagName index1 ?index2?
		     This command searches the text for a range of  characters
		     tagged  with  tagName  where  the	first character of the
		     range is no earlier than the character at index1  and  no
		     later  than  the  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 is not affected). A single command may con‐
		     tain any number  of  index1-index2	 pairs.	 If  the  last
		     index2 is omitted then the tag is removed from the single
		     character at index1. 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  com‐
		     mand 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 window 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 information on
		     the options that are supported.

	      pathName window create index ?option value ...?
		     This command creates a new window annotation, which  will
		     appear  in	 the  text at the position given by index. Any
		     number of option-value pairs may be specified to  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 win‐
		     dow, and 40% of the text is off-screen to the right.  The
		     fractions refer only to the lines that are actually visi‐
		     ble 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. What must be	 units,	 pages
		     or	 pixels. If what is units or pages then number must be
		     an integer, otherwise number may be specified in  any  of
		     the  forms	 acceptable to Tk_GetPixels, such as “2.0c” or
		     “1i” (the result is rounded to the nearest integer value.
		     If	 no  units  are given, pixels are assumed). If what is
		     units, the view adjusts left or right by number  average-
		     width  characters on the display; if it is pages then the
		     view adjusts by number screenfuls; if it is  pixels  then
		     the  view adjusts by number pixels. If number is negative
		     then characters farther to the left become visible; if it
		     is	 positive  then characters farther to the right become
		     visible.

       pathName yview ?args?
	      This command is used to query and change the  vertical  position
	      of  the text in the widget's window. It can take any of the 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	visible	 pixel	of  the	 first
		     character	(or image, etc) 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 first pixel just after the last visi‐
		     ble 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 pixel given by
		     fraction appears at the top of the top line of  the  win‐
		     dow.  Fraction is a fraction between 0 and 1; 0 indicates
		     the first pixel of the first character in the text,  0.33
		     indicates the pixel that is one-third the way through the
		     text; and so on. Values close to 1 will  indicate	values
		     close to the last pixel in the text (1 actually refers to
		     one pixel beyond the last pixel), but in such  cases  the
		     widget  will never scroll beyond the last pixel, and so a
		     value of 1 will effectively be rounded back  to  whatever
		     fraction  ensures	the last pixel is at the bottom of the
		     window, and some other pixel is at the top.

	      pathName yview scroll number what
		     This command adjust the view in the  window  up  or  down
		     according	to  number and what. What must be units, pages
		     or pixels. If what is units or pages then number must  be
		     an	 integer,  otherwise number may be specified in any of
		     the forms acceptable to Tk_GetPixels, such as  “2.0c”  or
		     “1i” (the result is rounded to the nearest integer value.
		     If no units are given, pixels are assumed).  If  what  is
		     units, the view adjusts up or down by number lines on the
		     display; if it is pages then the view adjusts  by	number
		     screenfuls; if it is pixels then the view adjusts by num‐
		     ber pixels. 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 is not specified then
		     index will appear at the top of the window. If -pickplace
		     is	 specified then the widget chooses where index appears
		     in the window:

		     [1]    If index is already visible somewhere in the  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 pathName
		     see widget command (pathName see handles both x-  and  y-
		     motion to make a location visible, whereas the -pickplace
		     mode 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” is depen‐
       dent on the value of the tcl_wordchars variable. See tclvars(n).

       [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	start  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 start 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 Control-
	      Shift-Right move the insertion cursor by words and  also	extend
	      the  selection.  Control-b and Control-f behave the same as Left
	      and Right, respectively. Meta-b and Meta-f behave	 the  same  as
	      Control-Left and Control-Right, respectively.

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

       [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  display  line and clear any selection in the widget. Shift-
	      Home moves the insertion cursor to the beginning of the  display
	      line and also extends the selection to that point.

       [14]   End  and	Control-e  move the insertion cursor to the end of the
	      display line and clear any selection in  the  widget.  Shift-End
	      moves  the cursor to the end of the display 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. Control-
	      Shift-Home moves the insertion cursor to the  beginning  of  the
	      text and also extends the selection to that point.

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

       [17]   The Select key and Control-Space set the selection anchor to the
	      position of the insertion cursor. They do not 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.  This  action  is	carried	 out  by  the  command
	      tk_textCopy.

       [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.  This  action  is	carried	 out  by  the  command
	      tk_textCut.  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. This action is carried out by the  command
	      tk_textPaste.

       [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 after
	      copying it to the clipboard.

       [31]   Control-t reverses the order of the two characters to the	 right
	      of the insertion cursor.

       [32]   Control-z (and Control-underscore on UNIX when tk_strictMotif is
	      true) undoes the last edit action if the -undo option  is	 true.
	      Does nothing otherwise.

       [33]   Control-Z	 (or  Control-y	 on Windows) reapplies the last undone
	      edit action if the -undo option is true. Does nothing otherwise.

       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.

KNOWN ISSUES
   ISSUES CONCERNING CHARS AND INDICES
       Before  Tk  8.5,	 the  widget used the string “chars” to refer to index
       positions (which included characters,  embedded	windows	 and  embedded
       images).	 As  of	 Tk 8.5 the text widget deals separately and correctly
       with “chars” and “indices”.  For backwards compatibility, however,  the
       index modifiers “+N chars” and “-N chars” continue to refer to indices.
       One must use any of the full forms “+N any chars”  or  “-N  any	chars”
       etc.  to refer to actual character indices. This confusion may be fixed
       in a future release by making the widget correctly interpret “+N chars”
       as a synonym for “+N any chars”.

   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  num‐
       ber  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.

   KNOWN BUGS
       The pathName search -regexp sub-command attempts to  perform  sophisti‐
       cated  regexp  matching	across	multiple lines in an efficient fashion
       (since Tk 8.5), examining each line individually,  and  then  in	 small
       groups of lines, whether searching forwards or backwards. Under certain
       conditions the search result might differ from that obtained by	apply‐
       ing  the	 same regexp to the entire text from the widget in one go. For
       example, when searching with a greedy regexp, the widget will  continue
       to attempt to add extra lines to the match as long as one of two condi‐
       tions are true: either Tcl's regexp library returns a code to  indicate
       a  longer match is possible (but there are known bugs in Tcl which mean
       this code is not always correctly returned);  or	 if  each  extra  line
       added  results in at least a partial match with the pattern. This means
       in the case where the first extra line added results in	no  match  and
       Tcl's  regexp  system  returns  the  incorrect code and adding a second
       extra line would actually match, the text widget will return the	 wrong
       result. In practice this is a rare problem, but it can occur, for exam‐
       ple:
	      pack [text .t]
	      .t insert 1.0 "aaaa\nbbbb\ncccc\nbbbb\naaaa\n"
	      .t search -regexp -- {(a+|b+\nc+\nb+)+\na+} 1.0
       will not find a match when one exists of 19  characters	starting  from
       the first “b”.

       Whenever	 one  possible	match is fully enclosed in another, the search
       command will attempt to ensure only the larger match is returned.  When
       performing  backwards  regexp searches it is possible that Tcl will not
       always achieve this, in the case where a match is preceded  by  one  or
       more  short,  non-overlapping  matches,	all of which are preceded by a
       large match which actually encompasses all of them.  The	 search	 algo‐
       rithm  used by the widget does not look back arbitrarily far for a pos‐
       sible match which might cover large portions of the widget.  For	 exam‐
       ple:
	      pack [text .t]
	      .t insert 1.0 "aaaa\nbbbb\nbbbb\nbbbb\nbbbb\n"
	      .t search -regexp -backward -- {b+\n|a+\n(b+\n)+} end
       matches	at “5.0” when a true greedy match would match at “1.0”.	 Simi‐
       larly if we add -all to this case, it matches at all of	“5.0”,	“4.0”,
       “3.0”  and  “1.0”, when really it should only match at “1.0” since that
       match encloses all the others.

SEE ALSO
       entry(n), scrollbar(n)

KEYWORDS
       text, widget, tkvars

Tk				      8.5			       text(n)
[top]

List of man pages available for SmartOS

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