text man page on BSDi

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



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

_________________________________________________________________

NAME
       text - Create and manipulate text widgets

SYNOPSIS
       text pathName ?options?

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

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

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

	      Specifies the desired height  for	 the  window,  in
	      units  of characters in the font given by the -font
	      option.  Must be at least one.

       Command-Line Name:-spacing1
       Database Name:  spacing1
       Database Class: Spacing1

	      Requests additional space above each text	 line  in
	      the  widget,  using  any	of the standard forms for
	      screen distances.	 If a  line  wraps,  this  option
	      only  applies  to	 the  first  line on the display.
	      This option may be overriden with -spacing1 options
	      in tags.

       Command-Line Name:-spacing2
       Database Name:  spacing2
       Database Class: Spacing2

	      For  lines  that wrap (so that they cover more than
	      one line on  the	display)  this	option	specifies
	      additional  space	 to  provide  between the display
	      lines that represent a single line  of  text.   The
	      value may have any of the standard forms for screen
	      distances.   This	 option	 may  be  overriden  with
	      -spacing2 options in tags.

       Command-Line Name:-spacing3
       Database Name:  spacing3
       Database Class: Spacing3

Tk			       4.0				1

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

	      Requests	additional  space below each text line in
	      the widget, using any of	the  standard  forms  for
	      screen  distances.   If  a  line wraps, this option
	      only applies to the last line on the display.  This
	      option  may  be overriden with -spacing3 options in
	      tags.

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

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

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

	      Specifies a set of tab stops for the  window.   The
	      option's	value  consists	 of a list of screen dis-
	      tances giving the positions of the tab stops.  Each
	      position	may  optionally	 be  followed in the next
	      list element by one of the  keywords  left,  right,
	      center,  or numeric, which specifies how to justify
	      text  relative  to  the  tab  stop.   Left  is  the
	      default; it causes the text following the tab char-
	      acter to be positioned with its left  edge  at  the
	      tab  position.   Right means that the right edge of
	      the text following the tab character is  positioned
	      at the tab position, and center means that the text
	      is centered at the  tab  position.   Numeric  means
	      that the decimal point in the text is positioned at
	      the tab position;	 if there  is  no  decimal  point
	      then  the	 least significant digit of the number is
	      positioned just to the left of  the  tab	position;
	      if  there is no number in the text then the text is
	      right-justified at the tab position.  For	 example,
	      -tabs  {2c  left	4c  6c	center} creates three tab
	      stops at two-centimeter intervals;  the  first  two
	      use  left	 justification	and the third uses center
	      justification.  If the list of tab stops	does  not
	      have  enough elements to cover all of the tabs in a
	      text line, then Tk extrapolates new tab stops using
	      the spacing and alignment from the last tab stop in
	      the list.	 The value of  the  tabs  option  may  be
	      overridden  by  -tabs options in tags.  If no -tabs
	      option is specified, or if it is	specified  as  an
	      empty  list, then Tk uses default tabs spaced every
	      eight (average size) characters.

       Command-Line Name:-width

Tk			       4.0				2

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

       Database Name:  width
       Database Class: Width

	      Specifies the desired width for the window in units
	      of  characters  in  the  font  given  by	the -font
	      option.  If the font doesn't have a  uniform  width
	      then  the	 width	of the character ``0'' is used in
	      translating from character units to screen units.

       Command-Line Name:-wrap
       Database Name:  wrap
       Database Class: Wrap

	      Specifies how to handle lines in the text that  are
	      too  long	 to  be displayed in a single line of the
	      text's window.  The value must be none or	 char  or
	      word.   A wrap mode of none means that each line of
	      text appears as exactly one  line	 on  the  screen;
	      extra  characters	 that don't fit on the screen are
	      not displayed.  In the other  modes  each	 line  of
	      text will be broken up into several screen lines if
	      necessary to keep all the characters  visible.   In
	      char  mode  a screen line break may occur after any
	      character; in word mode a line break will	 only  be
	      made at word boundaries.
