1996-09-27 06:29:02 -04:00
|
|
|
<HTML><HEAD><TITLE>Tk Built-In Commands - text manual page</TITLE></HEAD>
|
1998-04-10 06:59:06 -04:00
|
|
|
<BR>
|
1996-09-27 06:29:02 -04:00
|
|
|
<BODY bgcolor = #c3c3ff>
|
|
|
|
|
<H2><IMG ALIGN=BOTTOM SRC="./Img/ManPageBlue.gif"> text</H2>
|
|
|
|
|
<I>Create and manipulate text widgets</I><P><IMG ALIGN=TOP SRC="./Img/line-red.gif">
|
|
|
|
|
<H3><A NAME="M2">SYNOPSIS</A></H3>
|
|
|
|
|
(<B>text</B><I> widget-name </I>?<I>options</I>?)<BR>
|
|
|
|
|
<H3><A NAME="M3">STANDARD OPTIONS</A></H3>
|
|
|
|
|
<PRE>
|
|
|
|
|
<B><A HREF="options.n.html#M:background">:background</A></B> <B><A HREF="options.n.html#M:borderwidth">:borderwidth</A></B>
|
|
|
|
|
<B><A HREF="options.n.html#M:cursor">:cursor</A></B> <B><A HREF="options.n.html#M:exportselection">:exportselection</A></B>
|
|
|
|
|
<B><A HREF="options.n.html#M:font">:font</A></B> <B><A HREF="options.n.html#M:foreground">:foreground</A></B>
|
|
|
|
|
<B><A HREF="options.n.html#M:highlightbackground">:highlightbackground</A></B> <B><A HREF="options.n.html#M:highlightcolor">:highlightcolor</A></B>
|
|
|
|
|
<B><A HREF="options.n.html#M:highlightthickness">:highlightthickness</A></B> <B><A HREF="options.n.html#M:insertbackground">:insertbackground</A></B>
|
|
|
|
|
<B><A HREF="options.n.html#M:insertborderwidth">:insertborderwidth</A></B> <B><A HREF="options.n.html#M:insertofftime">:insertofftime</A></B>
|
|
|
|
|
<B><A HREF="options.n.html#M:insertontime">:insertontime</A></B> <B><A HREF="options.n.html#M:insertwidth">:insertwidth</A></B>
|
|
|
|
|
<B><A HREF="options.n.html#M:padx">:padx</A></B> <B><A HREF="options.n.html#M:pady">:pady</A></B>
|
|
|
|
|
<B><A HREF="options.n.html#M:relief">:relief</A></B> <B><A HREF="options.n.html#M:selectbackground">:selectbackground</A></B>
|
|
|
|
|
<B><A HREF="options.n.html#M:selectborderwidth">:selectborderwidth</A></B> <B><A HREF="options.n.html#M:selectforeground">:selectforeground</A></B>
|
|
|
|
|
<B><A HREF="options.n.html#M:setgrid">:setgrid</A></B> <B><A HREF="options.n.html#M:takefocus">:takefocus</A></B>
|
|
|
|
|
<B><A HREF="options.n.html#M:xscrollcommand">:xscrollcommand</A></B> <B><A HREF="options.n.html#M:yscrollcommand">:yscrollcommand</A></B>
|
|
|
|
|
</PRE>
|
|
|
|
|
<H3><A NAME="M28">WIDGET-SPECIFIC OPTIONS</A></H3>
|
|
|
|
|
<DL>
|
|
|
|
|
<P>
|
|
|
|
|
<DT><I>Name</I>: <B>height</B>
|
|
|
|
|
<DT><I>Class</I>: <B>Height</B>
|
|
|
|
|
<DT><I>Option keyword</I>: <B><A NAME="M29">:height</A></B>
|
|
|
|
|
<DT><I>STklos slot name</I>: <B>height</B>
|
|
|
|
|
<DD>Specifies the desired height for the window, in units of characters
|
|
|
|
|
in the font given by the <B>:font</B> option.
|
|
|
|
|
Must be at least one.
|
|
|
|
|
<P>
|
|
|
|
|
<P>
|
|
|
|
|
<DT><I>Name</I>: <B>spacing1</B>
|
|
|
|
|
<DT><I>Class</I>: <B>Spacing1</B>
|
|
|
|
|
<DT><I>Option keyword</I>: <B><A NAME="M30">:spacing1</A></B>
|
|
|
|
|
<DT><I>STklos slot name</I>: <B>spacing1</B>
|
|
|
|
|
<DD>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 <B>:spacing1</B> options in
|
|
|
|
|
tags.
|
|
|
|
|
<P>
|
|
|
|
|
<P>
|
|
|
|
|
<DT><I>Name</I>: <B>spacing2</B>
|
|
|
|
|
<DT><I>Class</I>: <B>Spacing2</B>
|
|
|
|
|
<DT><I>Option keyword</I>: <B><A NAME="M31">:spacing2</A></B>
|
|
|
|
|
<DT><I>STklos slot name</I>: <B>spacing2</B>
|
|
|
|
|
<DD>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 <B>:spacing2</B> options in
|
|
|
|
|
tags.
|
|
|
|
|
<P>
|
|
|
|
|
<P>
|
|
|
|
|
<DT><I>Name</I>: <B>spacing3</B>
|
|
|
|
|
<DT><I>Class</I>: <B>Spacing3</B>
|
|
|
|
|
<DT><I>Option keyword</I>: <B><A NAME="M32">:spacing3</A></B>
|
|
|
|
|
<DT><I>STklos slot name</I>: <B>spacing3</B>
|
|
|
|
|
<DD>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 <B>:spacing3</B> options in
|
|
|
|
|
tags.
|
|
|
|
|
<P>
|
|
|
|
|
<P>
|
|
|
|
|
<DT><I>Name</I>: <B>state</B>
|
|
|
|
|
<DT><I>Class</I>: <B>State</B>
|
|
|
|
|
<DT><I>Option keyword</I>: <B><A NAME="M33">:state</A></B>
|
|
|
|
|
<DT><I>STklos slot name</I>: <B>state</B>
|
|
|
|
|
<DD>Specifies one of two states for the text: <B>normal</B> or <B>disabled</B>.
|
|
|
|
|
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.
|
|
|
|
|
<P>
|
|
|
|
|
<P>
|
|
|
|
|
<DT><I>Name</I>: <B>tabs</B>
|
|
|
|
|
<DT><I>Class</I>: <B>Tabs</B>
|
|
|
|
|
<DT><I>Option keyword</I>: <B><A NAME="M34">:tabs</A></B>
|
|
|
|
|
<DT><I>STklos slot name</I>: <B>tabs</B>
|
|
|
|
|
<DD>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 <B>left</B>, <B>right</B>, <B>center</B>,
|
|
|
|
|
or <B>numeric</B>, which specifies how to justify
|
|
|
|
|
text relative to the tab stop. <B>Left</B> is the default; it causes
|
|
|
|
|
the text following the tab character to be positioned with its left edge
|
|
|
|
|
at the tab position. <B>Right</B> means that the right edge of the text
|
|
|
|
|
following the tab character is positioned at the tab position, and
|
|
|
|
|
<B>center</B> means that the text is centered at the tab position.
|
|
|
|
|
<B>Numeric</B> 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, <B>:tabs `(2c left 4c 6c center)</B> 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 <B>tabs</B> option may be overridden by <B>:tabs</B>
|
|
|
|
|
options in tags.
|
|
|
|
|
If no <B>:tabs</B> option is specified, or if it is specified as
|
|
|
|
|
an empty list, then Tk uses default tabs spaced every eight
|
|
|
|
|
(average size) characters.
|
|
|
|
|
<P>
|
|
|
|
|
<P>
|
|
|
|
|
<DT><I>Name</I>: <B>width</B>
|
|
|
|
|
<DT><I>Class</I>: <B>Width</B>
|
|
|
|
|
<DT><I>Option keyword</I>: <B><A NAME="M35">:width</A></B>
|
|
|
|
|
<DT><I>STklos slot name</I>: <B>width</B>
|
|
|
|
|
<DD>Specifies the desired width for the window in units of characters
|
|
|
|
|
in the font given by the <B>:font</B> 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.
|
|
|
|
|
<P>
|
|
|
|
|
<P>
|
|
|
|
|
<DT><I>Name</I>: <B>wrap</B>
|
|
|
|
|
<DT><I>Class</I>: <B>Wrap</B>
|
|
|
|
|
<DT><I>Option keyword</I>: <B><A NAME="M36">:wrap</A></B>
|
|
|
|
|
<DT><I>STklos slot name</I>: <B>wrap</B>
|
|
|
|
|
<DD>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 <B>none</B> or <B>char</B> or <B>word</B>.
|
|
|
|
|
A wrap mode of <B>none</B> 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 <B>char</B> mode a screen line break may occur after any character;
|
|
|
|
|
in <B>word</B> mode a line break will only be made at word boundaries.
|
|
|
|
|
<P>
|
|
|
|
|
</DL>
|
|
|
|
|
<H3><A NAME="M37">DESCRIPTION</A></H3>
|
|
|
|
|
The <B>text</B> procedure creates a new window (given by the
|
|
|
|
|
<I>widget-name</I> argument) and makes it into a text widget.
|
|
|
|
|
Additional
|
|
|
|
|
options, described above, may be specified on the procedure line
|
|
|
|
|
or in the option database
|
|
|
|
|
to configure aspects of the text such as its default background color
|
|
|
|
|
and relief. The <B>text</B> procedure returns the
|
|
|
|
|
path name of the new window.
|
|
|
|
|
<P>
|
|
|
|
|
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, STk procedures 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.
|
|
|
|
|
<P>
|
|
|
|
|
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.
|
|
|
|
|
<P>
|
|
|
|
|
The third form of annotation allows arbitrary windows to be
|
|
|
|
|
embedded in a text widget.
|
|
|
|
|
See EMBEDDED WINDOWS below for more details.
|
|
|
|
|
|
|
|
|
|
<H3><A NAME="M38">INDICES</A></H3>
|
|
|
|
|
Many of the widget procedures 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
|
|
|
|
|
<PRE><I>base modifier modifier modifier ...</I></PRE>
|
|
|
|
|
Where <I>base</I> gives a starting point and the <I>modifier</I>s
|
|
|
|
|
adjust the index from the starting point (e.g. move forward or
|
|
|
|
|
backward one character). Every index must contain a <I>base</I>,
|
|
|
|
|
but the <I>modifier</I>s are optional.
|
|
|
|
|
<P>
|
|
|
|
|
The <I>base</I> for an index must have one of the following forms:
|
|
|
|
|
<P>
|
|
|
|
|
<DL>
|
|
|
|
|
<DT><A NAME="M39"><I>line</I><B>.</B><I>char</I></A><DD>
|
|
|
|
|
<DT><A NAME="M40">(<I>line</I><B> . </B><I>char</I>)</A><DD>
|
|
|
|
|
Indicates <I>char</I>'th character on line <I>line</I>.
|
|
|
|
|
Lines are numbered from 1 for consistency with other UNIX programs
|
|
|
|
|
that use this numbering scheme.
|
|
|
|
|
Within a line, characters are numbered from 0.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M41"><B>@</B><I>x</I><B>,</B><I>y</I></A><DD>
|
|
|
|
|
Indicates the character that covers the pixel whose x and y coordinates
|
|
|
|
|
within the text's window are <I>x</I> and <I>y</I>.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M42"><B>end</B></A><DD>
|
|
|
|
|
Indicates the end of the text (the character just after the last
|
|
|
|
|
newline).
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M43"><I>mark</I></A><DD>
|
|
|
|
|
Indicates the character just after the mark whose name is <I>mark</I>.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M44"><I>tag</I><B>.first</B></A><DD>
|
|
|
|
|
Indicates the first character in the text that has been tagged with
|
|
|
|
|
<I>tag</I>.
|
|
|
|
|
This form generates an error if no characters are currently tagged
|
|
|
|
|
with <I>tag</I>.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M45"><I>tag</I><B>.last</B></A><DD>
|
|
|
|
|
Indicates the character just after the last one in the text that has
|
|
|
|
|
been tagged with <I>tag</I>.
|
|
|
|
|
This form generates an error if no characters are currently tagged
|
|
|
|
|
with <I>tag</I>.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M46"><I>widget-name</I></A><DD>
|
|
|
|
|
Indicates the position of the embedded window whose name is
|
|
|
|
|
<I>widget-name</I>.
|
|
|
|
|
This form generates an error if there is no embedded window
|
|
|
|
|
by the given name.
|
|
|
|
|
<P>
|
|
|
|
|
</DL>
|
|
|
|
|
<P>
|
|
|
|
|
If modifiers follow the base index, each one of them must have one
|
|
|
|
|
of the forms listed below. Keywords such as <B>chars</B> and <B>wordend</B>
|
|
|
|
|
may be abbreviated as long as the abbreviation is unambiguous.
|
|
|
|
|
<P>
|
|
|
|
|
<DL>
|
|
|
|
|
<DT><A NAME="M47"><B>+ </B><I>count</I><B> chars</B></A><DD>
|
|
|
|
|
Adjust the index forward by <I>count</I> characters, moving to later
|
|
|
|
|
lines in the text if necessary. If there are fewer than <I>count</I>
|
|
|
|
|
characters in the text after the current index, then set the index
|
|
|
|
|
to the last character in the text.
|
|
|
|
|
Spaces on either side of <I>count</I> are optional.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M48"><B>: </B><I>count</I><B> chars</B></A><DD>
|
|
|
|
|
Adjust the index backward by <I>count</I> characters, moving to earlier
|
|
|
|
|
lines in the text if necessary. If there are fewer than <I>count</I>
|
|
|
|
|
characters in the text before the current index, then set the index
|
|
|
|
|
to the first character in the text.
|
|
|
|
|
Spaces on either side of <I>count</I> are optional.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M49"><B>+ </B><I>count</I><B> lines</B></A><DD>
|
|
|
|
|
Adjust the index forward by <I>count</I> lines, retaining the same
|
|
|
|
|
character position within the line. If there are fewer than <I>count</I>
|
|
|
|
|
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 <I>count</I> are optional.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M50"><B>- </B><I>count</I><B> lines</B></A><DD>
|
|
|
|
|
Adjust the index backward by <I>count</I> lines, retaining the same
|
|
|
|
|
character position within the line. If there are fewer than <I>count</I>
|
|
|
|
|
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 <I>count</I> are optional.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M51"><B>linestart</B></A><DD>
|
|
|
|
|
Adjust the index to refer to the first character on the line.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M52"><B>lineend</B></A><DD>
|
|
|
|
|
Adjust the index to refer to the last character on the line (the newline).
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M53"><B>wordstart</B></A><DD>
|
|
|
|
|
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.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M54"><B>wordend</B></A><DD>
|
|
|
|
|
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.
|
|
|
|
|
<P>
|
|
|
|
|
</DL>
|
|
|
|
|
<P>
|
|
|
|
|
If more than one modifier is present then they are applied in
|
|
|
|
|
left-to-right order. For example, the index ``<B>end - 1 chars</B>''
|
|
|
|
|
refers to the next-to-last character in the text and
|
|
|
|
|
``<B>insert wordstart - 1 c</B>'' refers to the character just before
|
|
|
|
|
the first one in the word containing the insertion cursor.
|
|
|
|
|
<H3><A NAME="M55">TAGS</A></H3>
|
|
|
|
|
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), <B>+</B>, or <B>:</B>:
|
|
|
|
|
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.
|
|
|
|
|
<P>
|
|
|
|
|
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 procedures to it), it is given
|
|
|
|
|
a priority higher than any existing tag.
|
|
|
|
|
The priority order of tags may be redefined using the
|
|
|
|
|
``<I>widget-name </I><B>'tag 'raise</B>'' and ``<I>widget-name </I><B>'tag 'lower</B>''
|
|
|
|
|
widget procedures.
|
|
|
|
|
<P>
|
|
|
|
|
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
|
1998-04-10 06:59:06 -04:00
|
|
|
<B>background</B>, <B><A HREF="./font.n.html">font</A></B>, and <B>foreground</B> options for the
|
1996-09-27 06:29:02 -04:00
|
|
|
text widget.
|
|
|
|
|
However, display options may be associated with individual tags
|
|
|
|
|
using the ``<I>widget-name </I><B>tag configure</B>'' widget procedure.
|
|
|
|
|
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:
|
|
|
|
|
<P>
|
|
|
|
|
<DL>
|
|
|
|
|
<DT><A NAME="M56"><B>:background </B><I>color</I></A><DD>
|
|
|
|
|
<I>Color</I> specifies the background color to use for characters
|
|
|
|
|
associated with the tag.
|
|
|
|
|
It may have any of the forms accepted by <B>Tk_GetColor</B>.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M57"><B>:bgstipple </B><I>bitmap</I></A><DD>
|
|
|
|
|
<I>Bitmap</I> specifies a bitmap that is used as a stipple pattern
|
|
|
|
|
for the background.
|
|
|
|
|
It may have any of the forms accepted by <B>Tk_GetBitmap</B>.
|
|
|
|
|
If <I>bitmap</I> hasn't been specified, or if it is specified
|
|
|
|
|
as an empty string, then a solid fill will be used for the
|
|
|
|
|
background.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M58"><B>:borderwidth </B><I>pixels</I></A><DD>
|
|
|
|
|
<I>Pixels</I> specifies the width of a 3-D border to draw around
|
|
|
|
|
the background.
|
|
|
|
|
It may have any of the forms accepted by <B>Tk_GetPixels</B>.
|
|
|
|
|
This option is used in conjunction with the <B>:relief</B>
|
|
|
|
|
option to give a 3-D appearance to the background for characters;
|
|
|
|
|
it is ignored unless the <B>:background</B> option
|
|
|
|
|
has been set for the tag.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M59"><B>:fgstipple </B><I>bitmap</I></A><DD>
|
|
|
|
|
<I>Bitmap</I> 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 <B>Tk_GetBitmap</B>.
|
|
|
|
|
If <I>bitmap</I> hasn't been specified, or if it is specified
|
|
|
|
|
as an empty string, then a solid fill will be used.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M60"><B>:font </B><I>fontName</I></A><DD>
|
|
|
|
|
<I>FontName</I> is the name of a font to use for drawing characters.
|
|
|
|
|
It may have any of the forms accepted by <B>Tk_GetFontStruct</B>.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M61"><B>:foreground </B><I>color</I></A><DD>
|
|
|
|
|
<I>Color</I> specifies the color to use when drawing text and other
|
|
|
|
|
foreground information such as underlines.
|
|
|
|
|
It may have any of the forms accepted by <B>Tk_GetColor</B>.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M62"><B>:justify </B><I>justify</I></A><DD>
|
|
|
|
|
If the first character of a display line has a tag for which this
|
|
|
|
|
option has been specified, then <I>justify</I> determines how to
|
|
|
|
|
justify the line.
|
|
|
|
|
It must be one of <B>left</B>, <B>right</B>, or <B>center</B>.
|
|
|
|
|
If a line wraps, then the justification for each line on the
|
|
|
|
|
display is determined by the first character of that display line.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M63"><B>:lmargin1 </B><I>pixels</I></A><DD>
|
|
|
|
|
If the first character of a text line has a tag for which this
|
|
|
|
|
option has been specified, then <I>pixels</I> specifies how
|
|
|
|
|
much the line should be indented from the left edge of the
|
|
|
|
|
window.
|
|
|
|
|
<I>Pixels</I> 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 <B>:lmargin2</B> option controls
|
|
|
|
|
the indentation for subsequent lines.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M64"><B>:lmargin2 </B><I>pixels</I></A><DD>
|
|
|
|
|
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
|
|
|
|
|
<I>pixels</I> specifies how much the line should be indented from
|
|
|
|
|
the left edge of the window.
|
|
|
|
|
<I>Pixels</I> 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.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M65"><B>:offset </B><I>pixels</I></A><DD>
|
|
|
|
|
<I>Pixels</I> 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.
|
|
|
|
|
<I>Pixels</I> may have any of the standard forms for screen
|
|
|
|
|
distances.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M66"><B>:overstrike </B><I>boolean</I></A><DD>
|
|
|
|
|
Specifies whether or not to draw a horizontal rule through
|
|
|
|
|
the middle of characters.
|
|
|
|
|
<I>Boolean</I> may have any of the forms accepted by <B>Tk_GetBoolean</B>.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M67"><B>:relief </B><I>relief</I></A><DD>
|
|
|
|
|
<I>Relief</I> specifies the 3-D relief to use for drawing backgrounds,
|
|
|
|
|
in any of the forms accepted by <B>Tk_GetRelief</B>.
|
|
|
|
|
This option is used in conjunction with the <B>:borderwidth</B>
|
|
|
|
|
option to give a 3-D appearance to the background for characters;
|
|
|
|
|
it is ignored unless the <B>:background</B> option
|
|
|
|
|
has been set for the tag.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M68"><B>:rmargin </B><I>pixels</I></A><DD>
|
|
|
|
|
If the first character of a display line has a tag for which this
|
|
|
|
|
option has been specified, then <I>pixels</I> specifies how wide
|
|
|
|
|
a margin to leave between the end of the line and the right
|
|
|
|
|
edge of the window.
|
|
|
|
|
<I>Pixels</I> 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.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M69"><B>:spacing1 </B><I>pixels</I></A><DD>
|
|
|
|
|
<I>Pixels</I> 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.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M70"><B>:spacing2 </B><I>pixels</I></A><DD>
|
|
|
|
|
For lines that wrap, this option specifies how much additional
|
|
|
|
|
space to leave between the display lines for a single text line.
|
|
|
|
|
<I>Pixels</I> may have any of the standard forms for screen
|
|
|
|
|
distances.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M71"><B>:spacing3 </B><I>pixels</I></A><DD>
|
|
|
|
|
<I>Pixels</I> 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.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M72"><B>:tabs </B><I>tabList</I></A><DD>
|
|
|
|
|
<I>TabList</I> specifies a set of tab stops in the same form
|
|
|
|
|
as for the <B>:tabs</B> 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 <B>:tags " "</B>, then it requests
|
|
|
|
|
default 8-character tabs as described for the <B>tags</B>
|
|
|
|
|
widget option.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M73"><B>:underline </B><I>boolean</I></A><DD>
|
|
|
|
|
<I>Boolean</I> specifies whether or not to draw an underline underneath
|
|
|
|
|
characters.
|
|
|
|
|
It may have any of the forms accepted by <B>Tk_GetBoolean</B>.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M74"><B>:wrap </B><I>mode</I></A><DD>
|
|
|
|
|
<I>Mode</I> specifies how to handle lines that are wider than the
|
|
|
|
|
text's window.
|
|
|
|
|
It has the same legal values as the <B>:wrap</B> option
|
|
|
|
|
for the text widget: <B>none</B>, <B>char</B>, or <B>word</B>.
|
|
|
|
|
If this tag option is specified, it overrides the <B>:wrap</B> option
|
|
|
|
|
for the text widget.
|
|
|
|
|
<P>
|
|
|
|
|
</DL>
|
|
|
|
|
<P>
|
|
|
|
|
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.
|
|
|
|
|
<P>
|
|
|
|
|
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
|
|
|
|
|
STk procedure 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 <B>tag bind</B> widget
|
|
|
|
|
procedure below.
|
|
|
|
|
<P>
|
|
|
|
|
The third use for tags is in managing the selection.
|
|
|
|
|
See THE SELECTION below.
|
|
|
|
|
|
|
|
|
|
<H3><A NAME="M75">MARKS</A></H3>
|
|
|
|
|
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 ``<I>widget-name </I><B>mark</B>'' widget
|
|
|
|
|
procedure, and their current locations may be determined by using the
|
|
|
|
|
mark name as an index in widget procedures.
|
|
|
|
|
<P>
|
|
|
|
|
Each mark also has a <I>gravity</I>, which is either <B>left</B> or
|
|
|
|
|
<B>right</B>.
|
|
|
|
|
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 <B>right</B>.
|
|
|
|
|
<P>
|
|
|
|
|
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.
|
|
|
|
|
<P>
|
|
|
|
|
Two marks have special significance.
|
|
|
|
|
First, the mark <B>insert</B> is associated with the insertion cursor,
|
|
|
|
|
as described under THE INSERTION CURSOR below.
|
|
|
|
|
Second, the mark <B>current</B> 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: <B>current</B> 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.
|
|
|
|
|
|
|
|
|
|
<H3><A NAME="M76">EMBEDDED WINDOWS</A></H3>
|
|
|
|
|
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.
|
|
|
|
|
<P>
|
|
|
|
|
When an embedded window is added to a text widget with the
|
|
|
|
|
<B>window create</B> widget procedure, several configuration
|
|
|
|
|
options may be associated with it.
|
|
|
|
|
These options may be modified later with the <B>window configure</B>
|
|
|
|
|
widget procedure.
|
|
|
|
|
The following options are currently supported:
|
|
|
|
|
<P>
|
|
|
|
|
<DL>
|
|
|
|
|
<DT><A NAME="M77"><B>:align </B><I>where</I></A><DD>
|
|
|
|
|
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.
|
|
|
|
|
<I>Where</I> must have one of the values <B>top</B> (align the top of the window
|
|
|
|
|
with the top of the line), <B>center</B> (center the window
|
|
|
|
|
within the range of the line), <B>bottom</B> (align the bottom of the
|
|
|
|
|
window with the bottom of the line's area),
|
|
|
|
|
or <B>baseline</B> (align the bottom of the window with the baseline
|
|
|
|
|
of the line).
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M78"><B>:create </B><I>procedure</I></A><DD>
|
|
|
|
|
Specifies a STk procedure that may be evaluated to create the window
|
|
|
|
|
for the annotation.
|
|
|
|
|
If no <B>:window</B> option has been specified for the annotation
|
|
|
|
|
this script will be evaluated when the annotation is about to
|
|
|
|
|
be displayed on the screen.
|
|
|
|
|
<I>Script</I> must create a window for the annotation and return
|
|
|
|
|
that window as its result.
|
|
|
|
|
If the annotation's window should ever be deleted, <I>procedure</I>
|
|
|
|
|
will be evaluated again the next time the annotation is displayed.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M79"><B>:padx </B><I>pixels</I></A><DD>
|
|
|
|
|
<I>Pixels</I> 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.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M80"><B>:pady </B><I>pixels</I></A><DD>
|
|
|
|
|
<I>Pixels</I> 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.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M81"><B>:stretch </B><I>boolean</I></A><DD>
|
|
|
|
|
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 <B>:pady</B> option has been specified as well, then the
|
|
|
|
|
requested padding will be retained even if the window is
|
|
|
|
|
stretched.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M82"><B>:window </B><I>widget-name</I></A><DD>
|
|
|
|
|
Specifies the window to display in the annotation.
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
</DL>
|
|
|
|
|
<H3><A NAME="M83">THE SELECTION</A></H3>
|
|
|
|
|
Text widgets support the standard X selection.
|
|
|
|
|
Selection support is implemented via tags.
|
|
|
|
|
If the <B>exportSelection</B> option for the text widget is true
|
|
|
|
|
then the <B>sel</B> tag will be associated with the selection:
|
|
|
|
|
<OL>
|
|
|
|
|
<LI>
|
|
|
|
|
Whenever characters are tagged with <B>sel</B> the text widget
|
|
|
|
|
will claim ownership of the selection.
|
|
|
|
|
<LI>
|
|
|
|
|
Attempts to retrieve the
|
|
|
|
|
selection will be serviced by the text widget, returning all the
|
|
|
|
|
characters with the <B>sel</B> tag.
|
|
|
|
|
<LI>
|
|
|
|
|
If the selection is claimed away by another application or by another
|
|
|
|
|
window within this application, then the <B>sel</B> tag will be removed
|
|
|
|
|
from all characters in the text.
|
|
|
|
|
</OL>
|
|
|
|
|
<P>
|
|
|
|
|
The <B>sel</B> tag is automatically defined when a text widget is
|
|
|
|
|
created, and it may not be deleted with the ``<I>widget-name </I><B>'tag 'delete</B>''
|
|
|
|
|
widget procedure. Furthermore, the <B>selectBackground</B>,
|
|
|
|
|
<B>selectBorderWidth</B>, and <B>selectForeground</B> options for
|
|
|
|
|
the text widget are tied to the <B>:background</B>,
|
|
|
|
|
<B>:borderwidth</B>, and <B>:foreground</B> options for the <B>sel</B>
|
|
|
|
|
tag: changes in either will automatically be reflected in the
|
|
|
|
|
other.
|
|
|
|
|
|
|
|
|
|
<H3><A NAME="M84">THE INSERTION CURSOR</A></H3>
|
|
|
|
|
The mark named <B>insert</B> has special significance in text widgets.
|
|
|
|
|
It is defined automatically when a text widget is created and it
|
|
|
|
|
may not be unset with the ``<I>widget-name </I><B>mark unset</B>'' widget
|
|
|
|
|
procedure.
|
|
|
|
|
The <B>insert</B> 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.
|
|
|
|
|
|
|
|
|
|
<H3><A NAME="M85">WIDGET PROCEDURE</A></H3>
|
|
|
|
|
The <B>text</B> procedure creates a new STk procedure whose
|
|
|
|
|
name is the same as the path name of the text's window. This
|
|
|
|
|
procedure may be used to invoke various
|
|
|
|
|
operations on the widget. It has the following general form:
|
|
|
|
|
<PRE>(<I>widget-name option </I>?<I>arg arg ...</I>?)</PRE>
|
|
|
|
|
<I>PathName</I> is the name of the procedure, which is the same as
|
|
|
|
|
the text widget's path name. <I>Option</I> and the <I>arg</I>s
|
|
|
|
|
determine the exact behavior of the procedure. The following
|
|
|
|
|
procedures are possible for text widgets:
|
|
|
|
|
<P>
|
|
|
|
|
<DL>
|
|
|
|
|
<DT><A NAME="M86">(<I>widget-name '</I><B>bbox </B><I>index</I>)</A><DD>
|
|
|
|
|
Returns a list of four elements describing the screen area
|
|
|
|
|
of the character given by <I>index</I>.
|
|
|
|
|
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.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M87">(<I>widget-name '</I><B>cget</B> <I>option</I>)</A><DD>
|
|
|
|
|
Returns the current value of the configuration option given
|
|
|
|
|
by <I>option</I>.
|
|
|
|
|
<I>Option</I> may have any of the values accepted by the <B>text</B>
|
|
|
|
|
procedure.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M88">(<I>widget-name '</I><B>compare</B> <I>index1 op index2</I>)</A><DD>
|
|
|
|
|
Compares the indices given by <I>index1</I> and <I>index2</I> according
|
|
|
|
|
to the relational operator given by <I>op</I>, and returns 1 if
|
|
|
|
|
the relationship is satisfied and 0 if it isn't.
|
|
|
|
|
<I>Op</I> must be one of the operators <, <=, ==, >=, >, or !=.
|
|
|
|
|
If <I>op</I> is == then 1 is returned if the two indices refer to
|
|
|
|
|
the same character, if <I>op</I> is < then 1 is returned if <I>index1</I>
|
|
|
|
|
refers to an earlier character in the text than <I>index2</I>, and
|
|
|
|
|
so on.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M89">(<I>widget-name '</I><B>configure</B> ?<I>option</I>? <I>?value option value ...</I>?)</A><DD>
|
|
|
|
|
Query or modify the configuration options of the widget.
|
|
|
|
|
If no <I>option</I> is specified, returns a list describing all of
|
|
|
|
|
the available options for <I>widget-name</I> (see <B>Tk_ConfigureInfo</B> for
|
|
|
|
|
information on the format of this list). If <I>option</I> is specified
|
|
|
|
|
with no <I>value</I>, then the procedure returns a list describing the
|
|
|
|
|
one named option (this list will be identical to the corresponding
|
|
|
|
|
sublist of the value returned if no <I>option</I> is specified). If
|
|
|
|
|
one or more <I>option-value</I> pairs are specified, then the procedure
|
|
|
|
|
modifies the given widget option(s) to have the given value(s); in
|
|
|
|
|
this case the procedure returns an empty string.
|
|
|
|
|
<I>Option</I> may have any of the values accepted by the <B>text</B>
|
|
|
|
|
procedure.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M90">(<I>widget-name '</I><B>debug </B>)</A><DD>
|
|
|
|
|
<DT><A NAME="M91">(<I>widget-name '</I><B>debug </B><I>boolean</I>)</A><DD>
|
|
|
|
|
If <I>boolean</I> 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 <I>boolean</I> has a false value then the debugging checks will
|
|
|
|
|
be turned off.
|
|
|
|
|
In either case the procedure returns an empty string.
|
|
|
|
|
If <I>boolean</I> is not specified then the procedure returns <B>on</B>
|
|
|
|
|
or <B>off</B> 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.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M92">(<I>widget-name '</I><B>delete </B><I>index1 </I>)</A><DD>
|
|
|
|
|
<DT><A NAME="M93">(<I>widget-name '</I><B>delete </B><I>index1 </I><I>index2</I>)</A><DD>
|
|
|
|
|
Delete a range of characters from the text.
|
|
|
|
|
If both <I>index1</I> and <I>index2</I> are specified, then delete
|
|
|
|
|
all the characters starting with the one given by <I>index1</I>
|
|
|
|
|
and stopping just before <I>index2</I> (i.e. the character at
|
|
|
|
|
<I>index2</I> is not deleted).
|
|
|
|
|
If <I>index2</I> doesn't specify a position later in the text
|
|
|
|
|
than <I>index1</I> then no characters are deleted.
|
|
|
|
|
If <I>index2</I> isn't specified then the single character at
|
|
|
|
|
<I>index1</I> 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 procedure returns an empty string.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M94">(<I>widget-name '</I><B>dlineinfo </B><I>index</I>)</A><DD>
|
|
|
|
|
Returns a list with five elements describing the area occupied
|
|
|
|
|
by the display line containing <I>index</I>.
|
|
|
|
|
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 <B>none</B> 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 <I>index</I> is not visible on
|
|
|
|
|
the screen then the return value is an empty list.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M95">(<I>widget-name </I><B>'dump </B>?<I>switches</I>? <I>index1 </I>?<I>index2</I>?)</A><DD>
|
|
|
|
|
Return the contents of the text widget from <I>index1</I> up to,
|
|
|
|
|
but not including <I>index2</I>,
|
|
|
|
|
including the text and
|
|
|
|
|
information about marks, tags, and embedded windows.
|
|
|
|
|
If <I>index2</I> is not specified, then it defaults to
|
|
|
|
|
one character past <I>index1</I>. The information is returned
|
|
|
|
|
in the following format:
|
|
|
|
|
<P>
|
|
|
|
|
</DL>
|
|
|
|
|
<P>
|
|
|
|
|
<UL>
|
|
|
|
|
<I>key1 value1 index1 key2 value2 index2</I> ...
|
|
|
|
|
<P>
|
|
|
|
|
The possible <I>key</I> values are <B>text</B>, <B>mark</B>,
|
|
|
|
|
<B>tagon</B>, <B>tagoff</B>, and <B>window</B>. The corresponding
|
|
|
|
|
<I>value</I> is the text, mark name, tag name, or window name.
|
|
|
|
|
The <I>index</I> 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:
|
|
|
|
|
<P>
|
|
|
|
|
<DL>
|
|
|
|
|
<DT><A NAME="M96"><B>:all</B></A><DD>
|
|
|
|
|
Return information about all elements: text, marks, tags, and windows.
|
|
|
|
|
This is the default.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M97"><B>:command </B><I>closure</I></A><DD>
|
|
|
|
|
Instead of returning the information as the result of the dump operation,
|
|
|
|
|
invoke the <I>closure</I> on each element of the text widget within the range.
|
|
|
|
|
The command must have three arguments: <I>key</I>, <I>value</I>, and <I>index</I>.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M98"><B>:mark</B></A><DD>
|
|
|
|
|
Include information about marks in the dump results.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M99"><B>:tag</B></A><DD>
|
|
|
|
|
Include information about tag transitions in the dump results. Tag information is
|
|
|
|
|
returned as <B>tagon</B> and <B>tagoff</B> elements that indicate the
|
|
|
|
|
begin and end of each range of each tag, respectively.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M100"><B>:text</B></A><DD>
|
|
|
|
|
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 <I>index2</I>.
|
|
|
|
|
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.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M101"><B>:window</B></A><DD>
|
|
|
|
|
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.
|
|
|
|
|
<P>
|
|
|
|
|
</DL>
|
|
|
|
|
</UL>
|
|
|
|
|
<P>
|
|
|
|
|
<DL>
|
|
|
|
|
<DT><A NAME="M102">(<I>widget-name </I><B>'get </B><I>index1 </I>)</A><DD>
|
|
|
|
|
<DT><A NAME="M103">(<I>widget-name </I><B>'get </B><I>index1 </I><I>index2</I>)</A><DD>
|
|
|
|
|
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 <I>index1</I> and ending just before
|
|
|
|
|
the one whose index is <I>index2</I> (the character at <I>index2</I>
|
|
|
|
|
will not be returned).
|
|
|
|
|
If <I>index2</I> is omitted then the single character at <I>index1</I>
|
|
|
|
|
is returned.
|
|
|
|
|
If there are no characters in the specified range (e.g. <I>index1</I>
|
|
|
|
|
is past the end of the file or <I>index2</I> is less than or equal
|
|
|
|
|
to <I>index1</I>) then an empty string is returned.
|
|
|
|
|
If the specified range contains embedded windows, no information
|
|
|
|
|
about them is included in the returned string.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M104">(<I>widget-name '</I><B>index </B><I>index</I>)</A><DD>
|
|
|
|
|
Returns the position corresponding to <I>index</I> in the form
|
|
|
|
|
<I>(line . char)</I> where <I>line</I> is the line number and <I>char</I>
|
|
|
|
|
is the character number.
|
|
|
|
|
<I>Index</I> may have any of the forms described under INDICES above.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M105">(<I>widget-name '</I><B>insert </B><I>index chars </I>?<I>tagList chars tagList ...</I>?)</A><DD>
|
|
|
|
|
Inserts all of the <I>chars</I> arguments just before the character at
|
|
|
|
|
<I>index</I>.
|
|
|
|
|
If <I>index</I> 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 <I>chars</I> argument and no <I>tagList</I>, 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 <I>tagList</I> 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 <I>chars</I>-<I>tagList</I> argument pairs are present,
|
|
|
|
|
they produce the same effect as if a separate <B>insert</B> widget
|
|
|
|
|
procedure had been issued for each pair, in order.
|
|
|
|
|
The last <I>tagList</I> argument may be omitted.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M106">(<I>widget-name '</I><B>mark </B><I>option </I>?<I>arg arg ...</I>?)</A><DD>
|
|
|
|
|
This procedure is used to manipulate marks. The exact behavior of
|
|
|
|
|
the procedure depends on the <I>option</I> argument that follows
|
|
|
|
|
the <B>mark</B> argument. The following forms of the procedure
|
|
|
|
|
are currently supported:
|
|
|
|
|
<P>
|
|
|
|
|
<P>
|
|
|
|
|
<DL>
|
|
|
|
|
<DT><A NAME="M107">(<I>widget-name '</I><B>mark 'gravity </B><I>markName</I>)</A><DD>
|
|
|
|
|
<DT><A NAME="M108">(<I>widget-name '</I><B>mark 'gravity </B><I>markName</I> <I>direction</I>)</A><DD>
|
|
|
|
|
If <I>direction</I> is not specified, returns <B>left</B> or <B>right</B>
|
|
|
|
|
to indicate which of its adjacent characters <I>markName</I> is attached
|
|
|
|
|
to.
|
|
|
|
|
If <I>direction</I> is specified, it must be <B>left</B> or <B>right</B>;
|
|
|
|
|
the gravity of <I>markName</I> is set to the given value.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M109">(<I>widget-name '</I><B>mark 'names</B>)</A><DD>
|
|
|
|
|
Returns a list whose elements are the names of all the marks that
|
|
|
|
|
are currently set.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M110">(<I>widget-name '</I><B>mark 'next </B><I>index</I>)</A><DD>
|
|
|
|
|
Returns the name of the next mark at or after <I>index</I>.
|
|
|
|
|
If <I>index</I> is specified in numerical form, then the search for
|
|
|
|
|
the next mark begins at that index.
|
|
|
|
|
If <I>index</I> 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 <B>mark next</B> 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 <B>dump</B> operation.
|
|
|
|
|
If a mark has been set to the special <B>end index,
|
|
|
|
|
then it appears to be </B><I>after</I> <B>end</B> with respect to the <B>mark next</B> operation.
|
|
|
|
|
An empty list is returned if there are no marks after <I>index</I>.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M111">(<I>widget-name '</I><B>mark 'previous </B><I>index</I>)</A><DD>
|
|
|
|
|
Returns the name of the mark at or before <I>index</I>.
|
|
|
|
|
If <I>index</I> is specified in numerical form, then the search for
|
|
|
|
|
the previous mark begins with the character just before that index.
|
|
|
|
|
If <I>index</I> 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 <B>mark previous</B> 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 <B>dump</B> operation.
|
|
|
|
|
An empty list is returned if there are no marks before <I>index</I>.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M112">(<I>widget-name '</I><B>mark 'set </B><I>markName index</I>)</A><DD>
|
|
|
|
|
Sets the mark named <I>markName</I> to a position just before the
|
|
|
|
|
character at <I>index</I>.
|
|
|
|
|
If <I>markName</I> already exists, it is moved from its old position;
|
|
|
|
|
if it doesn't exist, a new mark is created.
|
|
|
|
|
This procedure returns an empty string.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M113">(<I>widget-name '</I><B>mark 'unset </B><I>markName </I>?<I>markName markName ...</I>?)</A><DD>
|
|
|
|
|
Remove the mark corresponding to each of the <I>markName</I> arguments.
|
|
|
|
|
The removed marks will not be usable in indices and will not be
|
|
|
|
|
returned by future calls to ``<I>widget-name </I><B>mark names</B>''.
|
|
|
|
|
This procedure returns an empty string.
|
|
|
|
|
<P>
|
|
|
|
|
</DL>
|
|
|
|
|
<DT><A NAME="M114">(<I>widget-name '</I><B>scan</B> <I>option args</I>)</A><DD>
|
|
|
|
|
This procedure is used to implement scanning on texts. It has
|
|
|
|
|
two forms, depending on <I>option</I>:
|
|
|
|
|
<P>
|
|
|
|
|
<P>
|
|
|
|
|
<DL>
|
|
|
|
|
<DT><A NAME="M115">(<I>widget-name '</I><B>scan 'mark </B><I>x y</I>)</A><DD>
|
|
|
|
|
Records <I>x</I> and <I>y</I> and the current view in the text window,
|
|
|
|
|
for use in conjunction with later <B>scan dragto</B> procedures.
|
|
|
|
|
Typically this procedure is associated with a mouse button press in
|
|
|
|
|
the widget. It returns an empty string.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M116">(<I>widget-name '</I><B>scan 'dragto </B><I>x y</I>)</A><DD>
|
|
|
|
|
This procedure computes the difference between its <I>x</I> and <I>y</I>
|
|
|
|
|
arguments and the <I>x</I> and <I>y</I> arguments to the last
|
|
|
|
|
<B>scan mark</B> procedure for the widget.
|
|
|
|
|
It then adjusts the view by 10 times the difference in coordinates.
|
|
|
|
|
This procedure 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.
|
|
|
|
|
<P>
|
|
|
|
|
</DL>
|
|
|
|
|
<DT><A NAME="M117">(<I>widget-name </I><B>search </B>?<I>switches</I>? <I>pattern index </I>?<I>stopIndex</I>?)</A><DD>
|
|
|
|
|
Searches the text in <I>widget-name</I> starting at <I>index</I> for a range
|
|
|
|
|
of characters that matches <I>pattern</I>.
|
|
|
|
|
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:
|
|
|
|
|
<P>
|
|
|
|
|
<P>
|
|
|
|
|
<DL>
|
|
|
|
|
<DT><A NAME="M118"><B>:forwards</B></A><DD>
|
|
|
|
|
The search will proceed forward through the text, finding the first
|
|
|
|
|
matching range starting at or after the position given by <I>index</I>.
|
|
|
|
|
This is the default.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M119"><B>:backwards</B></A><DD>
|
|
|
|
|
The search will proceed backward through the text, finding the
|
|
|
|
|
matching range closest to <I>index</I> whose first character
|
|
|
|
|
is before <I>index</I>.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M120"><B>:exact</B></A><DD>
|
|
|
|
|
Use exact matching: the characters in the matching range must be
|
|
|
|
|
identical to those in <I>pattern</I>.
|
|
|
|
|
This is the default.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M121"><B>:regexp</B></A><DD>
|
|
|
|
|
Treat <I>pattern</I> as a regular expression and match it against
|
|
|
|
|
the text using the rules for regular expressions (see the <B>regexp</B>
|
|
|
|
|
procedure for details).
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M122"><B>:nocase</B></A><DD>
|
|
|
|
|
Ignore case differences between the pattern and the text.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M123"><B>:count</B><I> varName</I></A><DD>
|
|
|
|
|
The argument following <B>:count</B> 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.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M124"><B>:-</B></A><DD>
|
|
|
|
|
This switch has no effect except to terminate the list of switches:
|
|
|
|
|
the next argument will be treated as <I>pattern</I> even if it starts
|
|
|
|
|
with <B>:</B>.
|
|
|
|
|
<P>
|
|
|
|
|
</DL>
|
|
|
|
|
<UL>
|
|
|
|
|
<P>
|
|
|
|
|
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 <B>$</B> feature in regular
|
|
|
|
|
expressions to match the end of a line.
|
|
|
|
|
For exact matching the newlines are retained.
|
|
|
|
|
If <I>stopIndex</I> is specified, the search stops at that index:
|
|
|
|
|
for forward searches, no match at or after <I>stopIndex</I> will
|
|
|
|
|
be considered; for backward searches, no match earlier in the
|
|
|
|
|
text than <I>stopIndex</I> will be considered.
|
|
|
|
|
If <I>stopIndex</I> 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 <I>stopIndex</I> is specified, no wrap-around will occur.
|
|
|
|
|
</UL>
|
|
|
|
|
<DT><A NAME="M125">(<I>widget-name '</I><B>see </B><I>index</I>)</A><DD>
|
|
|
|
|
Adjusts the view in the window so that the character given by <I>index</I>
|
|
|
|
|
is completely visible.
|
|
|
|
|
If <I>index</I> is already visible then the procedure does nothing.
|
|
|
|
|
If <I>index</I> is a short distance out of view, the procedure
|
|
|
|
|
adjusts the view just enough to make <I>index</I> visible at the
|
|
|
|
|
edge of the window.
|
|
|
|
|
If <I>index</I> is far out of view, then the procedure centers
|
|
|
|
|
<I>index</I> in the window.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M126">(<I>widget-name </I><B>'tag </B><I>option </I>?<I>arg arg ...</I>?)</A><DD>
|
|
|
|
|
This procedure is used to manipulate tags. The exact behavior of the
|
|
|
|
|
procedure depends on the <I>option</I> argument that follows the
|
|
|
|
|
<B>tag</B> argument. The following forms of the procedure are currently
|
|
|
|
|
supported:
|
|
|
|
|
<P>
|
|
|
|
|
<P>
|
|
|
|
|
<DL>
|
|
|
|
|
<DT><A NAME="M127">(<I>widget-name </I><B>'tag 'add </B><I>tagName index1 </I>?<I>index2 index1 index2 ...</I>?)</A><DD>
|
|
|
|
|
Associate the tag <I>tagName</I> with all of the characters starting
|
|
|
|
|
with <I>index1</I> and ending just before
|
|
|
|
|
<I>index2</I> (the character at <I>index2</I> isn't tagged).
|
|
|
|
|
A single procedure may contain any number of <I>index1</I>-<I>index2</I>
|
|
|
|
|
pairs.
|
|
|
|
|
If the last <I>index2</I> is omitted then the single character at
|
|
|
|
|
<I>index1</I> is tagged.
|
|
|
|
|
If there are no characters in the specified range (e.g. <I>index1</I>
|
|
|
|
|
is past the end of the file or <I>index2</I> is less than or equal
|
|
|
|
|
to <I>index1</I>) then the procedure has no effect.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M128">(<I>widget-name </I><B>'tag 'bind </B><I>tagName</I>)</A><DD>
|
|
|
|
|
<DT><A NAME="M129">(<I>widget-name </I><B>'tag 'bind </B><I>tagName</I> <I>sequence</I>)</A><DD>
|
|
|
|
|
<DT><A NAME="M130">(<I>widget-name </I><B>'tag 'bind </B><I>tagName</I> <I>sequence</I> <I>script</I>)</A><DD>
|
|
|
|
|
This procedure associates <I>script</I> with the tag given by
|
|
|
|
|
<I>tagName</I>.
|
|
|
|
|
Whenever the event sequence given by <I>sequence</I> occurs for a
|
|
|
|
|
character that has been tagged with <I>tagName</I>,
|
|
|
|
|
the script will be invoked.
|
|
|
|
|
This widget procedure is similar to the <B><A HREF="./bind.n.html">bind</A></B> procedure except that
|
|
|
|
|
it operates on characters in a text rather than entire widgets.
|
|
|
|
|
See the <B><A HREF="./bind.n.html">bind</A></B> manual entry for complete details
|
|
|
|
|
on the syntax of <I>sequence</I> and the substitutions performed
|
|
|
|
|
on <I>script</I> before invoking it.
|
|
|
|
|
If all arguments are specified then a new binding is created, replacing
|
|
|
|
|
any existing binding for the same <I>sequence</I> and <I>tagName</I>.
|
|
|
|
|
In this case the return value is an empty string.
|
|
|
|
|
If <I>script</I> is omitted then the procedure returns the <I>script</I>
|
|
|
|
|
associated with <I>tagName</I> and <I>sequence</I> (an error occurs
|
|
|
|
|
if there is no such binding).
|
|
|
|
|
If both <I>script</I> and <I>sequence</I> are omitted then the procedure
|
|
|
|
|
returns a list of all the sequences for which bindings have been
|
|
|
|
|
defined for <I>tagName</I>.
|
|
|
|
|
<P>
|
|
|
|
|
<UL>
|
|
|
|
|
<P>
|
|
|
|
|
The only events for which bindings may be specified are those related
|
|
|
|
|
to the mouse and keyboard, such as <B>Enter</B>, <B>Leave</B>,
|
|
|
|
|
<B>ButtonPress</B>, <B>Motion</B>, and <B>KeyPress</B>.
|
|
|
|
|
Event bindings for a text widget use the <B>current</B> mark
|
|
|
|
|
described under MARKS above.
|
|
|
|
|
An <B>Enter</B> event triggers for a tag when the tag first
|
|
|
|
|
becomes present on the current character, and a <B>Leave</B>
|
|
|
|
|
event triggers for a tag when it ceases to be present on
|
|
|
|
|
the current character.
|
|
|
|
|
<B>Enter</B> and <B>Leave</B> events can happen either because the
|
|
|
|
|
<B>current</B> mark moved or because the character at that
|
|
|
|
|
position changed.
|
|
|
|
|
Note that these events are different than <B>Enter</B> and <B>Leave</B>
|
|
|
|
|
events for windows.
|
|
|
|
|
Mouse and keyboard events are directed to the current character.
|
|
|
|
|
<P>
|
|
|
|
|
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 <B><A HREF="./bind.n.html">bind</A></B> procedure for details).
|
|
|
|
|
<B>continue</B> and <B>break</B> procedures within binding scripts
|
|
|
|
|
are processed in the same way as for bindings created with
|
|
|
|
|
the <B><A HREF="./bind.n.html">bind</A></B> procedure.
|
|
|
|
|
<P>
|
|
|
|
|
If bindings are created for the widget as a whole using the
|
|
|
|
|
<B><A HREF="./bind.n.html">bind</A></B> procedure, then those bindings will supplement the
|
|
|
|
|
tag bindings.
|
|
|
|
|
The tag bindings will be invoked first, followed by bindings
|
|
|
|
|
for the window as a whole.
|
|
|
|
|
</UL>
|
|
|
|
|
<DT><A NAME="M131">(<I>widget-name </I><B>'tag 'cget</B> <I>tagName option</I>)</A><DD>
|
|
|
|
|
This procedure returns the current value of the option named <I>option</I>
|
|
|
|
|
associated with the tag given by <I>tagName</I>.
|
|
|
|
|
<I>Option</I> may have any of the values accepted by the <B>tag configure</B>
|
|
|
|
|
widget procedure.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M132">(<I>widget-name </I><B>'tag 'configure </B><I>tagName</I> ?<I>option</I>? ?<I>value</I>? ?<I>option value ...</I>?)</A><DD>
|
|
|
|
|
This procedure is similar to the <B>configure</B> widget procedure except
|
|
|
|
|
that it modifies options associated with the tag given by <I>tagName</I>
|
|
|
|
|
instead of modifying options for the overall text widget.
|
|
|
|
|
If no <I>option</I> is specified, the procedure returns a list describing
|
|
|
|
|
all of the available options for <I>tagName</I> (see <B>Tk_ConfigureInfo</B>
|
|
|
|
|
for information on the format of this list).
|
|
|
|
|
If <I>option</I> is specified with no <I>value</I>, then the procedure returns
|
|
|
|
|
a list describing the one named option (this list will be identical to
|
|
|
|
|
the corresponding sublist of the value returned if no <I>option</I>
|
|
|
|
|
is specified).
|
|
|
|
|
If one or more <I>option-value</I> pairs are specified, then the procedure
|
|
|
|
|
modifies the given option(s) to have the given value(s) in <I>tagName</I>;
|
|
|
|
|
in this case the procedure returns an empty list.
|
|
|
|
|
See TAGS above for details on the options available for tags.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M133">(<I>widget-name </I><B>'tag 'delete </B><I>tagName </I>?<I>tagName ...</I>?)</A><DD>
|
|
|
|
|
Deletes all tag information for each of the <I>tagName</I>
|
|
|
|
|
arguments.
|
|
|
|
|
The procedure 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 procedure returns an empty list.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M134">(<I>widget-name</I><B>'tag 'lower </B><I>tagName </I>)</A><DD>
|
|
|
|
|
<DT><A NAME="M135">(<I>widget-name</I><B>'tag 'lower </B><I>tagName </I> <I>belowThis</I>)</A><DD>
|
|
|
|
|
Changes the priority of tag <I>tagName</I> so that it is just lower
|
|
|
|
|
in priority than the tag whose name is <I>belowThis</I>.
|
|
|
|
|
If <I>belowThis</I> is omitted, then <I>tagName</I>'s priority
|
|
|
|
|
is changed to make it lowest priority of all tags.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M136">(<I>widget-name </I><B>'tag 'names </B>)</A><DD>
|
|
|
|
|
<DT><A NAME="M137">(<I>widget-name </I><B>'tag 'names </B> <I>index</I>)</A><DD>
|
|
|
|
|
Returns a list whose elements are the names of all the tags that
|
|
|
|
|
are active at the character position given by <I>index</I>.
|
|
|
|
|
If <I>index</I> 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 ``<I>widget-name </I><B>tag</B>'' widget
|
|
|
|
|
procedure but haven't been deleted by a ``<I>widget-name </I><B>tag delete</B>''
|
|
|
|
|
widget procedure, even if no characters are currently marked with
|
|
|
|
|
the tag).
|
|
|
|
|
The list will be sorted in order from lowest priority to highest
|
|
|
|
|
priority.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M138">(<I>widget-name </I><B>'tag 'nextrange </B><I>tagName index1 </I>)</A><DD>
|
|
|
|
|
<DT><A NAME="M139">(<I>widget-name </I><B>'tag 'nextrange </B><I>tagName index1 </I> <I>index2</I>)</A><DD>
|
|
|
|
|
This procedure searches the text for a range of characters tagged
|
|
|
|
|
with <I>tagName</I> where the first character of the range is
|
|
|
|
|
no earlier than the character at <I>index1</I> and no later than
|
|
|
|
|
the character just before <I>index2</I> (a range starting at
|
|
|
|
|
<I>index2</I> will not be considered).
|
|
|
|
|
If several matching ranges exist, the first one is chosen.
|
|
|
|
|
The procedure'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 list.
|
|
|
|
|
If <I>index2</I> is not given then it defaults to the end of the text.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M140">(<I>widget-name '</I><B>tag 'prevrange </B><I>tagName index1 </I>)</A><DD>
|
|
|
|
|
<DT><A NAME="M141">(<I>widget-name '</I><B>tag 'prevrange </B><I>tagName index1 </I> <I>index2</I>)</A><DD>
|
|
|
|
|
This command searches the text for a range of characters tagged
|
|
|
|
|
with <I>tagName</I> where the first character of the range is
|
|
|
|
|
before the character at <I>index1</I> and no earlier than
|
|
|
|
|
the character at <I>index2</I> (a range starting at
|
|
|
|
|
<I>index2</I> will be considered).
|
|
|
|
|
If several matching ranges exist, the one closest to <I>index1</I> 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 <I>index2</I> is not given then it defaults to the beginning of the text.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M142">(<I>widget-name</I><B>'tag 'raise </B><I>tagName </I>)</A><DD>
|
|
|
|
|
<DT><A NAME="M143">(<I>widget-name</I><B>'tag 'raise </B><I>tagName </I> <I>aboveThis</I>)</A><DD>
|
|
|
|
|
Changes the priority of tag <I>tagName</I> so that it is just higher
|
|
|
|
|
in priority than the tag whose name is <I>aboveThis</I>.
|
|
|
|
|
If <I>aboveThis</I> is omitted, then <I>tagName</I>'s priority
|
|
|
|
|
is changed to make it highest priority of all tags.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M144">(<I>widget-name </I><B>'tag 'ranges </B><I>tagName</I>)</A><DD>
|
|
|
|
|
Returns a list describing all of the ranges of text that have been
|
|
|
|
|
tagged with <I>tagName</I>.
|
|
|
|
|
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 <I>tag</I> then an
|
|
|
|
|
empty list is returned.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M145">(<I>widget-name </I><B>'tag 'remove </B><I>tagName index1 </I>?<I>index2 index1 index2 ...</I>?)</A><DD>
|
|
|
|
|
Remove the tag <I>tagName</I> from all of the characters starting
|
|
|
|
|
at <I>index1</I> and ending just before
|
|
|
|
|
<I>index2</I> (the character at <I>index2</I> isn't affected).
|
|
|
|
|
A single procedure may contain any number of <I>index1</I>-<I>index2</I>
|
|
|
|
|
pairs.
|
|
|
|
|
If the last <I>index2</I> is omitted then the single character at
|
|
|
|
|
<I>index1</I> is tagged.
|
|
|
|
|
If there are no characters in the specified range (e.g. <I>index1</I>
|
|
|
|
|
is past the end of the file or <I>index2</I> is less than or equal
|
|
|
|
|
to <I>index1</I>) then the procedure has no effect.
|
|
|
|
|
This procedure returns an empty list.
|
|
|
|
|
<P>
|
|
|
|
|
</DL>
|
|
|
|
|
<DT><A NAME="M146">(<I>widget-name '</I><B>window </B><I>option </I>?<I>arg arg ...</I>?)</A><DD>
|
|
|
|
|
This procedure is used to manipulate embedded windows.
|
|
|
|
|
The behavior of the procedure depends on the <I>option</I> argument
|
|
|
|
|
that follows the <B>tag</B> argument.
|
|
|
|
|
The following forms of the procedure are currently supported:
|
|
|
|
|
<P>
|
|
|
|
|
<P>
|
|
|
|
|
<DL>
|
|
|
|
|
<DT><A NAME="M147">(<I>widget-name '</I><B>window 'cget</B> <I>index option</I>)</A><DD>
|
|
|
|
|
Returns the value of a configuration option for an embedded window.
|
|
|
|
|
<I>Index</I> identifies the embedded window, and <I>option</I>
|
|
|
|
|
specifies a particular configuration option, which must be one of
|
|
|
|
|
the ones listed in the section EMBEDDED WINDOWS.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M148">(<I>widget-name '</I><B>window 'configure </B><I>index</I> ?<I>option value ...</I>?)</A><DD>
|
|
|
|
|
Query or modify the configuration options for an embedded window.
|
|
|
|
|
If no <I>option</I> is specified, returns a list describing all of
|
|
|
|
|
the available options for the embedded window at <I>index</I>
|
|
|
|
|
(see <B>Tk_ConfigureInfo</B> for information on the format of this list).
|
|
|
|
|
If <I>option</I> is specified with no <I>value</I>, then the procedure
|
|
|
|
|
returns a list describing the one named option (this list will be
|
|
|
|
|
identical to the corresponding sublist of the value returned if no
|
|
|
|
|
<I>option</I> is specified).
|
|
|
|
|
If one or more <I>option-value</I> pairs are specified, then the procedure
|
|
|
|
|
modifies the given option(s) to have the given value(s); in
|
|
|
|
|
this case the procedure returns an empty list.
|
|
|
|
|
See EMBEDDED WINDOWS for information on the options that
|
|
|
|
|
are supported.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M149">(<I>widget-name '</I><B>window 'create </B><I>index</I> ?<I>option value ...</I>?)</A><DD>
|
|
|
|
|
This procedure creates a new window annotation, which will appear
|
|
|
|
|
in the text at the position given by <I>index</I>.
|
|
|
|
|
Any number of <I>option-value</I> pairs may be specified to
|
|
|
|
|
configure the annotation.
|
|
|
|
|
See EMBEDDED WINDOWS for information on the options that
|
|
|
|
|
are supported.
|
|
|
|
|
Returns an empty list.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M150">(<I>widget-name '</I><B>window 'names</B>)</A><DD>
|
|
|
|
|
Returns a list whose elements are the names of all windows currently
|
|
|
|
|
embedded in <I>window</I>.
|
|
|
|
|
<P>
|
|
|
|
|
</DL>
|
|
|
|
|
<DT><A NAME="M151">(<I>widget-name '</I><B>xview </B><I>option args</I>)</A><DD>
|
|
|
|
|
This procedure 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:
|
|
|
|
|
<P>
|
|
|
|
|
<P>
|
|
|
|
|
<DL>
|
|
|
|
|
<DT><A NAME="M152">(<I>widget-name '</I><B>xview</B>)</A><DD>
|
|
|
|
|
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 <B>:xscrollprocedure</B>
|
|
|
|
|
option.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M153">(<I>widget-name '</I><B>xview 'moveto</B><I> fraction</I>)</A><DD>
|
|
|
|
|
Adjusts the view in the window so that <I>fraction</I> of the horizontal
|
|
|
|
|
span of the text is off-screen to the left.
|
|
|
|
|
<I>Fraction</I> is a fraction between 0 and 1.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M154">(<I>widget-name '</I><B>xview 'scroll </B><I>number what</I>)</A><DD>
|
|
|
|
|
This procedure shifts the view in the window left or right according to
|
|
|
|
|
<I>number</I> and <I>what</I>.
|
|
|
|
|
<I>Number</I> must be an integer.
|
|
|
|
|
<I>What</I> must be either <B>units</B> or <B>pages</B> or an abbreviation
|
|
|
|
|
of one of these.
|
|
|
|
|
If <I>what</I> is <B>units</B>, the view adjusts left or right by
|
|
|
|
|
<I>number</I> average-width characters on the display; if it is
|
|
|
|
|
<B>pages</B> then the view adjusts by <I>number</I> screenfuls.
|
|
|
|
|
If <I>number</I> is negative then characters farther to the left
|
|
|
|
|
become visible; if it is positive then characters farther to the right
|
|
|
|
|
become visible.
|
|
|
|
|
<P>
|
|
|
|
|
</DL>
|
|
|
|
|
<DT><A NAME="M155">(<I>widget-name '</I><B>yview </B><I>?args</I>?)</A><DD>
|
|
|
|
|
This procedure 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:
|
|
|
|
|
<P>
|
|
|
|
|
<P>
|
|
|
|
|
<DL>
|
|
|
|
|
<DT><A NAME="M156">(<I>widget-name '</I><B>yview</B>)</A><DD>
|
|
|
|
|
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 <B>:yscrollprocedure</B>
|
|
|
|
|
option.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M157">(<I>widget-name '</I><B>yview 'moveto</B><I> fraction</I>)</A><DD>
|
|
|
|
|
Adjusts the view in the window so that the character given by <I>fraction</I>
|
|
|
|
|
appears on the top line of the window.
|
|
|
|
|
<I>Fraction</I> 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.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M158">(<I>widget-name '</I><B>yview 'scroll </B><I>number what</I>)</A><DD>
|
|
|
|
|
This procedure adjust the view in the window up or down according to
|
|
|
|
|
<I>number</I> and <I>what</I>.
|
|
|
|
|
<I>Number</I> must be an integer.
|
|
|
|
|
<I>What</I> must be either <B>units</B> or <B>pages</B>.
|
|
|
|
|
If <I>what</I> is <B>units</B>, the view adjusts up or down by
|
|
|
|
|
<I>number</I> lines on the display; if it is <B>pages</B> then
|
|
|
|
|
the view adjusts by <I>number</I> screenfuls.
|
|
|
|
|
If <I>number</I> is negative then earlier positions in the text
|
|
|
|
|
become visible; if it is positive then later positions in the text
|
|
|
|
|
become visible.
|
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M159">(<I>widget-name </I><B>yview </B> <I>index</I>)</A><DD>
|
|
|
|
|
<DT><A NAME="M160">(<I>widget-name </I><B>yview </B><B>:pickplace</B> <I>index</I>)</A><DD>
|
|
|
|
|
Changes the view in the widget's window to make <I>index</I> visible.
|
|
|
|
|
If the <B>:pickplace</B> option isn't specified then <I>index</I> will
|
|
|
|
|
appear at the top of the window.
|
|
|
|
|
If <B>:pickplace</B> is specified then the widget chooses where
|
|
|
|
|
<I>index</I> appears in the window:
|
|
|
|
|
<P>
|
|
|
|
|
<OL>
|
|
|
|
|
<LI>
|
|
|
|
|
If <I>index</I> is already visible somewhere in the window then the
|
|
|
|
|
procedure does nothing.
|
|
|
|
|
<LI>
|
|
|
|
|
If <I>index</I> is only a few lines off-screen above the window then
|
|
|
|
|
it will be positioned at the top of the window.
|
|
|
|
|
<LI>
|
|
|
|
|
If <I>index</I> is only a few lines off-screen below the window then
|
|
|
|
|
it will be positioned at the bottom of the window.
|
|
|
|
|
<LI>
|
|
|
|
|
Otherwise, <I>index</I> will be centered in the window.
|
|
|
|
|
</OL>
|
|
|
|
|
<UL>
|
|
|
|
|
<P>
|
|
|
|
|
The <B>:pickplace</B> option has been obsoleted by the <B>see</B> widget
|
|
|
|
|
procedure (<B>see</B> handles both x- and y-motion to make a location
|
|
|
|
|
visible, whereas <B>:pickplace</B> only handles motion in y).
|
|
|
|
|
</UL>
|
|
|
|
|
<DT><A NAME="M161">(<I>widget-name '</I><B>yview </B><I>number</I>)</A><DD>
|
|
|
|
|
This procedure makes the first character on the line after
|
|
|
|
|
the one given by <I>number</I> visible at the top of the window.
|
|
|
|
|
<I>Number</I> must be an integer.
|
|
|
|
|
This procedure used to be used for scrolling, but now it is obsolete.
|
|
|
|
|
<P>
|
|
|
|
|
</DL>
|
|
|
|
|
</DL>
|
|
|
|
|
<H3><A NAME="M162">BINDINGS</A></H3>
|
|
|
|
|
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.
|
|
|
|
|
<OL>
|
|
|
|
|
<LI>
|
|
|
|
|
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.
|
|
|
|
|
<LI>
|
|
|
|
|
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.
|
|
|
|
|
<LI>
|
|
|
|
|
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.
|
|
|
|
|
<LI>
|
|
|
|
|
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.
|
|
|
|
|
<LI>
|
|
|
|
|
Clicking mouse button 1 with the Control key down will reposition the
|
|
|
|
|
insertion cursor without affecting the selection.
|
|
|
|
|
<LI>
|
|
|
|
|
If any normal printing characters are typed, they are
|
|
|
|
|
inserted at the point of the insertion cursor.
|
|
|
|
|
<LI>
|
|
|
|
|
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.
|
|
|
|
|
<LI>
|
|
|
|
|
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).
|
|
|
|
|
<LI>
|
|
|
|
|
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.
|
|
|
|
|
<LI>
|
|
|
|
|
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.
|
|
|
|
|
<LI>
|
|
|
|
|
Control-Next and Control-Prior scroll the view right or left by one page
|
|
|
|
|
without moving the insertion cursor or affecting the selection.
|
|
|
|
|
<LI>
|
|
|
|
|
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.
|
|
|
|
|
<LI>
|
|
|
|
|
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.
|
|
|
|
|
<LI>
|
|
|
|
|
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.
|
|
|
|
|
<LI>
|
|
|
|
|
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.
|
|
|
|
|
<LI>
|
|
|
|
|
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.
|
|
|
|
|
<LI>
|
|
|
|
|
Control-/ selects the entire contents of the widget.
|
|
|
|
|
<LI>
|
|
|
|
|
Control-\ clears any selection in the widget.
|
|
|
|
|
<LI>
|
|
|
|
|
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.
|
|
|
|
|
<LI>
|
|
|
|
|
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.
|
|
|
|
|
<LI>
|
|
|
|
|
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.
|
|
|
|
|
<LI>
|
|
|
|
|
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.
|
|
|
|
|
<LI>
|
|
|
|
|
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.
|
|
|
|
|
<LI>
|
|
|
|
|
Control-d deletes the character to the right of the insertion cursor.
|
|
|
|
|
<LI>
|
|
|
|
|
Meta-d deletes the word to the right of the insertion cursor.
|
|
|
|
|
<LI>
|
|
|
|
|
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.
|
|
|
|
|
<LI>
|
|
|
|
|
Control-o opens a new line by inserting a newline character in
|
|
|
|
|
front of the insertion cursor without moving the insertion cursor.
|
|
|
|
|
<LI>
|
|
|
|
|
Meta-backspace and Meta-Delete delete the word to the left of the
|
|
|
|
|
insertion cursor.
|
|
|
|
|
<LI>
|
|
|
|
|
Control-x deletes whatever is selected in the text widget.
|
|
|
|
|
<LI>
|
|
|
|
|
Control-t reverses the order of the two characters to the right of
|
|
|
|
|
the insertion cursor.
|
|
|
|
|
</OL>
|
|
|
|
|
<P>
|
|
|
|
|
If the widget is disabled using the <B>:state</B> 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.
|
|
|
|
|
<P>
|
|
|
|
|
The behavior of texts can be changed by defining new bindings for
|
|
|
|
|
individual widgets or by redefining the class bindings.
|
|
|
|
|
|
|
|
|
|
<H3><A NAME="M163">PERFORMANCE ISSUES</A></H3>
|
|
|
|
|
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.
|
|
|
|
|
<P>
|
|
|
|
|
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.
|
|
|
|
|
<P>
|
|
|
|
|
Very long text lines can be expensive,
|
|
|
|
|
especially if they have many marks and tags within them.
|
|
|
|
|
<P>
|
|
|
|
|
The display line with the insert cursor is redrawn each time the
|
|
|
|
|
cursor blinks, which causes a steady stream of graphics traffic.
|
|
|
|
|
Set the <B>insertOffTime</B> attribute to 0 avoid this.
|
1998-04-10 06:59:06 -04:00
|
|
|
<P><IMG ALIGN=TOP SRC="./Img/line-red.gif"><P>
|
1996-09-27 06:29:02 -04:00
|
|
|
<A HREF=./STk-hlp.html><IMG ALIGN=BOTTOM SRC="./Img/RefBookBlue.gif"> Back to the <B>STk</B> main page</A>
|
|
|
|
|
</BODY></HTML>
|
