<!-- manual page source format generated by PolyglotMan v3.0.8+XFree86, -->
<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->
<HTML>
<HEAD>
<TITLE>htext(n) manual page</TITLE>
</HEAD>
<BODY BGCOLOR="#efefef" TEXT="black" LINK="blue" VLINK="#551A8B" ALINK="red">
<A HREF="#toc">Table of Contents</A><P>
<H2><A NAME="sect0" HREF="#toc0">Name</A></H2>
htext - Create and manipulate hypertext widgets
<H2><A NAME="sect1" HREF="#toc1">Synopsis</A></H2>
<B>htext</B> <I>pathName </I>?<I>option value</I>?...
<H2><A NAME="sect2" HREF="#toc2">Description</A></H2>
<P>
The <B>htext</B> command creates
a new window (given by the <I>pathName</I> argument) and makes it into a <B>htext</B>
widget. Additional options, described above, may be specified on the command
line or in the option database to configure aspects of the widget such
as its color and font. At the time this command is invoked, there must
not exist a window named <I>pathName</I>, but <I>pathName</I>'s parent must exist. The
<B>htext</B> command returns its <I>pathName</I>. <P>
The <B>htext</B> widget is hybrid of a non-editable
text widget and a geometry manager (e.g. the packer). It displays text (optionally
read from file) in a window. Text can be scrolled either horizontally or
vertically using the <B>htext</B> window as a viewport. In addition, Tcl commands
can be embedded into the text which are evaluated as the text is parsed.
Text between special double characters (percent signs "%%") is immediately
passed to the Tcl interpreter for evaluation. <P>
Furthermore, any widget
or widget hierarchy can be packed in-line and made to appear on the current
line of the text. Widgets are packed using the <B>htext append</B> command. All
widgets must be children of the <B>htext</B> window and must already exist before
packing. Once a widget has been packed it cannot be moved to a different
position within the text. Widgets can be resized but they will remain
at the same position within the text. <P>
Before a file or text string is parsed
by the <B>htext</B> widget, all the widget's current children are destroyed. You
can reload files or text without worrying about unmapping or destroying
each child window beforehand. <P>
Setting the either the <B>-filename</B> or <B>-text</B> configuration
option will adjust the value of the other. If both options are set, the
file takes precedence. When a new file is read using the <B>-filename</B> option,
the value of the <B>-text</B> option is reset to the empty string. Likewise, when
the <B>-text</B> option is set, the string representing the <B>-filename</B> option is
cleared.
<H2><A NAME="sect3" HREF="#toc3">File Format</A></H2>
The format of <B>htext</B> text file is typically ASCII text.
Text enclosed by special double characters (by default, percent signs
'%%') is interpreted and executed as Tcl commands. The special character
may be specified by the <B>-specialchar</B> option. In the following example of
a <B>htext</B> file, a button widget is appended to the text between the words
"<I>a</I>" and "<I>which</I>". The <I>pathName</I> of the <B>htext</B> widget is "<I>.ht</I>". <BR>
<CODE><I>This will be displayed as normal text. <BR>
</I>But this will become a %% <BR>
button .ht.button -text "button" -fg red<BR>
.ht append .ht.button <BR>
%% which can invoke a Tcl command.<BR>
<P>
<H2><A NAME="sect4" HREF="#toc4"></CODE><P>Indices</A></H2>
<P>
Some of the widget operations (<B>selection</B>, gotoline, <B>search</B>, etc.)
take one or more indices as arguments. An index is a string used to indicate
a particular place within the text, such as the first and last characters
in a range to be selected. <P>
An index must have one of the following forms:
<DL>
<DT><I>line<B>.<I>char</I></B></I> </DT>
<DD>Indicates <I>char</I>'th character on line <I>line</I>. Both lines and characters
are number from 0, so "0.0" is the first beginning of the text. <I>Char</I> may
be undesignated. In this case a character position of 0 is assumed. </DD>
<DT><B>@<I>x<B>,<I>y</I></B></I></B>
</DT>
<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>. </DD>
<DT><B>end</B> </DT>
<DD>Indicates the end of the text. </DD>
<DT><B>anchor</B>
</DT>
<DD>Indicates the anchor point for the selection, which is set with the <B>selection</B>
operation. </DD>
<DT><B>sel.first</B> </DT>
<DD>Indicates the first character in the selection. It is
an error to use this form if the selection isn't in the entry window. </DD>
<DT><B>sel.last</B>
</DT>
<DD>Indicates the character just after the last one in the selection. It is
an error to use this form if the selection isn't in the entry window. </DD>
</DL>
<H2><A NAME="sect5" HREF="#toc5">Variables</A></H2>
<P>
The
following global Tcl variables are maintained when an <B>htext</B> file is parsed.
<DL>
<DT><B>htext(widget)</B> </DT>
<DD>is the pathname of the <B>htext</B> widget. </DD>
<DT><B>htext(file)</B> </DT>
<DD>is the
name of the file the <B>htext</B> widget is currently parsing. It is the empty
string when the <B>-text</B> option is used. </DD>
<DT><B><A HREF="htext.l.html">htext(line)</B></A>
</DT>
<DD>is the current line number
in the text. </DD>
</DL>
<P>
This information might be used to construct hyper links
between different files and/or lines. <P>
<H2><A NAME="sect6" HREF="#toc6">Syntax</A></H2>
The <B>htext</B> command creates a
new Tcl command whose name is <I>pathName</I>. This command may be used to invoke
various operations on the widget. It has the following general form: <BR>
<P>
<CODE><I>pathName oper </I>?<I>args</I>?<BR>
</CODE><P><I>Oper</I> and <I>args</I> determine the exact behavior of the command. <P>
<H2><A NAME="sect7" HREF="#toc7">Operations</A></H2>
The
following operations are available for <B>htext</B> widgets:
<DL>
<DT><I>pathName <B>append <I>window
</I></B></I>?<I>option value</I>?... </DT>
<DD>Embeds the widget <I>window</I> into the htext widget. <I>Window</I>
is the pathname of the widget to be embedded which must be a child of <I>pathName</I>.
<I>Window</I> will be positioned in the htext widget at the current location
of the text. If <I>option</I> and <I>value</I> pairs are present, they configure various
aspects how <I>window</I> appears in <I>pathName</I>. The following options are available.
<blockquote></DD>
<DT><B>-anchor <I>anchorPos</I></B> </DT>
<DD>Specifies how <I>window</I> will be arranged if there is any
extra space in the cavity surrounding the window. For example, if <I>anchorPos</I>
is <B>center</B> then the window is centered in the cavity; if <I>anchorPos</I> is <B>w</B>
then the window will be drawn such it touches the leftmost edge of the
cavity. The default is <I>center</I>. </DD>
<DT><B>-fill <I>style</I></B> </DT>
<DD>Specifies how the <I>window</I> should
be stretched to occupy the extra space in the cavity surrounding it (if
any exists). <I>Style</I> is <I>none</I>, <I>x</I>, <I>y</I>, <I>both</I>. If <I>style</I> is <I>x</I>, the width of <I>window</I>
is expanded to fill the cavity. If <I>style</I> is <B>y</B>, the height is expanded.
The default is <I>none</I>. </DD>
<DT><B>-height <I>pixels</I></B> </DT>
<DD>Sets the height of the cavity surrounding
<I>window</I>. If <I>pixels</I> is zero, the height of the cavity will be the same as
the requested height of <I>window</I>. If <I>pixels</I> is less than the requested height
of <I>window</I>, <I>window</I> will be reduced to fit the cavity. The default is <I>0</I>. </DD>
<DT><B>-ipadx
<I>pad</I></B> </DT>
<DD>Sets the amount of internal padding to be added to the width <I>window</I>.
<I>Pad</I> can be a list of one or two numbers. If <I>pad</I> has two elements, the
left side of <I>window</I> is extended by the first value and the right side by
the second value. If <I>pad</I> is just one value, both the left and right sides
are padded by evenly by the value. The default is <I>0</I>. </DD>
<DT><B>-ipady <I>pad</I></B> </DT>
<DD>Sets an amount
of internal padding to be added to the height of <I>window</I>. <I>Pad</I> can be a list
of one or two numbers. If <I>pad</I> has two elements, the top of <I>window</I> is padded
by the first value and the bottom by the second value. If <I>pad</I> is just one
number, both the top and bottom are padded evenly by the value. The default
is <I>0</I>. </DD>
<DT><B>-justify <I>justify</I></B> </DT>
<DD>Justifies <I>window</I> vertically within the cavity containing
it in relation to the line of text. <I>Justify</I> is <B>top</B>, <B>bottom</B>, or <B>center</B>.
If <I>justify</I> is <I>center</I> the widget is centered along the baseline of the
line of text. The default is <I>center</I>. </DD>
<DT><B>-padx <I>pad</I></B> </DT>
<DD>Sets the padding on the left
and right sides of <I>window</I>. <I>Pad</I> can be a list of one or two numbers. If <I>pad</I>
has two elements, the left side of <I>window</I> is padded by the first value
and the right side by the second value. If <I>pad</I> has just one value, both
the left and right sides are padded evenly by the value. The default is
<I>0</I>. </DD>
<DT><B>-pady <I>pad</I></B> </DT>
<DD>Sets the padding above and below <I>window</I>. <I>Pad</I> can be a list of
one or two numbers. If <I>pad</I> has two elements, the area above <I>window</I> is padded
by the first value and the area below by the second value. If <I>pad</I> is just
one number, both the top and bottom are padded by the value. The default
is <I>0</I>. </DD>
<DT><B>-relheight <I>value</I></B> </DT>
<DD>Specifies the height of the cavity containing <I>window</I>
relative to the height of <I>pathName</I>. <I>Value</I> is real number indicating the
ratio of the height of the cavity to the height of <I>pathName</I>. As the height
of <I>pathName</I> changes, so will the height of <I>window</I>. If <I>value</I> is 0.0 or less,
the height of the cavity is the requested height <I>window</I>. The default is
<I>0.0</I>. </DD>
<DT><B>-relwidth <I>value</I></B> </DT>
<DD>Specifies the width of the cavity containing <I>window</I> relative
to the width of <I>pathName</I>. <I>Value</I> is real number indicating the ratio of
the width of the cavity to the width of IpathName. As the height of <I>pathName</I>
changes, so will the height of <I>window</I>. If <I>value</I> is 0.0 or less, the width
of the cavity is the requested width of <I>window</I>. The default is <I>0.0</I>. </DD>
<DT><B>-width
<I>value</I></B> </DT>
<DD>Species the width of the cavity containing the child window. <I>Value</I>
must be in a form accepted by <B>Tk_GetPixels</B>. If <I>value</I> is greater than zero,
the cavity is resized to that width. If the requested window width is
greater than the cavity's width, the window will be reduced to fit the cavity.
By default, the cavity is requested width of the child window. </DD>
</DL>
</blockquote>
<DL>
<DT><I>pathName
<B>configure</B></I> ?<I>window</I>? ?<I>option</I>? ?<I>value option value ...</I>? </DT>
<DD>Queries or modifies the
configuration options of the text widget or one of its embedded widgets.
If no <I>window</I> argument is present, the htext widget itself is configured.
Otherwise <I>window</I> is the pathname of a widget already embedded into the
htext widget. Then this command configure the options for the embedded widget.
</DD>
</DL>
<P>
If <I>option</I> isn't specified, a list describing all of the current options
for <I>pathName</I> or <I>window</I> is returned. If <I>option</I> is specified, but not <I>value</I>,
then a list describing the option <I>option</I> is returned. If one or more <I>option</I>
and <I>value</I> pairs are specified, then for each pair, the htext or embedded
window option <I>option</I> is set to <I>value</I>. <P>
The following options are valid for
the htext widget. <blockquote>
<DL>
<DT><B>-background</B> <I>color<I> </I></I></DT>
<DD>Sets the background of the htext widget
to <I>color</I>. This default is <I>white</I>. </DD>
<DT><B>-cursor</B> <I>cursor</I> </DT>
<DD>Specifies the cursor for
the htext widget. The default cursor is <I>pencil</I>. </DD>
<DT><B>-filename</B> <I>fileName</I> </DT>
<DD>Specifies
a <B>htext</B> file to be displayed in the window. If the value is the empty string,
the <B>-text</B> option is used instead. See the section <FONT SIZE=-1><B>FILE</B></FONT>
for a description
of the <B>htext</B> file format. </DD>
<DT><B>-font</B> <I>fontName</I> </DT>
<DD>Sets the font of the text in the
htext widget to <I>fontName</I>. The default is <I>*-Helvetica-Bold-R-Normal-*-12-120-*</I>. </DD>
<DT><B>-foreground</B>
<I>color</I> </DT>
<DD>Sets the foreground of the htext widget to <I>color</I>. This is the color
of the text. This default is <I>black</I>. </DD>
<DT><B>-height</B> <I>pixels</I> </DT>
<DD>Specifies the height of
the htext widget window. </DD>
<DT><B>-linespacing</B> <I>pixels</I> </DT>
<DD>Specifies the spacing between
each line of text. The value must be in a form accepted by <B>Tk_GetPixels</B>.
The default value is 1 pixel. </DD>
<DT><B>-specialchar</B> <I>number</I> </DT>
<DD>Specifies the ASCII value
of the special double character delimiters. In <B>htext</B> files, the text between
these special characters is evaluated as a block of Tcl commands. The default
special character is the <I>0x25</I> (percent sign). </DD>
<DT><B>-text</B> <I>text</I> </DT>
<DD>Specifies the
text to be displayed in the htext widget. <I>Text</I> can be any valid string
of characters. See <FONT SIZE=-1><B>FILE FORMAT</B></FONT>
for a description. </DD>
<DT><B>-xscrollcommand</B> <I>string</I>
</DT>
<DD>Specifies the prefix for a command used to communicate with horizontal
scrollbars. When the view in the htext widget's window changes (or whenever
anything else occurs that could change the display in a scrollbar, such
as a change in the total size of the widget's contents), the widget invoke
<I>string</I> concatenated by two numbers. Each of the numbers is a fraction between
0 and 1, which indicates a position in the document. If this option is
not specified, then no command will be executed. </DD>
<DT><B>-yscrollcommand</B> <I>string</I> </DT>
<DD>Specifies
the prefix for a command used to communicate with vertical scrollbars.
When the view in the htext widget's window changes (or whenever anything
else occurs that could change the display in a scrollbar, such as a change
in the total size of the widget's contents), the widget invoke <I>string</I> concatenated
by two numbers. Each of the numbers is a fraction between 0 and 1, which
indicates a position in the document. If this option is not specified,
then no command will be executed. </DD>
<DT><B>-width</B> <I>pixels</I> </DT>
<DD>Specifies the desired width
of the viewport window. If the <I>pixels</I> is less than one, the window will
grow to accommodate the widest line of text. </DD>
<DT><B>-xscrollunits</B> <I>pixels</I> </DT>
<DD>Specifies
the horizontal scrolling distance. The default is 10 pixels. </DD>
<DT><B>-yscrollunits</B>
<I>pixels</I> </DT>
<DD>Specifies the vertical scrolling distance. The default is 10 pixels.
</DD>
</DL>
</blockquote>
<DL>
<DT><I>pathName <B>gotoline </B></I>?<I>index</I>? </DT>
<DD>Sets the top line of the text to <I>index</I>. <I>Index</I>
must be a valid text index (the character offset is ignored). If an <I>index</I>
isn't provided, the current line number is returned. </DD>
<DT><I>pathName <B>scan mark
<I>position</I></B></I> </DT>
<DD>Records <I>position</I> and the current view in the text window; used
in conjunction with later <B>scan dragto</B> commands. <I>Position</I> must be in the
form "<I>@x,y</I>, where <I>x</I> and <I>y</I> are window coordinates. Typically this command
is associated with a mouse button press in the widget. It returns an empty
string. </DD>
<DT><I>pathName <B>scan dragto <I>position</I></B></I> </DT>
<DD>Computes the difference between <I>position</I>
and the position registered in the last <B>scan mark</B> command for the widget.
The view is then adjusted up or down by 10 times the difference in coordinates.
This command is can be associated with mouse motion events to produce
the effect of dragging the text at high speed through the window. <I>Position</I>
must be in the form "<I>@x,y</I>, where <I>x</I> and <I>y</I> are window coordinates. The command
returns an empty string. </DD>
<DT><I>pathName <B>search <I>pattern</I></B></I> ?<I>from</I>? ?<I>to</I>? </DT>
<DD>Returns the
number of the next line matching <I>pattern</I>. <I>Pattern</I> is a string which obeys
the matching rules of <B>Tcl_StringMatch</B>. <I>From</I> and <I>to</I> are text line numbers
(inclusive) which bound the search. If no match for <I>pattern</I> can be found,
<B>-1</B> is returned. </DD>
<DT><I>pathName <B>xview </B></I>?<I>position</I>? </DT>
<DD>Moves the viewport horizontally
to the new text x-coordinate position. <I>Position</I> is the offset from the
left side of the text to the current position and must be in a form accepted
by <B>Tk_GetPixels</B>. If <I>position</I> is not present, the current text position is
returned. </DD>
<DT><I>pathName <B>yview </B></I>?<I>position</I>? </DT>
<DD>Moves the viewport vertically to the
new text y-coordinate position. <I>Position</I> is the offset from the top of
the text to the current position and must be in a form accepted by <B>Tk_GetPixels</B>.
If <I>position</I> is not present, the current text position is returned. </DD>
</DL>
<H2><A NAME="sect8" HREF="#toc8">Bugs</A></H2>
Text
with embedded tabs can be obscured by child windows when scrolled horizontally.
<H2><A NAME="sect9" HREF="#toc9">Keywords</A></H2>
hypertext, widget <P>
<HR><P>
<A NAME="toc"><B>Table of Contents</B></A><P>
<UL>
<LI><A NAME="toc0" HREF="#sect0">Name</A></LI>
<LI><A NAME="toc1" HREF="#sect1">Synopsis</A></LI>
<LI><A NAME="toc2" HREF="#sect2">Description</A></LI>
<LI><A NAME="toc3" HREF="#sect3">File Format</A></LI>
<LI><A NAME="toc4" HREF="#sect4">Indices</A></LI>
<LI><A NAME="toc5" HREF="#sect5">Variables</A></LI>
<LI><A NAME="toc6" HREF="#sect6">Syntax</A></LI>
<LI><A NAME="toc7" HREF="#sect7">Operations</A></LI>
<LI><A NAME="toc8" HREF="#sect8">Bugs</A></LI>
<LI><A NAME="toc9" HREF="#sect9">Keywords</A></LI>
</UL>
</BODY></HTML>