_________________________________________________________________

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

       A  text	widget	displays  one  or  more lines of text and
       allows that text to be edited.  Text widgets support three
       different  kinds	 of annotations on the text, called tags,
       marks, and embedded windows.  Tags  allow  different  por-
       tions of the text to be displayed with different fonts and
       colors.	In addition, Tcl commands can be associated  with
       tags  so	 that scripts are invoked when particular actions
       such as keystrokes and mouse button presses occur in  par-
       ticular	ranges	of  the	 text.	 See  TAGS below for more
       details.

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

       The  third  form of annotation allows arbitrary windows to

Tk			       4.0				3

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

       be embedded in a text widget.  See EMBEDDED WINDOWS  below
       for more details.

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

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

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

       @x,y	   Indicates the character that covers the  pixel
		   whose  x  and  y coordinates within the text's
		   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 characters are currently tagged
		   with tag.

       tag.last	   Indicates  the  character  just after the last
		   one in the text that has been tagged with tag.
		   This	 form generates an error if no characters
		   are currently tagged with tag.

       pathName	   Indicates the position of the embedded  window
		   whose  name	is pathName.  This form generates
		   an error if there is no embedded window by the
		   given name.

       If  modifiers follow the base index, each one of them must
       have one of the forms  listed  below.   Keywords	 such  as
       chars  and  wordend  may	 be  abbreviated  as  long as the

Tk			       4.0				4

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

       abbreviation is unambiguous.

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

       - count chars
	      Adjust the index backward by count characters, mov-
	      ing to earlier lines in the text if necessary.   If
	      there  are  fewer than count characters in the text
	      before the current index, then set the index to the
	      first character in the text.  Spaces on either side
	      of count are optional.

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

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

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

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

       wordstart
	      Adjust the index to refer to the first character of

Tk			       4.0				5

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

	      the word containing the current index.  A word con-
	      sists of any number of adjacent characters that are
	      letters,	digits, or underscores, or a single char-
	      acter that is not one of these.

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

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

TAGS
       The  first form of annotation in text widgets is a tag.	A
       tag is a textual string that is associated  with	 some  of
       the  characters	in  a  text.   Tags may contain arbitrary
       characters, but it is probably best to avoid using the the
       characters  ``  '' (space), +, or -: these characters have
       special meaning in indices, so tags containing them  can't
       be used as indices.  There may be any number of tags asso-
       ciated with characters in a text.  Each tag may refer to a
       single character, a range of characters, or several ranges
       of characters.  An individual character may have any  num-
       ber of tags associated with it.

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

       Tags serve three purposes in text  widgets.   First,  they
       control	the  way  information is displayed on the screen.
       By default, characters are displayed as determined by  the
       background, font, and foreground options for the text wid-
       get.  However, display  options	may  be	 associated  with
       individual  tags using the ``pathName tag configure'' wid-
       get command.  If a character has	 been  tagged,	then  the
       display	options	 associated  with  the	tag  override the
       default display style.  The  following  options	are  cur-
       rently supported for tags:

       -background color
	      Color  specifies	the  background	 color to use for

Tk			       4.0				6

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

	      characters associated with the tag.   It	may  have
	      any of the forms accepted by Tk_GetColor.

       -bgstipple bitmap
	      Bitmap specifies a bitmap that is used as a stipple
	      pattern for the background.  It may have any of the
	      forms  accepted  by Tk_GetBitmap.	 If bitmap hasn't
	      been specified, or if it is specified as	an  empty
	      string,  then  a	solid  fill  will be used for the
	      background.

       -borderwidth pixels
	      Pixels specifies the width of a 3-D border to  draw
	      around  the  background.	 It  may  have any of the
	      forms accepted by	 Tk_GetPixels.	 This  option  is
	      used in conjunction with the -relief option to give
	      a 3-D appearance to the background for  characters;
	      it  is  ignored  unless  the -background option has
	      been set for the tag.

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

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

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

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

       -lmargin1 pixels
	      If the first character of a text line has a tag for
	      which  this  option has been specified, then pixels
	      specifies how much the line should be indented from
	      the  left	 edge of the window.  Pixels may have any
	      of the standard forms for screen distances.   If	a

Tk			       4.0				7

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

	      line of text wraps, this option only applies to the
	      first line on the display;   the	-lmargin2  option
	      controls the indentation for subsequent lines.

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

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

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

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

       -spacing1 pixels
	      Pixels  specifies	 how much additional space should
	      be left above each text  line,  using  any  of  the
	      standard	forms  for  screen  distances.	If a line

