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.
|
1998-04-30 07:04:33 -04:00
|
|
|
|
Text widgets support four different kinds of annotations on the
|
|
|
|
|
text, called tags, marks, embedded windows or embedded images.
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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.
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<P>
|
|
|
|
|
The fourth form of annotation allows Tk images to be embedded in a text
|
|
|
|
|
widget.
|
|
|
|
|
See EMBEDDED IMAGES below for more details.
|
1996-09-27 06:29:02 -04:00
|
|
|
|
|
|
|
|
|
<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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M47">.VS</A><DD>
|
|
|
|
|
<I>imageName</I>
|
|
|
|
|
Indicates the position of the embedded image whose name is
|
|
|
|
|
<I>imageName</I>.
|
|
|
|
|
This form generates an error if there is no embedded image
|
|
|
|
|
by the given name.
|
|
|
|
|
<P>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
</DL>
|
|
|
|
|
<P>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
If the <I>base</I> could match more than one of the above forms, such
|
|
|
|
|
as a <I>mark</I> and <I>imageName</I> both having the same value, then
|
|
|
|
|
the form earlier in the above list takes precedence.
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M48"><B>+ </B><I>count</I><B> chars</B></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M49"><B>: </B><I>count</I><B> chars</B></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M50"><B>+ </B><I>count</I><B> lines</B></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M51"><B>- </B><I>count</I><B> lines</B></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M52"><B>linestart</B></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
Adjust the index to refer to the first character on the line.
|
|
|
|
|
<P>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M53"><B>lineend</B></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
Adjust the index to refer to the last character on the line (the newline).
|
|
|
|
|
<P>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M54"><B>wordstart</B></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M55"><B>wordend</B></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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.
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<H3><A NAME="M56">TAGS</A></H3>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M57"><B>:background </B><I>color</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
<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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M58"><B>:bgstipple </B><I>bitmap</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
<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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M59"><B>:borderwidth </B><I>pixels</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
<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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M60"><B>:fgstipple </B><I>bitmap</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
<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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M61"><B>:font </B><I>fontName</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
<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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M62"><B>:foreground </B><I>color</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
<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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M63"><B>:justify </B><I>justify</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M64"><B>:lmargin1 </B><I>pixels</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M65"><B>:lmargin2 </B><I>pixels</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M66"><B>:offset </B><I>pixels</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
<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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M67"><B>:overstrike </B><I>boolean</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M68"><B>:relief </B><I>relief</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
<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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M69"><B>:rmargin </B><I>pixels</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M70"><B>:spacing1 </B><I>pixels</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
<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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M71"><B>:spacing2 </B><I>pixels</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M72"><B>:spacing3 </B><I>pixels</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
<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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M73"><B>:tabs </B><I>tabList</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
<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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M74"><B>:underline </B><I>boolean</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
<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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M75"><B>:wrap </B><I>mode</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
<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.
|
|
|
|
|
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<H3><A NAME="M76">MARKS</A></H3>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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.
|
|
|
|
|
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<H3><A NAME="M77">EMBEDDED WINDOWS</A></H3>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M78"><B>:align </B><I>where</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M79"><B>:create </B><I>procedure</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M80"><B>:padx </B><I>pixels</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
<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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M81"><B>:pady </B><I>pixels</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
<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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M82"><B>:stretch </B><I>boolean</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<DT><A NAME="M83"><B>:window </B><I>widget-name</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
Specifies the window to display in the annotation.
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
</DL>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<H3><A NAME="M84">EMBEDDED IMAGES</A></H3>
|
|
|
|
|
The final form of annotation in text widgets is an embedded image.
|
|
|
|
|
Each embedded image annotation causes an image to be displayed
|
|
|
|
|
at a particular point in the text.
|
|
|
|
|
There may be any number of embedded images in a text widget,
|
|
|
|
|
and a particular image may be embedded in multiple places in the same
|
|
|
|
|
text widget.
|
|
|
|
|
The embedded image's position on the screen will be updated as the
|
|
|
|
|
text is modified or scrolled.
|
|
|
|
|
Each embedded image occupies one character's worth of index space
|
|
|
|
|
in the text widget, and it may be referred to either by
|
|
|
|
|
its position in the widget's index space, or the name it is assigned
|
|
|
|
|
when the image is inserted into the text widget widh <B><A HREF=../Help/./image.n.html>image create</A></B>.
|
|
|
|
|
If the range of text containing the embedded image is deleted then
|
|
|
|
|
that copy of the image is removed from the screen.
|
|
|
|
|
<P>
|
|
|
|
|
When an embedded image is added to a text widget with the <B>image
|
|
|
|
|
create</B> widget command, a name unique to this instance of the image
|
|
|
|
|
is returned. This name may then be used to refer to this image
|
|
|
|
|
instance. The name is taken to be the value of the <B>:name</B> option
|
|
|
|
|
(described below). If the <B>:name</B> option is not provided, the
|
|
|
|
|
<B>:image</B> name is used instead. If the <I>imageName</I> is already
|
|
|
|
|
in use in the text widget, then <B>#</B><I>nn</I> is added to the end of the
|
|
|
|
|
<I>imageName</I>, where <I>nn</I> is an arbitrary integer. This insures
|
|
|
|
|
the <I>imageName</I> is unique.
|
|
|
|
|
Once this name is assigned to this instance of the image, it does not
|
|
|
|
|
change, even though the <B>:image</B> or <B>:name</B> values can be changed
|
|
|
|
|
with <B><A HREF=../Help/./image.n.html>image configure</A></B>.
|
|
|
|
|
<P>
|
|
|
|
|
When an embedded image is added to a text widget with the
|
|
|
|
|
<B><A HREF=../Help/./image.n.html>image create</A></B> widget command, several configuration
|
|
|
|
|
options may be associated with it.
|
|
|
|
|
These options may be modified later with the <B><A HREF=../Help/./image.n.html>image configure</A></B>
|
|
|
|
|
widget command.
|
|
|
|
|
The following options are currently supported:
|
|
|
|
|
<P>
|
|
|
|
|
<DL>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M85">{B:align} {IwhereR}</A><DD>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
If the image is not as tall as the line in which it is displayed,
|
|
|
|
|
this option determines where the image is displayed in the line.
|
|
|
|
|
<I>Where</I> must have one of the values <B>top</B> (align the top of the image
|
|
|
|
|
with the top of the line), <B>center</B> (center the image
|
|
|
|
|
within the range of the line), <B>bottom</B> (align the bottom of the
|
|
|
|
|
image with the bottom of the line's area),
|
|
|
|
|
or <B>baseline</B> (align the bottom of the image with the baseline
|
|
|
|
|
of the line).
|
|
|
|
|
<P>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M86">{B:image} {IimageR}</A><DD>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
Specifies the name of the Tk image to display in the annotation.
|
|
|
|
|
If <I>image</I> is not a valid Tk image, then an error is returned.
|
|
|
|
|
<P>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M87">{B:name} {IImageNameR}</A><DD>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
Specifies the name by which this image instance may be referenced in
|
|
|
|
|
the text widget. If <I>ImageName</I> is not supplied, then the
|
|
|
|
|
name of the Tk image is used instead.
|
|
|
|
|
If the <I>imageName</I> is already in use, <I>#nn</I> is appended to
|
|
|
|
|
the end of the name as described above.
|
|
|
|
|
<P>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M88">{B:padx} {IpixelsR}</A><DD>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<I>Pixels</I> specifies the amount of extra space to leave on
|
|
|
|
|
each side of the embedded image.
|
|
|
|
|
It may have any of the usual forms defined for a screen distance.
|
|
|
|
|
<P>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M89">{B:pady} {IpixelsR}</A><DD>
|
1998-04-30 07:04:33 -04:00
|
|
|
|
<I>Pixels</I> specifies the amount of extra space to leave on
|
|
|
|
|
the top and on the bottom of the embedded image.
|
|
|
|
|
It may have any of the usual forms defined for a screen distance.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
</DL>
|
|
|
|
|
<H3><A NAME="M90">THE SELECTION</A></H3>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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:
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<P>
|
|
|
|
|
<DL>
|
|
|
|
|
<DT><A NAME="M91">{[1]}</A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
Whenever characters are tagged with <B>sel</B> the text widget
|
|
|
|
|
will claim ownership of the selection.
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M92">{[2]}</A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
Attempts to retrieve the
|
|
|
|
|
selection will be serviced by the text widget, returning all the
|
|
|
|
|
characters with the <B>sel</B> tag.
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<P>
|
|
|
|
|
<DT><A NAME="M93">{[3]}</A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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.
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<P>
|
|
|
|
|
</DL>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
<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.
|
|
|
|
|
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<H3><A NAME="M94">THE INSERTION CURSOR</A></H3>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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.
|
|
|
|
|
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<H3><A NAME="M95">WIDGET PROCEDURE</A></H3>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M96">(<I>widget-name '</I><B>bbox </B><I>index</I>)</A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M97">(<I>widget-name '</I><B>cget</B> <I>option</I>)</A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M98">(<I>widget-name '</I><B>compare</B> <I>index1 op index2</I>)</A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M99">(<I>widget-name '</I><B>configure</B> ?<I>option</I>? <I>?value option value ...</I>?)</A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M100">(<I>widget-name '</I><B>debug </B>)</A><DD>
|
|
|
|
|
<DT><A NAME="M101">(<I>widget-name '</I><B>debug </B><I>boolean</I>)</A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M102">(<I>widget-name '</I><B>delete </B><I>index1 </I>)</A><DD>
|
|
|
|
|
<DT><A NAME="M103">(<I>widget-name '</I><B>delete </B><I>index1 </I><I>index2</I>)</A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M104">(<I>widget-name '</I><B>dlineinfo </B><I>index</I>)</A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M105">(<I>widget-name </I><B>'dump </B>?<I>switches</I>? <I>index1 </I>?<I>index2</I>?)</A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M106"><B>:all</B></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
Return information about all elements: text, marks, tags, and windows.
|
|
|
|
|
This is the default.
|
|
|
|
|
<P>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M107"><B>:command </B><I>closure</I></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M108"><B>:mark</B></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
Include information about marks in the dump results.
|
|
|
|
|
<P>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M109"><B>:tag</B></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M110"><B>:text</B></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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>
|
1998-09-30 07:11:02 -04:00
|
|
|
|
<DT><A NAME="M111"><B>:window</B></A><DD>
|
1996-09-27 06:29:02 -04:00
|
|
|
|
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 info |