1717 lines
80 KiB
HTML
1717 lines
80 KiB
HTML
<HTML><HEAD><TITLE>Tk Built-In Commands - text manual page</TITLE></HEAD>
|
||
<BR>
|
||
<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 four different kinds of annotations on the
|
||
text, called tags, marks, embedded windows or embedded images.
|
||
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.
|
||
<P>
|
||
The fourth form of annotation allows Tk images to be embedded in a text
|
||
widget.
|
||
See EMBEDDED IMAGES 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>
|
||
<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>
|
||
</DL>
|
||
<P>
|
||
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.
|
||
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="M48"><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="M49"><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="M50"><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="M51"><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="M52"><B>linestart</B></A><DD>
|
||
Adjust the index to refer to the first character on the line.
|
||
<P>
|
||
<DT><A NAME="M53"><B>lineend</B></A><DD>
|
||
Adjust the index to refer to the last character on the line (the newline).
|
||
<P>
|
||
<DT><A NAME="M54"><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="M55"><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="M56">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
|
||
<B>background</B>, <B><A HREF="./font.n.html">font</A></B>, and <B>foreground</B> options for the
|
||
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="M57"><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="M58"><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="M59"><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="M60"><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="M61"><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="M62"><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="M63"><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="M64"><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="M65"><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="M66"><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="M67"><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="M68"><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="M69"><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="M70"><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="M71"><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="M72"><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="M73"><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="M74"><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="M75"><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="M76">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="M77">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="M78"><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="M79"><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="M80"><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="M81"><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="M82"><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="M83"><B>:window </B><I>widget-name</I></A><DD>
|
||
Specifies the window to display in the annotation.
|
||
|
||
<P>
|
||
</DL>
|
||
<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>
|
||
<DT><A NAME="M85">{ B:align} { Iwhere R}</A><DD>
|
||
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>
|
||
<DT><A NAME="M86">{ B:image} { Iimage R}</A><DD>
|
||
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>
|
||
<DT><A NAME="M87">{ B:name} { IImageName R}</A><DD>
|
||
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>
|
||
<DT><A NAME="M88">{ B:padx} { Ipixels R}</A><DD>
|
||
<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>
|
||
<DT><A NAME="M89">{ B:pady} { Ipixels R}</A><DD>
|
||
<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>
|
||
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:
|
||
<P>
|
||
<DL>
|
||
<DT><A NAME="M91">{[1]}</A><DD>
|
||
Whenever characters are tagged with <B>sel</B> the text widget
|
||
will claim ownership of the selection.
|
||
<P>
|
||
<DT><A NAME="M92">{[2]}</A><DD>
|
||
Attempts to retrieve the
|
||
selection will be serviced by the text widget, returning all the
|
||
characters with the <B>sel</B> tag.
|
||
<P>
|
||
<DT><A NAME="M93">{[3]}</A><DD>
|
||
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.
|
||
<P>
|
||
</DL>
|
||
<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="M94">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="M95">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="M96">(<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="M97">(<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="M98">(<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="M99">(<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="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>
|
||
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="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>
|
||
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="M104">(<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="M105">(<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="M106"><B>:all</B></A><DD>
|
||
Return information about all elements: text, marks, tags, and windows.
|
||
This is the default.
|
||
<P>
|
||
<DT><A NAME="M107"><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="M108"><B>:mark</B></A><DD>
|
||
Include information about marks in the dump results.
|
||
<P>
|
||
<DT><A NAME="M109"><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="M110"><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="M111"><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="M112">(<I>widget-name </I><B>'get </B><I>index1 </I>)</A><DD>
|
||
<DT><A NAME="M113">(<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="M114">(<I>widget-name </I><B>'image </B><I>option </I>?<I>arg arg ...</I>?)</A><DD>
|
||
This command is used to manipulate embedded images.
|
||
The behavior of the command depends on the <I>option</I> argument
|
||
that follows the <B>tag</B> argument.
|
||
The following forms of the command are currently supported:
|
||
<P>
|
||
<P>
|
||
<DL>
|
||
<DT><A NAME="M115">(<I>widget-name </I><B>'image 'cget</B> <I>index option</I>)</A><DD>
|
||
Returns the value of a configuration option for an embedded image.
|
||
<I>Index</I> identifies the embedded image, and <I>option</I>
|
||
specifies a particular configuration option, which must be one of
|
||
the ones listed in the section EMBEDDED IMAGES.
|
||
<P>
|
||
<DT><A NAME="M116">(<I>widget-name </I><B>'image 'configure </B><I>index</I> ?<I>option value ...</I>?)</A><DD>
|
||
Query or modify the configuration options for an embedded image.
|
||
If no <I>option</I> is specified, returns a list describing all of
|
||
the available options for the embedded image 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 command
|
||
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 command
|
||
modifies the given option(s) to have the given value(s); in
|
||
this case the command returns an empty string.
|
||
See EMBEDDED IMAGES for information on the options that
|
||
are supported.
|
||
<P>
|
||
<DT><A NAME="M117">(<I>Widget-name </I><B>'image 'create </B><I>index</I> ?<I>option value ...</I>?)</A><DD>
|
||
This command creates a new image 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.
|
||
Returns a unique identifier that may be used as an index to refer to
|
||
this image.
|
||
See EMBEDDED IMAGES for information on the options that
|
||
are supported, and a description of the identifier returned.
|
||
<P>
|
||
<DT><A NAME="M118">(<I>Widget-name </I><B>'image 'names</B>)</A><DD>
|
||
Returns a list whose elements are the names of all image instances currently
|
||
embedded in <I>window</I>.
|
||
<P>
|
||
</DL>
|
||
<DT><A NAME="M119">(<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="M120">(<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="M121">(<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="M122">(<I>widget-name '</I><B>mark 'gravity </B><I>markName</I>)</A><DD>
|
||
<DT><A NAME="M123">(<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="M124">(<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="M125">(<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</B> index,
|
||
then it appears to be <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="M126">(<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="M127">(<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="M128">(<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="M129">(<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="M130">(<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="M131">(<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="M132">(<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="M133"><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="M134"><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="M135"><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="M136"><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="M137"><B>:nocase</B></A><DD>
|
||
Ignore case differences between the pattern and the text.
|
||
<P>
|
||
<DT><A NAME="M138"><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="M139"><B>:environment</B><I> env</I></A><DD>
|
||
The argument following <B>:environment</B> gives the definition environment of the variable counting matches (i.e. the one given to the <B>:count</B> option).
|
||
<B>:-</B>
|
||
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="M140">(<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="M141">(<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="M142">(<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="M143">(<I>widget-name </I><B>'tag 'bind </B><I>tagName</I>)</A><DD>
|
||
<DT><A NAME="M144">(<I>widget-name </I><B>'tag 'bind </B><I>tagName</I> <I>sequence</I>)</A><DD>
|
||
<DT><A NAME="M145">(<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>) or virtual events.
|
||
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. If a virtual event is used in a binding, that
|
||
binding can trigger only if the virtual event is defined by an underlying
|
||
mouse-related or keyboard-related event.
|
||
<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="M146">(<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="M147">(<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="M148">(<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="M149">(<I>widget-name</I><B>'tag 'lower </B><I>tagName </I>)</A><DD>
|
||
<DT><A NAME="M150">(<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="M151">(<I>widget-name </I><B>'tag 'names </B>)</A><DD>
|
||
<DT><A NAME="M152">(<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="M153">(<I>widget-name </I><B>'tag 'nextrange </B><I>tagName index1 </I>)</A><DD>
|
||
<DT><A NAME="M154">(<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="M155">(<I>widget-name '</I><B>tag 'prevrange </B><I>tagName index1 </I>)</A><DD>
|
||
<DT><A NAME="M156">(<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="M157">(<I>widget-name</I><B>'tag 'raise </B><I>tagName </I>)</A><DD>
|
||
<DT><A NAME="M158">(<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="M159">(<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="M160">(<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="M161">(<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="M162">(<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="M163">(<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="M164">(<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="M165">(<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="M166">(<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="M167">(<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="M168">(<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="M169">(<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="M170">(<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="M171">(<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="M172">(<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="M173">(<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="M174">(<I>widget-name </I><B>yview </B> <I>index</I>)</A><DD>
|
||
<DT><A NAME="M175">(<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>
|
||
<P>
|
||
<DL>
|
||
<DT><A NAME="M176">{[1]}</A><DD>
|
||
If <I>index</I> is already visible somewhere in the window then the
|
||
procedure does nothing.
|
||
<P>
|
||
<DT><A NAME="M177">{[2]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M178">{[3]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M179">{[4]}</A><DD>
|
||
Otherwise, <I>index</I> will be centered in the window.
|
||
<P>
|
||
</DL>
|
||
<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="M180">(<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="M181">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.
|
||
<P>
|
||
<DL>
|
||
<DT><A NAME="M182">{[1]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M183">{[2]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M184">{[3]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M185">{[4]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M186">{[5]}</A><DD>
|
||
Clicking mouse button 1 with the Control key down will reposition the
|
||
insertion cursor without affecting the selection.
|
||
<P>
|
||
<DT><A NAME="M187">{[6]}</A><DD>
|
||
If any normal printing characters are typed, they are
|
||
inserted at the point of the insertion cursor.
|
||
<P>
|
||
<DT><A NAME="M188">{[7]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M189">{[8]}</A><DD>
|
||
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).
|
||
<P>
|
||
<DT><A NAME="M190">{[9]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M191">{[10]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M192">{[11]}</A><DD>
|
||
Control-Next and Control-Prior scroll the view right or left by one page
|
||
without moving the insertion cursor or affecting the selection.
|
||
<P>
|
||
<DT><A NAME="M193">{[12]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M194">{[13]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M195">{[14]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M196">{[15]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M197">{[16]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M198">{[17]}</A><DD>
|
||
Control-/ selects the entire contents of the widget.
|
||
<P>
|
||
<DT><A NAME="M199">{[18]}</A><DD>
|
||
Control-\ clears any selection in the widget.
|
||
<P>
|
||
<DT><A NAME="M200">{[19]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M201">{[20]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M202">{[21]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M203">{[22]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M204">{[23]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M205">{[24]}</A><DD>
|
||
Control-d deletes the character to the right of the insertion cursor.
|
||
<P>
|
||
<DT><A NAME="M206">{[25]}</A><DD>
|
||
Meta-d deletes the word to the right of the insertion cursor.
|
||
<P>
|
||
<DT><A NAME="M207">{[26]}</A><DD>
|
||
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.
|
||
<P>
|
||
<DT><A NAME="M208">{[27]}</A><DD>
|
||
Control-o opens a new line by inserting a newline character in
|
||
front of the insertion cursor without moving the insertion cursor.
|
||
<P>
|
||
<DT><A NAME="M209">{[28]}</A><DD>
|
||
Meta-backspace and Meta-Delete delete the word to the left of the
|
||
insertion cursor.
|
||
<P>
|
||
<DT><A NAME="M210">{[29]}</A><DD>
|
||
Control-x deletes whatever is selected in the text widget.
|
||
<P>
|
||
<DT><A NAME="M211">{[30]}</A><DD>
|
||
Control-t reverses the order of the two characters to the right of
|
||
the insertion cursor.
|
||
<P>
|
||
</DL>
|
||
<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="M212">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.
|
||
<P><IMG ALIGN=TOP SRC="./Img/line-red.gif"><P>
|
||
<A HREF=./STk-hlp.html><IMG ALIGN=BOTTOM SRC="./Img/RefBookBlue.gif"> Back to the <B>STk</B> main page</A>
|
||
</BODY></HTML>
|