Tk			       4.0				8

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

	      wraps, this option only applies to the  first  line
	      on the display.

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

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

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

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

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

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

       The second purpose for tags is event  bindings.	 You  can
       associate bindings with a tag in much the same way you can
       associate  bindings  with  a   widget   class:	 whenever

Tk			       4.0				9

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

       particular  X  events  occur  on characters with the given
       tag, a given Tcl command will be executed.   Tag	 bindings
       can  be	used  to  give behaviors to ranges of characters;
       among other things, this allows hypertext-like features to
       be  implemented.	  For details, see the description of the
       tag bind widget command below.

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

MARKS
       The  second  form of annotation in text widgets is a mark.
       Marks are used for  remembering	particular  places  in	a
       text.   They  are  something  like tags, in that they have
       names and they refer to places in the  file,  but  a  mark
       isn't  associated  with particular characters.  Instead, a
       mark is associated with the gap	between	 two  characters.
       Only  a	single	position may be associated with a mark at
       any given time.	If  the	 characters  around  a	mark  are
       deleted the mark will still remain;  it will just have new
       neighbor characters.  In contrast, if the characters  con-
       taining a tag are deleted then the tag will no longer have
       an association with characters in the file.  Marks may  be
       manipulated with the ``pathName mark'' widget command, and
       their current locations may be  determined  by  using  the
       mark name as an index in widget commands.

       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
       position.   If  the  mark  has  right  gravity,	new  text
       inserted at the mark position will appear to the right  of
       the mark.  The gravity for a mark defaults to right.

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

       Two  marks  have	 special  significance.	  First, the mark
       insert  is  associated  with  the  insertion  cursor,   as
       described  under	 THE INSERTION CURSOR below.  Second, the
       mark current is associated with the character  closest  to
       the mouse and is adjusted automatically to track the mouse
       position and any changes to the text in	the  widget  (one
       exception:   current  is	 not updated in response to mouse
       motions if a mouse button is down;   the	 update	 will  be
       deferred	 until	all  mouse  buttons  have been released).
       Neither of these special marks may be deleted.

Tk			       4.0			       10

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

