1490 lines
65 KiB
Plaintext
1490 lines
65 KiB
Plaintext
'\"
|
|
'\" Copyright (c) 1992 The Regents of the University of California.
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
'\" SCCS: @(#) text.n 1.64 96/08/27 13:21:22
|
|
'\"
|
|
.so man.macros
|
|
.TH text n 4.0 Tk "Tk Built-In Commands"
|
|
.BS
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
|
.SH NAME
|
|
text \- Create and manipulate text widgets
|
|
.SH SYNOPSIS
|
|
\fBtext\fI \fIpathName \fR?\fIoptions\fR?
|
|
.SO
|
|
\-background \-highlightbackground \-insertontime \-selectborderwidth
|
|
\-borderwidth \-highlightcolor \-insertwidth \-selectforeground
|
|
\-cursor \-highlightthickness \-padx \-setgrid
|
|
\-exportselection \-insertbackground \-pady \-takefocus
|
|
\-font \-insertborderwidth \-relief \-xscrollcommand
|
|
\-foreground \-insertofftime \-selectbackground \-yscrollcommand
|
|
.SE
|
|
.SH "WIDGET-SPECIFIC OPTIONS"
|
|
.OP \-height height Height
|
|
Specifies the desired height for the window, in units of characters
|
|
in the font given by the \fB\-font\fR option.
|
|
Must be at least one.
|
|
.OP \-spacing1 spacing1 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 \fB\-spacing1\fR options in
|
|
tags.
|
|
.OP \-spacing2 spacing2 Spacing2
|
|
For lines that wrap (so that they cover more than one line on the
|
|
display) this option specifies additional space to provide between
|
|
the display lines that represent a single line of text.
|
|
The value may have any of the standard forms for screen distances.
|
|
This option may be overriden with \fB\-spacing2\fR options in
|
|
tags.
|
|
.OP \-spacing3 spacing3 Spacing3
|
|
Requests additional space below each text line in the widget,
|
|
using any of the standard forms for screen distances.
|
|
If a line wraps, this option only applies to the last line
|
|
on the display.
|
|
This option may be overriden with \fB\-spacing3\fR options in
|
|
tags.
|
|
.OP \-state state State
|
|
Specifies one of two states for the text: \fBnormal\fR or \fBdisabled\fR.
|
|
If the text is disabled then characters may not be inserted or deleted
|
|
and no insertion cursor will be displayed, even if the input focus is
|
|
in the widget.
|
|
.OP \-tabs tabs Tabs
|
|
Specifies a set of tab stops for the window. The option's value consists
|
|
of a list of screen distances giving the positions of the tab stops. Each
|
|
position may optionally be followed in the next list element
|
|
by one of the keywords \fBleft\fR, \fBright\fR, \fBcenter\fR,
|
|
or \fBnumeric\fR, which specifies how to justify
|
|
text relative to the tab stop. \fBLeft\fR is the default; it causes
|
|
the text following the tab character to be positioned with its left edge
|
|
at the tab position. \fBRight\fR means that the right edge of the text
|
|
following the tab character is positioned at the tab position, and
|
|
\fBcenter\fR means that the text is centered at the tab position.
|
|
\fBNumeric\fR 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, \fB\-tabs {2c left 4c 6c center}\fR 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 \fBtabs\fR option may be overridden by \fB\-tabs\fR
|
|
options in tags.
|
|
If no \fB\-tabs\fR option is specified, or if it is specified as
|
|
an empty list, then Tk uses default tabs spaced every eight
|
|
(average size) characters.
|
|
.OP \-width width Width
|
|
Specifies the desired width for the window in units of characters
|
|
in the font given by the \fB\-font\fR 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.
|
|
.OP \-wrap wrap Wrap
|
|
Specifies how to handle lines in the text that are too long to be
|
|
displayed in a single line of the text's window.
|
|
The value must be \fBnone\fR or \fBchar\fR or \fBword\fR.
|
|
A wrap mode of \fBnone\fR 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 \fBchar\fR mode a screen line break may occur after any character;
|
|
in \fBword\fR mode a line break will only be made at word boundaries.
|
|
.BE
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
The \fBtext\fR command creates a new window (given by the
|
|
\fIpathName\fR argument) and makes it into a text widget.
|
|
Additional
|
|
options, described above, may be specified on the command line
|
|
or in the option database
|
|
to configure aspects of the text such as its default background color
|
|
and relief. The \fBtext\fR command returns the
|
|
path name of the new window.
|
|
.PP
|
|
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 portions 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 particular ranges of the text.
|
|
See TAGS below for more details.
|
|
.PP
|
|
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.
|
|
.PP
|
|
The third form of annotation allows arbitrary windows to be
|
|
embedded in a text widget.
|
|
See EMBEDDED WINDOWS below for more details.
|
|
|
|
.SH INDICES
|
|
.PP
|
|
Many of the widget commands for texts take one or more indices
|
|
as arguments.
|
|
An index is a string used to indicate a particular place within
|
|
a text, such as a place to insert characters or one endpoint of a
|
|
range of characters to delete.
|
|
Indices have the syntax
|
|
.CS
|
|
\fIbase modifier modifier modifier ...\fR
|
|
.CE
|
|
Where \fIbase\fR gives a starting point and the \fImodifier\fRs
|
|
adjust the index from the starting point (e.g. move forward or
|
|
backward one character). Every index must contain a \fIbase\fR,
|
|
but the \fImodifier\fRs are optional.
|
|
.PP
|
|
The \fIbase\fR for an index must have one of the following forms:
|
|
.TP 12
|
|
\fIline\fB.\fIchar\fR
|
|
Indicates \fIchar\fR'th character on line \fIline\fR.
|
|
Lines are numbered from 1 for consistency with other UNIX programs
|
|
that use this numbering scheme.
|
|
Within a line, characters are numbered from 0.
|
|
If \fIchar\fR is \fBend\fR then it refers to the newline character
|
|
that ends the line.
|
|
.TP 12
|
|
\fB@\fIx\fB,\fIy\fR
|
|
Indicates the character that covers the pixel whose x and y coordinates
|
|
within the text's window are \fIx\fR and \fIy\fR.
|
|
.TP 12
|
|
\fBend\fR
|
|
Indicates the end of the text (the character just after the last
|
|
newline).
|
|
.TP 12
|
|
\fImark\fR
|
|
Indicates the character just after the mark whose name is \fImark\fR.
|
|
.TP 12
|
|
\fItag\fB.first\fR
|
|
Indicates the first character in the text that has been tagged with
|
|
\fItag\fR.
|
|
This form generates an error if no characters are currently tagged
|
|
with \fItag\fR.
|
|
.TP 12
|
|
\fItag\fB.last\fR
|
|
Indicates the character just after the last one in the text that has
|
|
been tagged with \fItag\fR.
|
|
This form generates an error if no characters are currently tagged
|
|
with \fItag\fR.
|
|
.TP 12
|
|
\fIpathName\fR
|
|
Indicates the position of the embedded window whose name is
|
|
\fIpathName\fR.
|
|
This form generates an error if there is no embedded window
|
|
by the given name.
|
|
.PP
|
|
If modifiers follow the base index, each one of them must have one
|
|
of the forms listed below. Keywords such as \fBchars\fR and \fBwordend\fR
|
|
may be abbreviated as long as the abbreviation is unambiguous.
|
|
.TP
|
|
\fB+ \fIcount\fB chars\fR
|
|
Adjust the index forward by \fIcount\fR characters, moving to later
|
|
lines in the text if necessary. If there are fewer than \fIcount\fR
|
|
characters in the text after the current index, then set the index
|
|
to the last character in the text.
|
|
Spaces on either side of \fIcount\fR are optional.
|
|
.TP
|
|
\fB\- \fIcount\fB chars\fR
|
|
Adjust the index backward by \fIcount\fR characters, moving to earlier
|
|
lines in the text if necessary. If there are fewer than \fIcount\fR
|
|
characters in the text before the current index, then set the index
|
|
to the first character in the text.
|
|
Spaces on either side of \fIcount\fR are optional.
|
|
.TP
|
|
\fB+ \fIcount\fB lines\fR
|
|
Adjust the index forward by \fIcount\fR lines, retaining the same
|
|
character position within the line. If there are fewer than \fIcount\fR
|
|
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 \fIcount\fR are optional.
|
|
.TP
|
|
\fB\- \fIcount\fB lines\fR
|
|
Adjust the index backward by \fIcount\fR lines, retaining the same
|
|
character position within the line. If there are fewer than \fIcount\fR
|
|
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 \fIcount\fR are optional.
|
|
.TP
|
|
\fBlinestart\fR
|
|
Adjust the index to refer to the first character on the line.
|
|
.TP
|
|
\fBlineend\fR
|
|
Adjust the index to refer to the last character on the line (the newline).
|
|
.TP
|
|
\fBwordstart\fR
|
|
Adjust the index to refer to the first character of the word containing
|
|
the current index. A word consists of any number of adjacent characters
|
|
that are letters, digits, or underscores, or a single character that
|
|
is not one of these.
|
|
.TP
|
|
\fBwordend\fR
|
|
Adjust the index to refer to the character just after the last one of the
|
|
word containing the current index. If the current index refers to the last
|
|
character of the text then it is not modified.
|
|
.PP
|
|
If more than one modifier is present then they are applied in
|
|
left-to-right order. For example, the index ``\fBend \- 1 chars\fR''
|
|
refers to the next-to-last character in the text and
|
|
``\fBinsert wordstart \- 1 c\fR'' refers to the character just before
|
|
the first one in the word containing the insertion cursor.
|
|
|
|
.SH TAGS
|
|
.PP
|
|
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), \fB+\fR, or \fB\-\fR:
|
|
these characters have special meaning in indices, so tags containing
|
|
them can't be used as indices.
|
|
There may be any number of tags associated with characters in a
|
|
text.
|
|
Each tag may refer to a single character, a range of characters, or
|
|
several ranges of characters.
|
|
An individual character may have any number of tags associated with it.
|
|
.PP
|
|
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
|
|
``\fIpathName \fBtag raise\fR'' and ``\fIpathName \fBtag lower\fR''
|
|
widget commands.
|
|
.PP
|
|
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
|
|
\fBbackground\fR, \fBfont\fR, and \fBforeground\fR options for the
|
|
text widget.
|
|
However, display options may be associated with individual tags
|
|
using the ``\fIpathName \fBtag configure\fR'' widget command.
|
|
If a character has been tagged, then the display options associated
|
|
with the tag override the default display style.
|
|
The following options are currently supported for tags:
|
|
.TP
|
|
\fB\-background \fIcolor\fR
|
|
\fIColor\fR specifies the background color to use for characters
|
|
associated with the tag.
|
|
It may have any of the forms accepted by \fBTk_GetColor\fR.
|
|
.TP
|
|
\fB\-bgstipple \fIbitmap\fR
|
|
\fIBitmap\fR specifies a bitmap that is used as a stipple pattern
|
|
for the background.
|
|
It may have any of the forms accepted by \fBTk_GetBitmap\fR.
|
|
If \fIbitmap\fR hasn't been specified, or if it is specified
|
|
as an empty string, then a solid fill will be used for the
|
|
background.
|
|
.TP
|
|
\fB\-borderwidth \fIpixels\fR
|
|
\fIPixels\fR specifies the width of a 3-D border to draw around
|
|
the background.
|
|
It may have any of the forms accepted by \fBTk_GetPixels\fR.
|
|
This option is used in conjunction with the \fB\-relief\fR
|
|
option to give a 3-D appearance to the background for characters;
|
|
it is ignored unless the \fB\-background\fR option
|
|
has been set for the tag.
|
|
.TP
|
|
\fB\-fgstipple \fIbitmap\fR
|
|
\fIBitmap\fR 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 \fBTk_GetBitmap\fR.
|
|
If \fIbitmap\fR hasn't been specified, or if it is specified
|
|
as an empty string, then a solid fill will be used.
|
|
.TP
|
|
\fB\-font \fIfontName\fR
|
|
\fIFontName\fR is the name of a font to use for drawing characters.
|
|
It may have any of the forms accepted by \fBTk_GetFontStruct\fR.
|
|
.TP
|
|
\fB\-foreground \fIcolor\fR
|
|
\fIColor\fR specifies the color to use when drawing text and other
|
|
foreground information such as underlines.
|
|
It may have any of the forms accepted by \fBTk_GetColor\fR.
|
|
.TP
|
|
\fB\-justify \fIjustify\fR
|
|
If the first character of a display line has a tag for which this
|
|
option has been specified, then \fIjustify\fR determines how to
|
|
justify the line.
|
|
It must be one of \fBleft\fR, \fBright\fR, or \fBcenter\fR.
|
|
If a line wraps, then the justification for each line on the
|
|
display is determined by the first character of that display line.
|
|
.TP
|
|
\fB\-lmargin1 \fIpixels\fR
|
|
If the first character of a text line has a tag for which this
|
|
option has been specified, then \fIpixels\fR specifies how
|
|
much the line should be indented from the left edge of the
|
|
window.
|
|
\fIPixels\fR may have any of the standard forms for screen
|
|
distances.
|
|
If a line of text wraps, this option only applies to the
|
|
first line on the display; the \fB\-lmargin2\fR option controls
|
|
the indentation for subsequent lines.
|
|
.TP
|
|
\fB\-lmargin2 \fIpixels\fR
|
|
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
|
|
\fIpixels\fR specifies how much the line should be indented from
|
|
the left edge of the window.
|
|
\fIPixels\fR 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.
|
|
.TP
|
|
\fB\-offset \fIpixels\fR
|
|
\fIPixels\fR specifies an amount by which the text's baseline
|
|
should be offset vertically from the baseline of the overall
|
|
line, in pixels.
|
|
For example, a positive offset can be used for superscripts
|
|
and a negative offset can be used for subscripts.
|
|
\fIPixels\fR may have any of the standard forms for screen
|
|
distances.
|
|
.TP
|
|
\fB\-overstrike \fIboolean\fR
|
|
Specifies whether or not to draw a horizontal rule through
|
|
the middle of characters.
|
|
\fIBoolean\fR may have any of the forms accepted by \fBTk_GetBoolean\fR.
|
|
.TP
|
|
\fB\-relief \fIrelief\fR
|
|
\fIRelief\fR specifies the 3-D relief to use for drawing backgrounds,
|
|
in any of the forms accepted by \fBTk_GetRelief\fR.
|
|
This option is used in conjunction with the \fB\-borderwidth\fR
|
|
option to give a 3-D appearance to the background for characters;
|
|
it is ignored unless the \fB\-background\fR option
|
|
has been set for the tag.
|
|
.TP
|
|
\fB\-rmargin \fIpixels\fR
|
|
If the first character of a display line has a tag for which this
|
|
option has been specified, then \fIpixels\fR specifies how wide
|
|
a margin to leave between the end of the line and the right
|
|
edge of the window.
|
|
\fIPixels\fR may have any of the standard forms for screen
|
|
distances.
|
|
This option is only used when wrapping is enabled.
|
|
If a text line wraps, the right margin for each line on the
|
|
display is determined by the first character of that display
|
|
line.
|
|
.TP
|
|
\fB\-spacing1 \fIpixels\fR
|
|
\fIPixels\fR specifies how much additional space should be
|
|
left above each text line, using any of the standard forms for
|
|
screen distances.
|
|
If a line wraps, this option only applies to the first
|
|
line on the display.
|
|
.TP
|
|
\fB\-spacing2 \fIpixels\fR
|
|
For lines that wrap, this option specifies how much additional
|
|
space to leave between the display lines for a single text line.
|
|
\fIPixels\fR may have any of the standard forms for screen
|
|
distances.
|
|
.TP
|
|
\fB\-spacing3 \fIpixels\fR
|
|
\fIPixels\fR 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.
|
|
.TP
|
|
\fB\-tabs \fItabList\fR
|
|
\fITabList\fR specifies a set of tab stops in the same form
|
|
as for the \fB\-tabs\fR 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 unspecified for the tag (the default).
|
|
If the option is specified as a non-empty string that is
|
|
an empty list, such as \fB\-tags\0{\0}\fR, then it requests
|
|
default 8-character tabs as described for the \fBtags\fR
|
|
widget option.
|
|
.TP
|
|
\fB\-underline \fIboolean\fR
|
|
\fIBoolean\fR specifies whether or not to draw an underline underneath
|
|
characters.
|
|
It may have any of the forms accepted by \fBTk_GetBoolean\fR.
|
|
.TP
|
|
\fB\-wrap \fImode\fR
|
|
\fIMode\fR specifies how to handle lines that are wider than the
|
|
text's window.
|
|
It has the same legal values as the \fB\-wrap\fR option
|
|
for the text widget: \fBnone\fR, \fBchar\fR, or \fBword\fR.
|
|
If this tag option is specified, it overrides the \fB\-wrap\fR option
|
|
for the text widget.
|
|
.PP
|
|
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 display option, then the default
|
|
style for the widget will be used.
|
|
.PP
|
|
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 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 \fBtag bind\fR widget
|
|
command below.
|
|
.PP
|
|
The third use for tags is in managing the selection.
|
|
See THE SELECTION below.
|
|
|
|
.SH MARKS
|
|
.PP
|
|
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 containing a tag are deleted then
|
|
the tag will no longer have an association with characters in
|
|
the file.
|
|
Marks may be manipulated with the ``\fIpathName \fBmark\fR'' widget
|
|
command, and their current locations may be determined by using the
|
|
mark name as an index in widget commands.
|
|
.PP
|
|
Each mark also has a \fIgravity\fR, which is either \fBleft\fR or
|
|
\fBright\fR.
|
|
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 \fBright\fR.
|
|
.PP
|
|
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.
|
|
.PP
|
|
Two marks have special significance.
|
|
First, the mark \fBinsert\fR is associated with the insertion cursor,
|
|
as described under THE INSERTION CURSOR below.
|
|
Second, the mark \fBcurrent\fR 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: \fBcurrent\fR 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.
|
|
|
|
.SH EMBEDDED WINDOWS
|
|
.PP
|
|
The third form of annotation in text widgets is an embedded window.
|
|
Each embedded window annotation causes a window to be displayed
|
|
at a particular point in the text.
|
|
There may be any number of embedded windows in a text widget,
|
|
and any widget may be used as an embedded window (subject to the
|
|
usual rules for geometry management, which require the text window
|
|
to be the parent of the embedded window or a descendant of its
|
|
parent).
|
|
The embedded window's position on the screen will be updated as the
|
|
text is modified or scrolled, and it will be mapped and unmapped as
|
|
it moves into and out of the visible area of the text widget.
|
|
Each embedded window occupies one character's worth of index space
|
|
in the text widget, and it may be referred to either by the name
|
|
of its embedded window or by its position in the widget's
|
|
index space.
|
|
If the range of text containing the embedded window is deleted then
|
|
the window is destroyed.
|
|
.PP
|
|
When an embedded window is added to a text widget with the
|
|
\fBwindow create\fR widget command, several configuration
|
|
options may be associated with it.
|
|
These options may be modified later with the \fBwindow configure\fR
|
|
widget command.
|
|
The following options are currently supported:
|
|
.TP
|
|
\fB\-align \fIwhere\fR
|
|
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.
|
|
\fIWhere\fR must have one of the values \fBtop\fR (align the top of the window
|
|
with the top of the line), \fBcenter\fR (center the window
|
|
within the range of the line), \fBbottom\fR (align the bottom of the
|
|
window with the bottom of the line's area),
|
|
or \fBbaseline\fR (align the bottom of the window with the baseline
|
|
of the line).
|
|
.TP
|
|
\fB\-create \fIscript\fR
|
|
Specifies a Tcl script that may be evaluated to create the window
|
|
for the annotation.
|
|
If no \fB\-window\fR option has been specified for the annotation
|
|
this script will be evaluated when the annotation is about to
|
|
be displayed on the screen.
|
|
\fIScript\fR 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, \fIscript\fR
|
|
will be evaluated again the next time the annotation is displayed.
|
|
.TP
|
|
\fB\-padx \fIpixels\fR
|
|
\fIPixels\fR specifies the amount of extra space to leave on
|
|
each side of the embedded window.
|
|
It may have any of the usual forms defined for a screen distance.
|
|
.TP
|
|
\fB\-pady \fIpixels\fR
|
|
\fIPixels\fR specifies the amount of extra space to leave on
|
|
the top and on the bottom of the embedded window.
|
|
It may have any of the usual forms defined for a screen distance.
|
|
.TP
|
|
\fB\-stretch \fIboolean\fR
|
|
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 \fB\-pady\fR option has been specified as well, then the
|
|
requested padding will be retained even if the window is
|
|
stretched.
|
|
.TP
|
|
\fB\-window \fIpathName\fR
|
|
Specifies the name of a window to display in the annotation.
|
|
|
|
.SH THE SELECTION
|
|
.PP
|
|
Text widgets support the standard X selection.
|
|
Selection support is implemented via tags.
|
|
If the \fBexportSelection\fR option for the text widget is true
|
|
then the \fBsel\fR tag will be associated with the selection:
|
|
.IP [1]
|
|
Whenever characters are tagged with \fBsel\fR the text widget
|
|
will claim ownership of the selection.
|
|
.IP [2]
|
|
Attempts to retrieve the
|
|
selection will be serviced by the text widget, returning all the
|
|
characters with the \fBsel\fR tag.
|
|
.IP [3]
|
|
If the selection is claimed away by another application or by another
|
|
window within this application, then the \fBsel\fR tag will be removed
|
|
from all characters in the text.
|
|
.PP
|
|
The \fBsel\fR tag is automatically defined when a text widget is
|
|
created, and it may not be deleted with the ``\fIpathName \fBtag delete\fR''
|
|
widget command. Furthermore, the \fBselectBackground\fR,
|
|
\fBselectBorderWidth\fR, and \fBselectForeground\fR options for
|
|
the text widget are tied to the \fB\-background\fR,
|
|
\fB\-borderwidth\fR, and \fB\-foreground\fR options for the \fBsel\fR
|
|
tag: changes in either will automatically be reflected in the
|
|
other.
|
|
|
|
.SH THE INSERTION CURSOR
|
|
.PP
|
|
The mark named \fBinsert\fR has special significance in text widgets.
|
|
It is defined automatically when a text widget is created and it
|
|
may not be unset with the ``\fIpathName \fBmark unset\fR'' widget
|
|
command.
|
|
The \fBinsert\fR mark represents the position of the insertion
|
|
cursor, and the insertion cursor will automatically be drawn at
|
|
this point whenever the text widget has the input focus.
|
|
|
|
.SH "WIDGET COMMAND"
|
|
.PP
|
|
The \fBtext\fR command creates a new Tcl command whose
|
|
name is the same as the path name of the text's window. This
|
|
command may be used to invoke various
|
|
operations on the widget. It has the following general form:
|
|
.CS
|
|
\fIpathName option \fR?\fIarg arg ...\fR?
|
|
.CE
|
|
\fIPathName\fR is the name of the command, which is the same as
|
|
the text widget's path name. \fIOption\fR and the \fIarg\fRs
|
|
determine the exact behavior of the command. The following
|
|
commands are possible for text widgets:
|
|
.TP
|
|
\fIpathName \fBbbox \fIindex\fR
|
|
Returns a list of four elements describing the screen area
|
|
of the character given by \fIindex\fR.
|
|
The first two elements of the list give the x and y coordinates
|
|
of the upper-left corner of the area occupied by the
|
|
character, and the last two elements give the width and height
|
|
of the area.
|
|
If the character is only partially visible on the screen, then
|
|
the return value reflects just the visible part.
|
|
If the character is not visible on the screen then the return
|
|
value is an empty list.
|
|
.TP
|
|
\fIpathName \fBcget\fR \fIoption\fR
|
|
Returns the current value of the configuration option given
|
|
by \fIoption\fR.
|
|
\fIOption\fR may have any of the values accepted by the \fBtext\fR
|
|
command.
|
|
.TP
|
|
\fIpathName \fBcompare\fR \fIindex1 op index2\fR
|
|
Compares the indices given by \fIindex1\fR and \fIindex2\fR according
|
|
to the relational operator given by \fIop\fR, and returns 1 if
|
|
the relationship is satisfied and 0 if it isn't.
|
|
\fIOp\fR must be one of the operators <, <=, ==, >=, >, or !=.
|
|
If \fIop\fR is == then 1 is returned if the two indices refer to
|
|
the same character, if \fIop\fR is < then 1 is returned if \fIindex1\fR
|
|
refers to an earlier character in the text than \fIindex2\fR, and
|
|
so on.
|
|
.TP
|
|
\fIpathName \fBconfigure\fR ?\fIoption\fR? \fI?value option value ...\fR?
|
|
Query or modify the configuration options of the widget.
|
|
If no \fIoption\fR is specified, returns a list describing all of
|
|
the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
|
|
information on the format of this list). If \fIoption\fR is specified
|
|
with no \fIvalue\fR, 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 \fIoption\fR is specified). If
|
|
one or more \fIoption\-value\fR pairs are specified, then the command
|
|
modifies the given widget option(s) to have the given value(s); in
|
|
this case the command returns an empty string.
|
|
\fIOption\fR may have any of the values accepted by the \fBtext\fR
|
|
command.
|
|
.TP
|
|
\fIpathName \fBdebug \fR?\fIboolean\fR?
|
|
If \fIboolean\fR 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 \fIboolean\fR has a false value then the debugging checks will
|
|
be turned off.
|
|
In either case the command returns an empty string.
|
|
If \fIboolean\fR is not specified then the command returns \fBon\fR
|
|
or \fBoff\fR 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.
|
|
.TP
|
|
\fIpathName \fBdelete \fIindex1 \fR?\fIindex2\fR?
|
|
Delete a range of characters from the text.
|
|
If both \fIindex1\fR and \fIindex2\fR are specified, then delete
|
|
all the characters starting with the one given by \fIindex1\fR
|
|
and stopping just before \fIindex2\fR (i.e. the character at
|
|
\fIindex2\fR is not deleted).
|
|
If \fIindex2\fR doesn't specify a position later in the text
|
|
than \fIindex1\fR then no characters are deleted.
|
|
If \fIindex2\fR isn't specified then the single character at
|
|
\fIindex1\fR is deleted.
|
|
It is not allowable to delete characters in a way that would leave
|
|
the text without a newline as the last character.
|
|
The command returns an empty string.
|
|
.TP
|
|
\fIpathName \fBdlineinfo \fIindex\fR
|
|
Returns a list with five elements describing the area occupied
|
|
by the display line containing \fIindex\fR.
|
|
The first two elements of the list give the x and y coordinates
|
|
of the upper-left corner of the area occupied by the
|
|
line, the third and fourth elements give the width and height
|
|
of the area, and the fifth element gives the position of the baseline
|
|
for the line, measured down from the top of the area.
|
|
All of this information is measured in pixels.
|
|
If the current wrap mode is \fBnone\fR and the line extends beyond
|
|
the boundaries of the window,
|
|
the area returned reflects the entire area of the line, including the
|
|
portions that are out of the window.
|
|
If the line is shorter than the full width of the window then the
|
|
area returned reflects just the portion of the line that is occupied
|
|
by characters and embedded windows.
|
|
If the display line containing \fIindex\fR is not visible on
|
|
the screen then the return value is an empty list.
|
|
.TP
|
|
\fIpathName \fBdump \fR?\fIswitches\fR? \fIindex1 \fR?\fIindex2\fR?
|
|
Return the contents of the text widget from \fIindex1\fR up to,
|
|
but not including \fIindex2\fR,
|
|
including the text and
|
|
information about marks, tags, and embedded windows.
|
|
If \fIindex2\fR is not specified, then it defaults to
|
|
one character past \fIindex1\fR. The information is returned
|
|
in the following format:
|
|
.LP
|
|
.RS
|
|
\fIkey1 value1 index1 key2 value2 index2\fR ...
|
|
.LP
|
|
The possible \fIkey\fP values are \fBtext\fP, \fBmark\fP,
|
|
\fBtagon\fP, \fBtagoff\fP, and \fBwindow\fP. The corresponding
|
|
\fIvalue\fP is the text, mark name, tag name, or window name.
|
|
The \fIindex\fP information is the index of the
|
|
start of the text, the mark, the tag transition, or the window.
|
|
One or more of the following switches (or abbreviations thereof)
|
|
may be specified to control the dump:
|
|
.TP
|
|
\fB\-all\fR
|
|
Return information about all elements: text, marks, tags, and windows.
|
|
This is the default.
|
|
.TP
|
|
\fB\-command \fIcommand\fR
|
|
Instead of returning the information as the result of the dump operation,
|
|
invoke the \fIcommand\fR on each element of the text widget within the range.
|
|
The command has three arguments appended to it before it is evaluated:
|
|
the \fIkey\fP, \fIvalue\fP, and \fIindex\fP.
|
|
.TP
|
|
\fB\-mark\fR
|
|
Include information about marks in the dump results.
|
|
.TP
|
|
\fB\-tag\fR
|
|
Include information about tag transitions in the dump results. Tag information is
|
|
returned as \fBtagon\fP and \fBtagoff\fP elements that indicate the
|
|
begin and end of each range of each tag, respectively.
|
|
.TP
|
|
\fB\-text\fR
|
|
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 \fIindex2\fR.
|
|
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.
|
|
.TP
|
|
\fB\-window\fR
|
|
Include information about embedded windows in the dump results.
|
|
The value of a window is its Tk pathname, unless the window
|
|
has not been created yet. (It must have a create script.)
|
|
In this case an empty string is returned, and you must query the
|
|
window by its index position to get more information.
|
|
.RE
|
|
.TP
|
|
\fIpathName \fBget \fIindex1 \fR?\fIindex2\fR?
|
|
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 \fIindex1\fR and ending just before
|
|
the one whose index is \fIindex2\fR (the character at \fIindex2\fR
|
|
will not be returned).
|
|
If \fIindex2\fR is omitted then the single character at \fIindex1\fR
|
|
is returned.
|
|
If there are no characters in the specified range (e.g. \fIindex1\fR
|
|
is past the end of the file or \fIindex2\fR is less than or equal
|
|
to \fIindex1\fR) then an empty string is returned.
|
|
If the specified range contains embedded windows, no information
|
|
about them is included in the returned string.
|
|
.TP
|
|
\fIpathName \fBindex \fIindex\fR
|
|
Returns the position corresponding to \fIindex\fR in the form
|
|
\fIline.char\fR where \fIline\fR is the line number and \fIchar\fR
|
|
is the character number.
|
|
\fIIndex\fR may have any of the forms described under INDICES above.
|
|
.TP
|
|
\fIpathName \fBinsert \fIindex chars \fR?\fItagList chars tagList ...\fR?
|
|
Inserts all of the \fIchars\fR arguments just before the character at
|
|
\fIindex\fR.
|
|
If \fIindex\fR 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 \fIchars\fR argument and no \fItagList\fR, 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 \fItagList\fR 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 \fIchars\fR\-\fItagList\fR argument pairs are present,
|
|
they produce the same effect as if a separate \fBinsert\fR widget
|
|
command had been issued for each pair, in order.
|
|
The last \fItagList\fR argument may be omitted.
|
|
.TP
|
|
\fIpathName \fBmark \fIoption \fR?\fIarg arg ...\fR?
|
|
This command is used to manipulate marks. The exact behavior of
|
|
the command depends on the \fIoption\fR argument that follows
|
|
the \fBmark\fR argument. The following forms of the command
|
|
are currently supported:
|
|
.RS
|
|
.TP
|
|
\fIpathName \fBmark gravity \fImarkName\fR ?\fIdirection\fR?
|
|
If \fIdirection\fR is not specified, returns \fBleft\fR or \fBright\fR
|
|
to indicate which of its adjacent characters \fImarkName\fR is attached
|
|
to.
|
|
If \fIdirection\fR is specified, it must be \fBleft\fR or \fBright\fR;
|
|
the gravity of \fImarkName\fR is set to the given value.
|
|
.TP
|
|
\fIpathName \fBmark names\fR
|
|
Returns a list whose elements are the names of all the marks that
|
|
are currently set.
|
|
.TP
|
|
\fIpathName \fBmark next \fIindex\fR
|
|
Returns the name of the next mark at or after \fIindex\fR.
|
|
If \fIindex\fR is specified in numerical form, then the search for
|
|
the next mark begins at that index.
|
|
If \fIindex\fR 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 \fBmark next\fP 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 \fBdump\fP operation.
|
|
If a mark has been set to the special \fBend\fB index,
|
|
then it appears to be \fIafter\fP \fBend\fP with respect to the \fBmark next\fP operation.
|
|
An empty string is returned if there are no marks after \fIindex\fR.
|
|
.TP
|
|
\fIpathName \fBmark previous \fIindex\fR
|
|
Returns the name of the mark at or before \fIindex\fR.
|
|
If \fIindex\fR is specified in numerical form, then the search for
|
|
the previous mark begins with the character just before that index.
|
|
If \fIindex\fR is the name of a mark, then the search for
|
|
the next mark begins immediately before that mark.
|
|
This can still return a mark at the same position if
|
|
there are multiple marks at the same index.
|
|
These semantics mean that the \fBmark previous\fP operation can be used to
|
|
step through all the marks in a text widget in the reverse order
|
|
as the mark information returned by the \fBdump\fP operation.
|
|
An empty string is returned if there are no marks before \fIindex\fR.
|
|
.TP
|
|
\fIpathName \fBmark set \fImarkName index\fR
|
|
Sets the mark named \fImarkName\fR to a position just before the
|
|
character at \fIindex\fR.
|
|
If \fImarkName\fR already exists, it is moved from its old position;
|
|
if it doesn't exist, a new mark is created.
|
|
This command returns an empty string.
|
|
.TP
|
|
\fIpathName \fBmark unset \fImarkName \fR?\fImarkName markName ...\fR?
|
|
Remove the mark corresponding to each of the \fImarkName\fR arguments.
|
|
The removed marks will not be usable in indices and will not be
|
|
returned by future calls to ``\fIpathName \fBmark names\fR''.
|
|
This command returns an empty string.
|
|
.RE
|
|
.TP
|
|
\fIpathName \fBscan\fR \fIoption args\fR
|
|
This command is used to implement scanning on texts. It has
|
|
two forms, depending on \fIoption\fR:
|
|
.RS
|
|
.TP
|
|
\fIpathName \fBscan mark \fIx y\fR
|
|
Records \fIx\fR and \fIy\fR and the current view in the text window,
|
|
for use in conjunction with later \fBscan dragto\fR commands.
|
|
Typically this command is associated with a mouse button press in
|
|
the widget. It returns an empty string.
|
|
.TP
|
|
\fIpathName \fBscan dragto \fIx y\fR
|
|
This command computes the difference between its \fIx\fR and \fIy\fR
|
|
arguments and the \fIx\fR and \fIy\fR arguments to the last
|
|
\fBscan mark\fR 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.
|
|
.RE
|
|
.TP
|
|
\fIpathName \fBsearch \fR?\fIswitches\fR? \fIpattern index \fR?\fIstopIndex\fR?
|
|
Searches the text in \fIpathName\fR starting at \fIindex\fR for a range
|
|
of characters that matches \fIpattern\fR.
|
|
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 following switches (or abbreviations thereof)
|
|
may be specified to control the search:
|
|
.RS
|
|
.TP
|
|
\fB\-forwards\fR
|
|
The search will proceed forward through the text, finding the first
|
|
matching range starting at or after the position given by \fIindex\fR.
|
|
This is the default.
|
|
.TP
|
|
\fB\-backwards\fR
|
|
The search will proceed backward through the text, finding the
|
|
matching range closest to \fIindex\fR whose first character
|
|
is before \fIindex\fR.
|
|
.TP
|
|
\fB\-exact\fR
|
|
Use exact matching: the characters in the matching range must be
|
|
identical to those in \fIpattern\fR.
|
|
This is the default.
|
|
.TP
|
|
\fB\-regexp\fR
|
|
Treat \fIpattern\fR as a regular expression and match it against
|
|
the text using the rules for regular expressions (see the \fBregexp\fR
|
|
command for details).
|
|
.TP
|
|
\fB\-nocase\fR
|
|
Ignore case differences between the pattern and the text.
|
|
.TP
|
|
\fB\-count\fI varName\fR
|
|
The argument following \fB\-count\fR gives the name of a variable;
|
|
if a match is found, the number of characters in the matching
|
|
range will be stored in the variable.
|
|
.TP
|
|
\fB\-\|\-\fR
|
|
This switch has no effect except to terminate the list of switches:
|
|
the next argument will be treated as \fIpattern\fR even if it starts
|
|
with \fB\-\fR.
|
|
.LP
|
|
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 \fB$\fR feature in regular
|
|
expressions to match the end of a line.
|
|
For exact matching the newlines are retained.
|
|
If \fIstopIndex\fR is specified, the search stops at that index:
|
|
for forward searches, no match at or after \fIstopIndex\fR will
|
|
be considered; for backward searches, no match earlier in the
|
|
text than \fIstopIndex\fR will be considered.
|
|
If \fIstopIndex\fR 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 \fIstopIndex\fR is specified, no wrap-around will occur.
|
|
.RE
|
|
.TP
|
|
\fIpathName \fBsee \fIindex\fR
|
|
Adjusts the view in the window so that the character given by \fIindex\fR
|
|
is completely visible.
|
|
If \fIindex\fR is already visible then the command does nothing.
|
|
If \fIindex\fR is a short distance out of view, the command
|
|
adjusts the view just enough to make \fIindex\fR visible at the
|
|
edge of the window.
|
|
If \fIindex\fR is far out of view, then the command centers
|
|
\fIindex\fR in the window.
|
|
.TP
|
|
\fIpathName \fBtag \fIoption \fR?\fIarg arg ...\fR?
|
|
This command is used to manipulate tags. The exact behavior of the
|
|
command depends on the \fIoption\fR argument that follows the
|
|
\fBtag\fR argument. The following forms of the command are currently
|
|
supported:
|
|
.RS
|
|
.TP
|
|
\fIpathName \fBtag add \fItagName index1 \fR?\fIindex2 index1 index2 ...\fR?
|
|
Associate the tag \fItagName\fR with all of the characters starting
|
|
with \fIindex1\fR and ending just before
|
|
\fIindex2\fR (the character at \fIindex2\fR isn't tagged).
|
|
A single command may contain any number of \fIindex1\fR\-\fIindex2\fR
|
|
pairs.
|
|
If the last \fIindex2\fR is omitted then the single character at
|
|
\fIindex1\fR is tagged.
|
|
If there are no characters in the specified range (e.g. \fIindex1\fR
|
|
is past the end of the file or \fIindex2\fR is less than or equal
|
|
to \fIindex1\fR) then the command has no effect.
|
|
.TP
|
|
\fIpathName \fBtag bind \fItagName\fR ?\fIsequence\fR? ?\fIscript\fR?
|
|
This command associates \fIscript\fR with the tag given by
|
|
\fItagName\fR.
|
|
Whenever the event sequence given by \fIsequence\fR occurs for a
|
|
character that has been tagged with \fItagName\fR,
|
|
the script will be invoked.
|
|
This widget command is similar to the \fBbind\fR command except that
|
|
it operates on characters in a text rather than entire widgets.
|
|
See the \fBbind\fR manual entry for complete details
|
|
on the syntax of \fIsequence\fR and the substitutions performed
|
|
on \fIscript\fR before invoking it.
|
|
If all arguments are specified then a new binding is created, replacing
|
|
any existing binding for the same \fIsequence\fR and \fItagName\fR
|
|
(if the first character of \fIscript\fR is ``+'' then \fIscript\fR
|
|
augments an existing binding rather than replacing it).
|
|
In this case the return value is an empty string.
|
|
If \fIscript\fR is omitted then the command returns the \fIscript\fR
|
|
associated with \fItagName\fR and \fIsequence\fR (an error occurs
|
|
if there is no such binding).
|
|
If both \fIscript\fR and \fIsequence\fR are omitted then the command
|
|
returns a list of all the sequences for which bindings have been
|
|
defined for \fItagName\fR.
|
|
.RS
|
|
.PP
|
|
The only events for which bindings may be specified are those related
|
|
to the mouse and keyboard, such as \fBEnter\fR, \fBLeave\fR,
|
|
\fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR.
|
|
Event bindings for a text widget use the \fBcurrent\fR mark
|
|
described under MARKS above.
|
|
An \fBEnter\fR event triggers for a tag when the tag first
|
|
becomes present on the current character, and a \fBLeave\fR
|
|
event triggers for a tag when it ceases to be present on
|
|
the current character.
|
|
\fBEnter\fR and \fBLeave\fR events can happen either because the
|
|
\fBcurrent\fR mark moved or because the character at that
|
|
position changed.
|
|
Note that these events are different than \fBEnter\fR and \fBLeave\fR
|
|
events for windows.
|
|
Mouse and keyboard events are directed to the current character.
|
|
.PP
|
|
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 \fBbind\fR command for details).
|
|
\fBcontinue\fR and \fBbreak\fR commands within binding scripts
|
|
are processed in the same way as for bindings created with
|
|
the \fBbind\fR command.
|
|
.PP
|
|
If bindings are created for the widget as a whole using the
|
|
\fBbind\fR command, then those bindings will supplement the
|
|
tag bindings.
|
|
The tag bindings will be invoked first, followed by bindings
|
|
for the window as a whole.
|
|
.RE
|
|
.TP
|
|
\fIpathName \fBtag cget\fR \fItagName option\fR
|
|
This command returns the current value of the option named \fIoption\fR
|
|
associated with the tag given by \fItagName\fR.
|
|
\fIOption\fR may have any of the values accepted by the \fBtag configure\fR
|
|
widget command.
|
|
.TP
|
|
\fIpathName \fBtag configure \fItagName\fR ?\fIoption\fR? ?\fIvalue\fR? ?\fIoption value ...\fR?
|
|
This command is similar to the \fBconfigure\fR widget command except
|
|
that it modifies options associated with the tag given by \fItagName\fR
|
|
instead of modifying options for the overall text widget.
|
|
If no \fIoption\fR is specified, the command returns a list describing
|
|
all of the available options for \fItagName\fR (see \fBTk_ConfigureInfo\fR
|
|
for information on the format of this list).
|
|
If \fIoption\fR is specified with no \fIvalue\fR, 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 \fIoption\fR
|
|
is specified).
|
|
If one or more \fIoption\-value\fR pairs are specified, then the command
|
|
modifies the given option(s) to have the given value(s) in \fItagName\fR;
|
|
in this case the command returns an empty string.
|
|
See TAGS above for details on the options available for tags.
|
|
.TP
|
|
\fIpathName \fBtag delete \fItagName \fR?\fItagName ...\fR?
|
|
Deletes all tag information for each of the \fItagName\fR
|
|
arguments.
|
|
The command removes the tags from all characters in the file
|
|
and also deletes any other information associated with the tags,
|
|
such as bindings and display information.
|
|
The command returns an empty string.
|
|
.TP
|
|
\fIpathName\fB tag lower \fItagName \fR?\fIbelowThis\fR?
|
|
Changes the priority of tag \fItagName\fR so that it is just lower
|
|
in priority than the tag whose name is \fIbelowThis\fR.
|
|
If \fIbelowThis\fR is omitted, then \fItagName\fR's priority
|
|
is changed to make it lowest priority of all tags.
|
|
.TP
|
|
\fIpathName \fBtag names \fR?\fIindex\fR?
|
|
Returns a list whose elements are the names of all the tags that
|
|
are active at the character position given by \fIindex\fR.
|
|
If \fIindex\fR 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 ``\fIpathName \fBtag\fR'' widget
|
|
command but haven't been deleted by a ``\fIpathName \fBtag delete\fR''
|
|
widget command, even if no characters are currently marked with
|
|
the tag).
|
|
The list will be sorted in order from lowest priority to highest
|
|
priority.
|
|
.TP
|
|
\fIpathName \fBtag nextrange \fItagName index1 \fR?\fIindex2\fR?
|
|
This command searches the text for a range of characters tagged
|
|
with \fItagName\fR where the first character of the range is
|
|
no earlier than the character at \fIindex1\fR and no later than
|
|
the character just before \fIindex2\fR (a range starting at
|
|
\fIindex2\fR will not be considered).
|
|
If several matching ranges exist, the first one 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 \fIindex2\fR is not given then it defaults to the end of the text.
|
|
.TP
|
|
\fIpathName \fBtag prevrange \fItagName index1 \fR?\fIindex2\fR?
|
|
This command searches the text for a range of characters tagged
|
|
with \fItagName\fR where the first character of the range is
|
|
before the character at \fIindex1\fR and no earlier than
|
|
the character at \fIindex2\fR (a range starting at
|
|
\fIindex2\fR will be considered).
|
|
If several matching ranges exist, the one closest to \fIindex1\fR 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 \fIindex2\fR is not given then it defaults to the beginning of the text.
|
|
.TP
|
|
\fIpathName\fB tag raise \fItagName \fR?\fIaboveThis\fR?
|
|
Changes the priority of tag \fItagName\fR so that it is just higher
|
|
in priority than the tag whose name is \fIaboveThis\fR.
|
|
If \fIaboveThis\fR is omitted, then \fItagName\fR's priority
|
|
is changed to make it highest priority of all tags.
|
|
.TP
|
|
\fIpathName \fBtag ranges \fItagName\fR
|
|
Returns a list describing all of the ranges of text that have been
|
|
tagged with \fItagName\fR.
|
|
The first two elements of the list describe the first tagged range
|
|
in the text, the next two elements describe the second range, and
|
|
so on.
|
|
The first element of each pair contains the index of the first
|
|
character of the range, and the second element of the pair contains
|
|
the index of the character just after the last one in the
|
|
range.
|
|
If there are no characters tagged with \fItag\fR then an
|
|
empty string is returned.
|
|
.TP
|
|
\fIpathName \fBtag remove \fItagName index1 \fR?\fIindex2 index1 index2 ...\fR?
|
|
Remove the tag \fItagName\fR from all of the characters starting
|
|
at \fIindex1\fR and ending just before
|
|
\fIindex2\fR (the character at \fIindex2\fR isn't affected).
|
|
A single command may contain any number of \fIindex1\fR\-\fIindex2\fR
|
|
pairs.
|
|
If the last \fIindex2\fR is omitted then the single character at
|
|
\fIindex1\fR is tagged.
|
|
If there are no characters in the specified range (e.g. \fIindex1\fR
|
|
is past the end of the file or \fIindex2\fR is less than or equal
|
|
to \fIindex1\fR) then the command has no effect.
|
|
This command returns an empty string.
|
|
.RE
|
|
.TP
|
|
\fIpathName \fBwindow \fIoption \fR?\fIarg arg ...\fR?
|
|
This command is used to manipulate embedded windows.
|
|
The behavior of the command depends on the \fIoption\fR argument
|
|
that follows the \fBtag\fR argument.
|
|
The following forms of the command are currently supported:
|
|
.RS
|
|
.TP
|
|
\fIpathName \fBwindow cget\fR \fIindex option\fR
|
|
Returns the value of a configuration option for an embedded window.
|
|
\fIIndex\fR identifies the embedded window, and \fIoption\fR
|
|
specifies a particular configuration option, which must be one of
|
|
the ones listed in the section EMBEDDED WINDOWS.
|
|
.TP
|
|
\fIpathName \fBwindow configure \fIindex\fR ?\fIoption value ...\fR?
|
|
Query or modify the configuration options for an embedded window.
|
|
If no \fIoption\fR is specified, returns a list describing all of
|
|
the available options for the embedded window at \fIindex\fR
|
|
(see \fBTk_ConfigureInfo\fR for information on the format of this list).
|
|
If \fIoption\fR is specified with no \fIvalue\fR, 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
|
|
\fIoption\fR is specified).
|
|
If one or more \fIoption\-value\fR 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 information on the options that
|
|
are supported.
|
|
.TP
|
|
\fIpathName \fBwindow create \fIindex\fR ?\fIoption value ...\fR?
|
|
This command creates a new window annotation, which will appear
|
|
in the text at the position given by \fIindex\fR.
|
|
Any number of \fIoption\-value\fR pairs may be specified to
|
|
configure the annotation.
|
|
See EMBEDDED WINDOWS for information on the options that
|
|
are supported.
|
|
Returns an empty string.
|
|
.TP
|
|
\fIpathName \fBwindow names\fR
|
|
Returns a list whose elements are the names of all windows currently
|
|
embedded in \fIwindow\fR.
|
|
.RE
|
|
.TP
|
|
\fIpathName \fBxview \fIoption args\fR
|
|
This command is used to query and change the horizontal position of the
|
|
text in the widget's window. It can take any of the following
|
|
forms:
|
|
.RS
|
|
.TP
|
|
\fIpathName \fBxview\fR
|
|
Returns a list containing two elements.
|
|
Each element is a real fraction between 0 and 1; together they describe
|
|
the portion of the document's horizontal span that is visible in
|
|
the window.
|
|
For example, if the first element is .2 and the second element is .6,
|
|
20% of the text is off-screen to the left, the middle 40% is visible
|
|
in the window, and 40% of the text is off-screen to the right.
|
|
The fractions refer only to the lines that are actually visible in the
|
|
window: if the lines in the window are all very short, so that they
|
|
are entirely visible, the returned fractions will be 0 and 1,
|
|
even if there are other lines in the text that are
|
|
much wider than the window.
|
|
These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR
|
|
option.
|
|
.TP
|
|
\fIpathName \fBxview moveto\fI fraction\fR
|
|
Adjusts the view in the window so that \fIfraction\fR of the horizontal
|
|
span of the text is off-screen to the left.
|
|
\fIFraction\fR is a fraction between 0 and 1.
|
|
.TP
|
|
\fIpathName \fBxview scroll \fInumber what\fR
|
|
This command shifts the view in the window left or right according to
|
|
\fInumber\fR and \fIwhat\fR.
|
|
\fINumber\fR must be an integer.
|
|
\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation
|
|
of one of these.
|
|
If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by
|
|
\fInumber\fR average-width characters on the display; if it is
|
|
\fBpages\fR then the view adjusts by \fInumber\fR screenfuls.
|
|
If \fInumber\fR is negative then characters farther to the left
|
|
become visible; if it is positive then characters farther to the right
|
|
become visible.
|
|
.RE
|
|
.TP
|
|
\fIpathName \fByview \fI?args\fR?
|
|
This command is used to query and change the vertical position of the
|
|
text in the widget's window.
|
|
It can take any of the following forms:
|
|
.RS
|
|
.TP
|
|
\fIpathName \fByview\fR
|
|
Returns a list containing two elements, both of which are real fractions
|
|
between 0 and 1.
|
|
The first element gives the position of the first character in the
|
|
top line in the window, relative to the text as a whole (0.5 means
|
|
it is halfway through the text, for example).
|
|
The second element gives the position of the character just after
|
|
the last one in the bottom line of the window,
|
|
relative to the text as a whole.
|
|
These are the same values passed to scrollbars via the \fB\-yscrollcommand\fR
|
|
option.
|
|
.TP
|
|
\fIpathName \fByview moveto\fI fraction\fR
|
|
Adjusts the view in the window so that the character given by \fIfraction\fR
|
|
appears on the top line of the window.
|
|
\fIFraction\fR is a fraction between 0 and 1; 0 indicates the first
|
|
character in the text, 0.33 indicates the character one-third the
|
|
way through the text, and so on.
|
|
.TP
|
|
\fIpathName \fByview scroll \fInumber what\fR
|
|
This command adjust the view in the window up or down according to
|
|
\fInumber\fR and \fIwhat\fR.
|
|
\fINumber\fR must be an integer.
|
|
\fIWhat\fR must be either \fBunits\fR or \fBpages\fR.
|
|
If \fIwhat\fR is \fBunits\fR, the view adjusts up or down by
|
|
\fInumber\fR lines on the display; if it is \fBpages\fR then
|
|
the view adjusts by \fInumber\fR screenfuls.
|
|
If \fInumber\fR is negative then earlier positions in the text
|
|
become visible; if it is positive then later positions in the text
|
|
become visible.
|
|
.TP
|
|
\fIpathName \fByview \fR?\fB\-pickplace\fR? \fIindex\fR
|
|
Changes the view in the widget's window to make \fIindex\fR visible.
|
|
If the \fB\-pickplace\fR option isn't specified then \fIindex\fR will
|
|
appear at the top of the window.
|
|
If \fB\-pickplace\fR is specified then the widget chooses where
|
|
\fIindex\fR appears in the window:
|
|
.RS
|
|
.IP [1]
|
|
If \fIindex\fR is already visible somewhere in the window then the
|
|
command does nothing.
|
|
.IP [2]
|
|
If \fIindex\fR is only a few lines off-screen above the window then
|
|
it will be positioned at the top of the window.
|
|
.IP [3]
|
|
If \fIindex\fR is only a few lines off-screen below the window then
|
|
it will be positioned at the bottom of the window.
|
|
.IP [4]
|
|
Otherwise, \fIindex\fR will be centered in the window.
|
|
.LP
|
|
The \fB\-pickplace\fR option has been obsoleted by the \fBsee\fR widget
|
|
command (\fBsee\fR handles both x- and y-motion to make a location
|
|
visible, whereas \fB\-pickplace\fR only handles motion in y).
|
|
.RE
|
|
.TP
|
|
\fIpathName \fByview \fInumber\fR
|
|
This command makes the first character on the line after
|
|
the one given by \fInumber\fR visible at the top of the window.
|
|
\fINumber\fR must be an integer.
|
|
This command used to be used for scrolling, but now it is obsolete.
|
|
.RE
|
|
|
|
.SH BINDINGS
|
|
.PP
|
|
Tk automatically creates class bindings for texts that give them
|
|
the following default behavior.
|
|
In the descriptions below, ``word'' refers to a contiguous group
|
|
of letters, digits, or ``_'' characters, or any single character
|
|
other than these.
|
|
.IP [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.
|
|
.IP [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.
|
|
.IP [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.
|
|
.IP [4]
|
|
The ends of the selection can be adjusted by dragging with mouse
|
|
button 1 while the Shift key is down; this will adjust the end
|
|
of the selection that was nearest to the mouse cursor when 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.
|
|
.IP [5]
|
|
Clicking mouse button 1 with the Control key down will reposition the
|
|
insertion cursor without affecting the selection.
|
|
.IP [6]
|
|
If any normal printing characters are typed, they are
|
|
inserted at the point of the insertion cursor.
|
|
.IP [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.
|
|
.IP [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).
|
|
.IP [9]
|
|
The Left and Right keys move the insertion cursor one character to the
|
|
left or right; they also clear any selection in the text.
|
|
If Left or Right is typed with the Shift key down, then the insertion
|
|
cursor moves and the selection is extended to include the new character.
|
|
Control-Left and Control-Right move the insertion cursor by words, and
|
|
Control-Shift-Left and Control-Shift-Right move the insertion cursor
|
|
by words and also extend the selection.
|
|
Control-b and Control-f behave the same as Left and Right, respectively.
|
|
Meta-b and Meta-f behave the same as Control-Left and Control-Right,
|
|
respectively.
|
|
.IP [10]
|
|
The Up and Down keys move the insertion cursor one line up or
|
|
down and clear any selection in the text.
|
|
If Up or Right is typed with the Shift key down, then the insertion
|
|
cursor moves and the selection is extended to include the new character.
|
|
Control-Up and Control-Down move the insertion cursor by paragraphs (groups
|
|
of lines separated by blank lines), and
|
|
Control-Shift-Up and Control-Shift-Down move the insertion cursor
|
|
by paragraphs and also extend the selection.
|
|
Control-p and Control-n behave the same as Up and Down, respectively.
|
|
.IP [11]
|
|
The Next and Prior keys move the insertion cursor forward or backwards
|
|
by one screenful and clear any selection in the text.
|
|
If the Shift key is held down while Next or Prior is typed, then
|
|
the selection is extended to include the new character.
|
|
Control-v moves the view down one screenful without moving the
|
|
insertion cursor or adjusting the selection.
|
|
.IP [12]
|
|
Control-Next and Control-Prior scroll the view right or left by one page
|
|
without moving the insertion cursor or affecting the selection.
|
|
.IP [13]
|
|
Home and Control-a move the insertion cursor to the
|
|
beginning of its line and clear any selection in the widget.
|
|
Shift-Home moves the insertion cursor to the beginning of the line
|
|
and also extends the selection to that point.
|
|
.IP [14]
|
|
End and Control-e move the insertion cursor to the
|
|
end of the line and clear any selection in the widget.
|
|
Shift-End moves the cursor to the end of the line and extends the selection
|
|
to that point.
|
|
.IP [15]
|
|
Control-Home and Meta-< move the insertion cursor to the beginning of
|
|
the text and clear any selection in the widget.
|
|
Control-Shift-Home moves the insertion cursor to the beginning of the text
|
|
and also extends the selection to that point.
|
|
.IP [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.
|
|
.IP [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.
|
|
.IP [18]
|
|
Control-/ selects the entire contents of the widget.
|
|
.IP [19]
|
|
Control-\e clears any selection in the widget.
|
|
.IP [20]
|
|
The F16 key (labelled Copy on many Sun workstations) or Meta-w
|
|
copies the selection in the widget to the clipboard, if there is a selection.
|
|
.IP [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.
|
|
.IP [22]
|
|
The F18 key (labelled Paste on many Sun workstations) or Control-y
|
|
inserts the contents of the clipboard at the position of the
|
|
insertion cursor.
|
|
.IP [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.
|
|
.IP [24]
|
|
Backspace and Control-h delete the selection, if there is one
|
|
in the widget.
|
|
If there is no selection, they delete the character to the left of
|
|
the insertion cursor.
|
|
.IP [25]
|
|
Control-d deletes the character to the right of the insertion cursor.
|
|
.IP [26]
|
|
Meta-d deletes the word to the right of the insertion cursor.
|
|
.IP [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.
|
|
.IP [28]
|
|
Control-o opens a new line by inserting a newline character in
|
|
front of the insertion cursor without moving the insertion cursor.
|
|
.IP [29]
|
|
Meta-backspace and Meta-Delete delete the word to the left of the
|
|
insertion cursor.
|
|
.IP [30]
|
|
Control-x deletes whatever is selected in the text widget.
|
|
.IP [31]
|
|
Control-t reverses the order of the two characters to the right of
|
|
the insertion cursor.
|
|
.PP
|
|
If the widget is disabled using the \fB\-state\fR 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.
|
|
.PP
|
|
The behavior of texts can be changed by defining new bindings for
|
|
individual widgets or by redefining the class bindings.
|
|
|
|
.SH "PERFORMANCE ISSUES"
|
|
.PP
|
|
Text widgets should run efficiently under a variety
|
|
of conditions. The text widget uses about 2-3 bytes of
|
|
main memory for each byte of text, so texts containing a megabyte
|
|
or more should be practical on most workstations.
|
|
Text is represented internally with a modified B-tree structure
|
|
that makes operations relatively efficient even with large texts.
|
|
Tags are included in the B-tree structure in a way that allows
|
|
tags to span large ranges or have many disjoint smaller ranges
|
|
without loss of efficiency.
|
|
Marks are also implemented in a way that allows large numbers of
|
|
marks.
|
|
In most cases it is fine to have large numbers of unique tags,
|
|
or a tag that has many distinct ranges.
|
|
.PP
|
|
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.
|
|
.PP
|
|
Very long text lines can be expensive,
|
|
especially if they have many marks and tags within them.
|
|
.PP
|
|
The display line with the insert cursor is redrawn each time the
|
|
cursor blinks, which causes a steady stream of graphics traffic.
|
|
Set the \fBinsertOffTime\fP attribute to 0 avoid this.
|
|
.SH KEYWORDS
|
|
text, widget
|