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
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.
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.
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
+ 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
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
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
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
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
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.
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.
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
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
returns an empty string. Option may have any of
the values accepted by the text command.
pathName debug ?boolean?
If boolean is specified, then it must have one of
the true or false values accepted by
Tcl_GetBoolean. If the value is a true one then
internal consistency checks will be turned on in
the B-tree code associated with text widgets. If
boolean has a false value then the debugging checks
will be turned off. In either case the command
returns an empty string. If boolean is not speci-
fied then the command returns on or off to indicate
whether or not debugging is turned on. There is a
single debugging switch shared by all text widgets:
turning debugging on or off in any widget turns it
on or off for all widgets. For widgets with large
amounts of text, the consistency checks may cause a
noticeable slow-down.
pathName delete index1 ?index2?
Delete a range of characters from the text. If
both index1 and index2 are specified, then delete
all the characters starting with the one given by
index1 and stopping just before index2 (i.e. the
character at index2 is not deleted). If index2
doesn't specify a position later in the text than
index1 then no characters are deleted. If index2
isn't specified then the 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-
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
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-
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
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
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
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
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
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
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.
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
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,
-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,
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.
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.
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.
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.
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