EMBEDDED WINDOWS
       The third form of annotation in text widgets is an  embed-
       ded window.  Each embedded window annotation causes a win-
       dow to be displayed at a particular point  in   the  text.
       There may be any number of embedded windows in a text wid-
       get, 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 win-
       dow's position on the screen will be updated as	the  text
       is  modified  or	 scrolled,  and	 it  will  be  mapped and
       unmapped as it moves into and out of the visible	 area  of
       the  text widget.  Each embedded window occupies one char-
       acter's worth of index space in the text	 widget,  and  it
       may be referred to either by the name of its embedded win-
       dow or by its position in the widget's  index  space.   If
       the  range  of  text  containing	 the  embedded	window is
       deleted then the window is destroyed.

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

       -align where
	      If the window is not as tall as the line	in  which
	      it  is  displayed, this option determines where the
	      window is displayed in the line.	Where  must  have
	      one  of the values top (align the top of the window
	      with the top of the line), center (center the  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 window for the annotation.  If no -win-
	      dow option has been specified  for  the  annotation
	      this  script  will be evaluated when the annotation
	      is about to be displayed	on  the	 screen.   Script
	      must  create a window for the annotation and return
	      the name of that window  as  its	result.	  If  the
	      annotation's  window should ever be deleted, script
	      will be evaluated again the next time  the  annota-
	      tion 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 dis-
	      tance.

Tk			       4.0			       11

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

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

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

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

THE SELECTION
       Text widgets support the standard X selection.	Selection
       support	is  implemented via tags.  If the exportSelection
       option for the text widget is true then the sel	tag  will
       be associated with the selection:

       [1]    Whenever	characters  are	 tagged with sel the text
	      widget will claim ownership of the selection.

       [2]    Attempts to retrieve the selection will be serviced
	      by  the  text  widget, returning all the characters
	      with the sel tag.

       [3]    If the selection is claimed away by another  appli-
	      cation  or  by  another window within this applica-
	      tion, then the sel tag will  be  removed	from  all
	      characters in the text.

       The sel tag is automatically defined when a text widget is
       created, and it may not be deleted with the ``pathName tag
       delete''	 widget	 command.   Furthermore,  the selectBack-
       ground, selectBorderWidth,  and	selectForeground  options
       for  the text widget are tied to the -background, -border-
       width, and -foreground options for the sel  tag:	  changes
       in either will automatically be reflected in the other.

THE INSERTION CURSOR
       The  mark  named	 insert	 has special significance in text
       widgets.	 It is defined automatically when a  text  widget
       is  created  and	 it  may not be unset with the ``pathName
       mark unset'' widget command.  The insert	 mark  represents
       the  position  of  the insertion cursor, and the insertion
       cursor will automatically be drawn at this point	 whenever

Tk			       4.0			       12

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

       the text widget has the input focus.

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

       pathName 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 ele-
	      ments give the width and height of  the  area.   If
	      the  character  is  only	partially  visible on the
	      screen, then the return  value  reflects	just  the
	      visible  part.   If the character is not visible on
	      the screen then the return value is an empty  list.

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

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

       pathName configure ?option? ?value option value ...?
	      Query  or	 modify	 the configuration options of the
	      widget.  If no option is specified, returns a  list
	      describing  all  of the available options for path-
	      Name (see Tk_ConfigureInfo for information  on  the
	      format  of this list).  If option is specified with
	      no value, then the command returns a list	 describ-
	      ing the one named option (this list will be identi-
	      cal to  the  corresponding  sublist  of  the  value
	      returned	if  no	option	is specified).	If one or
	      more option-value pairs  are  specified,	then  the
	      command modifies the given widget option(s) to have

Tk			       4.0			       13

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

	      the given	 value(s);   in	 this  case  the  command
	      returns  an  empty  string.  Option may have any of
	      the values accepted by the text command.

       pathName debug ?boolean?
	      If boolean is specified, then it must have  one  of
	      the  true	 or  false  values  accepted  by Tcl_Get-
	      Boolean.	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:  turn-
	      ing  debugging  on or off in any widget turns it on
	      or off for all widgets.	For  widgets  with  large
	      amounts of text, the consistency checks may cause a
	      noticeable slow-down.

       pathName delete index1 ?index2?
	      Delete a range of characters  from  the  text.   If
	      both  index1  and index2 are specified, then delete
	      all the characters starting with the one	given  by
	      index1  and  stopping  just before index2 (i.e. the
	      character at index2 is  not  deleted).   If  index2
	      doesn't  specify	a position later in the text than
	      index1 then no characters are deleted.   If  index2
	      isn't specified then the single character at index1
	      is deleted.  It is not allowable to delete  charac-
	      ters  in	a way that would leave the text without a
	      newline as the last character.  The command returns
	      an empty string.

       pathName 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 pix-
	      els.  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 contain-
	      ing index is not visible on  the	screen	then  the

Tk			       4.0			       14

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

	      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 infor-
	      mation is returned in the following format:

	      key1 value1 index1 key2 value2 index2 ...

	      The possible key	values	are  text,  mark,  tagon,
	      tagoff, and window.  The corresponding value is the
	      text, mark name, tag name,  or  window  name.   The
	      index  information is the index of the start of the
	      text, the mark, the tag transition, or the  window.
	      One or more of the following switches (or abbrevia-
	      tions thereof) may  be  specified	 to  control  the
	      dump:

	      -all   Return information about all elements: text,
		     marks,  tags,  and	 windows.   This  is  the
		     default.

	      -command command
		     Instead  of returning the information as the
		     result of the  dump  operation,  invoke  the
		     command  on  each element of the text widget
		     within the range.	 The  command  has  three
		     arguments appended to it before it is evalu-
		     ated: the key, value, and index.

	      -mark  Include information about marks in the  dump
		     results.

	      -tag   Include information about tag transitions in
		     the  dump	results.   Tag	 information   is
		     returned  as  tagon and tagoff elements that
		     indicate the begin and end of each range  of
		     each tag, respectively.

	      -text  Include  information  about text in the dump
		     results.  The value is the text  up  to  the
		     next  element  or the end of range indicated
		     by index2.	 A text	 element  does	not  span
		     newlines.	 A  multi-line block of text that
		     contains no marks or  tag	transitions  will
		     still  be	dumped	as a set of text seqments
		     that each end with a newline.   The  newline
		     is part of the value.

	      -window
		     Include  information  about embedded windows

Tk			       4.0			       15

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

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

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

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

       pathName insert index chars ?tagList chars tagList ...?
	      Inserts all of the chars arguments just before  the
	      character	 at index.  If index refers to the end of
	      the text (the character  after  the  last	 newline)
	      then  the new text is inserted just before the last
	      newline instead.	If there is a single chars  argu-
	      ment and no tagList, then the new text will receive
	      any tags that are present	 on  both  the	character
	      before and the character after the insertion point;
	      if a tag is present on only one of these characters
	      then  it	will  not be applied to the new text.  If
	      tagList is specified then it consists of a list  of
	      tag  names;  the new characters will receive all of
	      the tags in this list and no others, regardless  of
	      the  tags	 present  around the insertion point.  If
	      multiple chars-tagList argument pairs are	 present,
	      they  produce  the  same	effect	as  if a separate
	      insert widget 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  fol-
	      lowing   forms   of   the	  command  are	currently

Tk			       4.0			       16

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

	      supported:

	      pathName mark gravity markName ?direction?
		     If direction is not specified, returns  left
		     or	 right	to indicate which of its adjacent
		     characters	 markName  is  attached	 to.   If
		     direction	is  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  immediately	after  that mark.
		     This can still return a  mark  at	the  same
		     position  if there are multiple marks at the
		     same index.  These semantics mean	that  the
		     mark  next	 operation  can	 be  used to step
		     through all the marks in a	 text  widget  in
		     the  same	order  as  the	mark  information
		     returned by the dump operation.  If  a  mark
		     has  been set to the special end index, then
		     it appears to be after end with  respect  to
		     the mark next operation.  An empty string is
		     returned if there are no marks after  index.

	      pathName mark previous index
		     Returns  the  name	 of the mark at or before
		     index.  If index is specified  in	numerical
		     form,  then the search for the previous mark
		     begins with the character just  before  that
		     index.  If index is the name of a mark, then
		     the search for the next mark begins  immedi-
		     ately  before  that  mark.	  This	can still
		     return a mark at the same position if  there
		     are multiple marks at the same index.  These
		     semantics mean that the mark previous opera-
		     tion  can	be  used  to step through all the
		     marks in a text widget in the reverse  order
		     as the mark information returned by the dump
		     operation.	 An empty string is  returned  if
		     there are no marks before index.

	      pathName mark set markName index
		     Sets  the	mark named markName to a position
		     just before  the  character  at  index.   If
		     markName  already	exists,	 it is moved from

Tk			       4.0			       17

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

		     its old position; if it doesn't exist, a new
		     mark  is  created.	  This command returns an
		     empty string.

	      pathName mark unset markName ?markName markName
	      ...?
		     Remove the mark corresponding to each of the
		     markName arguments.  The removed marks  will
		     not  be  usable  in  indices and will not be
		     returned by future calls to ``pathName  mark
		     names''.	This  command  returns	an  empty
		     string.

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

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

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

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

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

	      -backwards
		     The search will proceed backward through the

Tk			       4.0			       18

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

		     text,  finding the matching range closest to
		     index whose first character is before index.

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

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

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

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

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

	      The matching range must be entirely within a single
	      line of text.  For regular expression matching  the
	      newlines	are  removed  from  the ends of the lines
	      before matching:	use  the  $  feature  in  regular
	      expressions  to match the end of a line.	For exact
	      matching the newlines are retained.   If	stopIndex
	      is  specified,  the search stops at that index: for
	      forward searches, no match at  or	 after	stopIndex
	      will  be	considered;   for  backward  searches, no
	      match earlier in the text than  stopIndex	 will  be
	      considered.   If	stopIndex  is omitted, the entire
	      text will be searched: when the beginning or end of
	      the  text	 is  reached, the search continues at the
	      other end until the starting  location  is  reached
	      again;   if  stopIndex is specified, no wrap-around
	      will occur.

       pathName see index
	      Adjusts the view in the window so that the  charac-
	      ter 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 com-
	      mand 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.

Tk			       4.0			       19

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

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

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

	      pathName tag bind tagName ?sequence? ?script?
		     This  command associates script with the tag
		     given  by	tagName.   Whenever   the   event
		     sequence  given  by  sequence  occurs  for a
		     character that has been tagged with tagName,
		     the  script  will	be  invoked.  This widget
		     command  is  similar  to  the  bind  command
		     except  that  it operates on characters in a
		     text rather than entire  widgets.	 See  the
		     bind  manual  entry  for complete details on
		     the syntax of sequence and the substitutions
		     performed	on script before invoking it.  If
		     all arguments are specified then a new bind-
		     ing is created, replacing any existing bind-
		     ing 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.  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

Tk			       4.0			       20

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

		     on the current character, and a Leave  event
		     triggers for a tag when it ceases to be pre-
		     sent 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  charac-
		     ter.

		     It	 is possible for the current character to
		     have multiple tags, and for each of them  to
		     have   a  binding	for  a	particular  event
		     sequence.	When this occurs, one binding  is
		     invoked  for each tag, in order from lowest-
		     priority to highest priority.  If there  are
		     multiple matching bindings for a single tag,
		     then the most  specific  binding  is  chosen
		     (see  the	manual entry for the bind command
		     for details).  continue and  break	 commands
		     within  binding scripts are processed in the
		     same way as for bindings  created	with  the
		     bind command.

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

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

	      pathName tag configure tagName  ?option?	?value?
	      ?option  value ...?
		     This command is  similar  to  the	configure
		     widget   command  except  that  it	 modifies
		     options associated with  the  tag	given  by
		     tagName instead of modifying options for the
		     overall text widget.  If no option is speci-
		     fied,  the command returns a list describing
		     all of the	 available  options  for  tagName
		     (see Tk_ConfigureInfo for information on the
		     format of this list).  If option  is  speci-
		     fied with no value, then the command returns
		     a list describing the one named option (this
		     list  will be identical to the corresponding
		     sublist of the value returned if  no  option
		     is	 specified).  If one or more option-value

Tk			       4.0			       21

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

		     pairs are specified, then the command  modi-
		     fies  the	given option(s) to have the given
		     value(s) in tagName; in this case	the  com-
		     mand  returns  an	empty  string.	 See TAGS
		     above for details on the  options	available
		     for tags.

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

	      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 char-
		     acter  position given by index.  If index is
		     omitted, then the return value will describe
		     all  of  the  tags	 that  exist for the text
		     (this includes all tags that have been named
		     in	 a  ``pathName	tag''  widget command but
		     haven't been deleted  by  a  ``pathName  tag
		     delete''  widget command, even if no charac-
		     ters are currently	 marked	 with  the  tag).
		     The list will be sorted in order from lowest
		     priority to highest priority.

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

Tk			       4.0			       22

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

	      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 con-
		     tains the index of the  first  character  of
		     the  range,  and  the  second element of the
		     pair contains the	index  of  the	character
		     just  after  the  last one in the range.  If
		     there are no characters tagged with tag then
		     an empty string is returned.

	      pathName tag remove tagName index1 ?index2 index1
	      index2 ...?
		     Remove the tag tagName from all of the char-
		     acters  starting  at  index1 and ending just
		     before index2 (the character at index2 isn't
		     affected).	 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  char-
		     acters  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.

Tk			       4.0			       23

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

       pathName window option ?arg arg ...?
	      This  command  is	 used to manipulate embedded win-
	      dows.  The 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 window cget index option
		     Returns  the value of a configuration option
		     for an embedded  window.	Index  identifies
		     the  embedded window, and option specifies a
		     particular 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 win-
		     dow  at  index  (see  Tk_ConfigureInfo   for
		     information on the format of this list).  If
		     option is specified with no value, then  the
		     command  returns  a  list describing the one
		     named option (this list will be identical to
		     the   corresponding  sublist  of  the  value
		     returned if no option is specified).  If one
		     or	 more  option-value  pairs are specified,
		     then  the	 command   modifies   the   given
		     option(s)	to  have  the given value(s);  in
		     this  case	 the  command  returns	an  empty
		     string.   See  EMBEDDED WINDOWS for informa-
		     tion on the options that are supported.

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

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

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

	      pathName xview
		     Returns  a	 list  containing  two	elements.

Tk			       4.0			       24

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

		     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 visible in the  win-
		     dow:   if	the  lines  in the window are all
		     very short, so that they are entirely  visi-
		     ble, the returned fractions will be 0 and 1,
		     even if there are other lines  in	the  text
		     that  are much wider than the window.  These
		     are the same values passed to scrollbars via
		     the -xscrollcommand option.

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

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

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

	      pathName yview
		     Returns a list containing two elements, both
		     of which are real fractions between 0 and 1.
		     The  first element gives the position of the
		     first character in the top line in the  win-
		     dow,  relative  to	 the text as a whole (0.5
		     means it is halfway through  the  text,  for
		     example).	 The  second  element  gives  the
		     position of the  character	 just  after  the
		     last  one	in the bottom line of the window,
		     relative to the text as a whole.  These  are

Tk			       4.0			       25

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

		     the same values passed to scrollbars via the
		     -yscrollcommand option.

	      pathName yview moveto fraction
		     Adjusts the view in the window so	that  the
		     character	given  by fraction appears on the
		     top line of the window.  Fraction is a frac-
		     tion between 0 and 1;  0 indicates the first
		     character in the text,  0.33  indicates  the
		     character	one-third  the	way  through  the
		     text, and so on.

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

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

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

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

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

		      [4]    Otherwise, index will be centered in
			     the window.

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

Tk			       4.0			       26

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

		     y).

	      pathName yview number
		     This command makes the  first  character  on
		     the line after the one given by number visi-
		     ble 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 descrip-
       tions below, ``word'' refers to a contiguous group of let-
       ters, digits, or ``_'' characters, or any single character
       other than these.

       [1]    Clicking mouse button  1	positions  the	insertion
	      cursor  just  before  the	 character underneath the
	      mouse cursor, sets the input focus to this  widget,
	      and  clears  any selection in the widget.	 Dragging
	      with mouse button 1 strokes out a selection between
	      the  insertion  cursor  and the character under the
	      mouse.

       [2]    Double-clicking with mouse  button  1  selects  the
	      word  under  the	mouse and positions the insertion
	      cursor at the  beginning	of  the	 word.	 Dragging
	      after  a	double	click will stroke out a selection
	      consisting of whole words.

       [3]    Triple-clicking with mouse  button  1  selects  the
	      line  under  the	mouse and positions the insertion
	      cursor at the  beginning	of  the	 line.	 Dragging
	      after  a	triple	click will stroke out a selection
	      consisting of whole lines.

       [4]    The ends of the selection can be adjusted by  drag-
	      ging  with  mouse	 button	 1 while the Shift key is
	      down;  this will adjust the end  of  the	selection
	      that  was nearest to the mouse cursor when button 1
	      was  pressed.   If  the  button  is  double-clicked
	      before dragging then the selection will be adjusted
	      in units of whole words;	if it  is  triple-clicked
	      then  the	 selection  will  be adjusted in units of
	      whole lines.

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

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

Tk			       4.0			       27

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

       [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  inser-
	      tion  cursor moves and the selection is extended to
	      include the new character.  Control-Left	and  Con-
	      trol-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.
	      Control-Up and Control-Down move the insertion cur-
	      sor  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  Con-
	      trol-n  behave  the  same	 as  Up and Down, respec-
	      tively.

       [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 selec-
	      tion is extended	to  include  the  new  character.
	      Control-v moves the view down one screenful without
	      moving the insertion cursor or adjusting the selec-
	      tion.

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

       [13]   Home and Control-a move the insertion cursor to the

Tk			       4.0			       28

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

	      beginning of its line and clear  any  selection  in
	      the  widget.  Shift-Home moves the insertion cursor
	      to the beginning of the line and also  extends  the
	      selection to that point.

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

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

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

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

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

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

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

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

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

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

Tk			       4.0			       29

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

       [24]   Backspace	 and  Control-h	 delete the selection, if
	      there is one in the widget.  If there is no  selec-
	      tion,  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 inser-
	      tion 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 cursor.

       [29]   Meta-backspace  and  Meta-Delete delete the word to
	      the left of the insertion cursor.

       [30]   Control-x deletes whatever is selected in the  text
	      widget.

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

       If the widget is disabled using the  -state  option,  then
       its  view  can  still  be  adjusted  and text can still be
       selected, but no insertion cursor will be displayed and no
       text modifications will take place.

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

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

Tk			       4.0			       30

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

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

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

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

KEYWORDS
       text, widget

Tk			       4.0			       31

[top]

List of man pages available for BSDi

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