#toc
Table of Contents
#toc0
Name
htext - Create and manipulate hypertext widgets
#toc1
Synopsis
htext
pathName
?
option value
?...
#toc2
Description
The
htext
command creates
a new window (given by the
pathName
argument) and makes it into a
htext
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
pathName
, but
pathName
's parent must exist. The
htext
command returns its
pathName
.
The
htext
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
htext
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.
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
htext append
command.  All
widgets must be children of the
htext
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.
Before a file or text string is parsed
by the
htext
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.
Setting the either the
-filename
or
-text
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
-filename
option,
the value of the
-text
option is reset to the empty string.  Likewise,  when
the
-text
option is set, the string representing the
-filename
option is
cleared.
#toc3
File Format
The format of
htext
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
-specialchar
option.  In the following example of
a
htext
file,  a button widget  is appended to the text between  the words
"
a
" and "
which
".   The
pathName
of the
htext
widget is "
.ht
".
This will be displayed as normal text.
But this will become a %%
button .ht.button -text "button" -fg red
.ht append .ht.button
%% which can invoke a Tcl command.
#toc4
Indices
Some of the widget operations (
selection
, gotoline,
search
, 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.
An index must have one of the following forms:
line
.
char
Indicates
char
'th character on line
line
. Both lines and characters
are number from 0, so "0.0" is the first beginning of the text.
Char
may
be undesignated.  In this case a character position of 0 is assumed.
@
x
,
y
Indicates the character that covers the pixel whose x and y coordinates
within the text's window are
x
and
y
.
end
Indicates the end of the text.
anchor
Indicates the anchor point for the selection, which is set with the
selection
operation.
sel.first
Indicates the first character in the selection.  It is
an error to use this form if the selection isn't in the entry window.
sel.last
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.
#toc5
Variables
The
following global Tcl variables are maintained when an
htext
file is parsed.
htext(widget)
is the pathname of the
htext
widget.
htext(file)
is the
name of the file the
htext
widget is currently parsing.   It is the empty
string when the
-text
option is used.
htext.l.html
htext(line)
is the current line number
in the text.
This information might be used to construct hyper links
between different files and/or lines.
#toc6
Syntax
The
htext
command creates a
new Tcl command whose name is
pathName
.  This command may be used to invoke
various operations on the widget.  It has the following general form:
pathName oper
?
args
?
Oper
and
args
determine the exact behavior of the command.
#toc7
Operations
The
following operations are available for
htext
widgets:
pathName
append
window
?
option value
?...
Embeds the widget
window
into the htext widget.
Window
is the pathname of the widget to be embedded which must be a child of
pathName
.
Window
will be positioned in the htext widget at the current location
of the text. If
option
and
value
pairs are present, they configure various
aspects how
window
appears in
pathName
.  The following options are available.
-anchor
anchorPos
Specifies how
window
will be arranged if there is any
extra space in the cavity surrounding the window.  For example, if
anchorPos
is
center
then the window is centered in the cavity; if
anchorPos
is
w
then the window will be drawn such it touches the leftmost edge of the
cavity. The default is
center
.
-fill
style
Specifies how the
window
should
be stretched to occupy the extra space in the cavity surrounding it (if
any exists).
Style
is
none
,
x
,
y
,
both
.  If
style
is
x
, the width of
window
is expanded to fill the cavity.  If
style
is
y
, the height is expanded.
The default is
none
.
-height
pixels
Sets the height of the cavity surrounding
window
.  If
pixels
is zero, the height of the cavity will be the same as
the requested height of
window
.  If
pixels
is less than the  requested height
of
window
,
window
will be reduced to fit the cavity.  The default is
0
.
-ipadx
pad
Sets the amount of internal padding to be added to the width
window
.
Pad
can be a list of one or two numbers.  If
pad
has two elements, the
left side of
window
is extended by the first value and the right side by
the second value.  If
pad
is just one value, both the left and right sides
are padded by evenly by the value.  The default is
0
.
-ipady
pad
Sets an amount
of internal padding to be added to the height of
window
.
Pad
can be a list
of one or two numbers.  If
pad
has two elements, the top of
window
is padded
by the first value and the bottom by the second value.  If
pad
is just one
number, both the top and bottom are padded evenly by the value. The default
is
0
.
-justify
justify
Justifies
window
vertically within the cavity containing
it in relation to the line of text.
Justify
is
top
,
bottom
, or
center
.
If
justify
is
center
the widget is centered along the baseline of the
line of text.  The  default is
center
.
-padx
pad
Sets the padding on the left
and right sides of
window
.
Pad
can be a list of one or two numbers.  If
pad
has two elements, the left side of
window
is padded by the first value
and the right side by the second value.  If
pad
has just one value, both
the left and right sides are padded evenly by the value. The default is
0
.
-pady
pad
Sets the padding above and below
window
.
Pad
can be a list of
one or two numbers.  If
pad
has two elements, the area above
window
is padded
by the first value and the area below by the second value.  If
pad
is just
one number, both the top and bottom are padded by the value.  The default
is
0
.
-relheight
value
Specifies the height of the cavity containing
window
relative to  the height of
pathName
.
Value
is real number indicating the
ratio of the height of the cavity to the height of
pathName
.   As the height
of
pathName
changes, so will the height of
window
. If
value
is 0.0 or less,
the height of the cavity is the requested  height
window
.  The default is
0.0
.
-relwidth
value
Specifies the width of the cavity containing
window
relative
to the width of
pathName
.
Value
is real number indicating the ratio of
the width of the cavity to the width of IpathName. As the height of
pathName
changes, so will the height of
window
. If
value
is 0.0 or less, the width
of the cavity is the requested width of
window
.   The default is
0.0
.
-width
value
Species the width of the cavity containing the child window.
Value
must be in a form accepted by
Tk_GetPixels
. If
value
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.
pathName
configure
?
window
? ?
option
? ?
value option value ...
?
Queries or modifies the
configuration options of the text widget or one  of its embedded widgets.
If no
window
argument is present,  the htext widget itself is configured.
Otherwise
window
is the pathname of a widget already embedded into the
htext widget. Then this command configure the options for the embedded widget.
If
option
isn't specified, a list describing all of the current options
for
pathName
or
window
is returned.  If
option
is specified, but not
value
,
then a list describing the option
option
is returned.  If one or more
option
and
value
pairs are specified, then for each pair, the htext or embedded
window option
option
is set to
value
.
The following options are valid for
the htext widget.
-background
color
Sets the background of the htext widget
to
color
.  This default is
white
.
-cursor
cursor
Specifies the cursor for
the htext widget.  The default cursor is
pencil
.
-filename
fileName
Specifies
a
htext
file to be displayed in the window.  If the value is the empty string,
the
-text
option is used instead. See the section
FILE
for a description
of the
htext
file format.
-font
fontName
Sets the font of the text in the
htext widget to
fontName
. The default is
*-Helvetica-Bold-R-Normal-*-12-120-*
.
-foreground
color
Sets the foreground of the htext widget to
color
.  This is the color
of the text.  This default is
black
.
-height
pixels
Specifies the height of
the htext widget window.
-linespacing
pixels
Specifies the spacing between
each line of text.  The value must be in a form accepted by
Tk_GetPixels
.
The default value is 1 pixel.
-specialchar
number
Specifies the ASCII value
of the special double character delimiters. In
htext
files, the text between
these special characters is  evaluated as a block of Tcl commands. The default
special character  is the
0x25
(percent sign).
-text
text
Specifies the
text to be displayed in the htext widget.
Text
can be any valid string
of characters. See
FILE FORMAT
for a description.
-xscrollcommand
string
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
string
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.
-yscrollcommand
string
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
string
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.
-width
pixels
Specifies the desired width
of the viewport window.  If the
pixels
is less than one, the window will
grow to accommodate the widest line of text.
-xscrollunits
pixels
Specifies
the horizontal scrolling distance. The default is 10 pixels.
-yscrollunits
pixels
Specifies the vertical scrolling distance. The default is 10 pixels.
pathName
gotoline
?
index
?
Sets the top line of the text to
index
.
Index
must be a valid text index (the character offset is ignored).   If an
index
isn't provided, the current line number is  returned.
pathName
scan mark
position
Records
position
and the current view in the text window;  used
in conjunction with later
scan dragto
commands.
Position
must  be in the
form "
@x,y
, where
x
and
y
are window coordinates. Typically this command
is associated with a mouse button press in the widget.  It returns an empty
string.
pathName
scan dragto
position
Computes the difference between
position
and the position registered in the last
scan mark
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.
Position
must be in the form "
@x,y
, where
x
and
y
are window coordinates. The command
returns an empty string.
pathName
search
pattern
?
from
? ?
to
?
Returns the
number of the next line matching
pattern
.
Pattern
is a string which obeys
the matching rules of
Tcl_StringMatch
.
From
and
to
are text line numbers
(inclusive) which  bound the search.   If no match for
pattern
can be found,
-1
is returned.
pathName
xview
?
position
?
Moves the viewport horizontally
to the new text x-coordinate position.
Position
is the offset from the
left side of the text to the current  position and must be in a form accepted
by
Tk_GetPixels
. If
position
is not present, the current text position is
returned.
pathName
yview
?
position
?
Moves the viewport vertically to the
new text y-coordinate position.
Position
is the offset from the top of
the text to the current  position and must be in a form accepted by
Tk_GetPixels
.
If
position
is not present, the current text position is returned.
#toc8
Bugs
Text
with embedded tabs can be obscured by child windows when scrolled  horizontally.
#toc9
Keywords
hypertext, widget
Table of Contents
#sect0
Name
#sect1
Synopsis
#sect2
Description
#sect3
File Format
#sect4
Indices
#sect5
Variables
#sect6
Syntax
#sect7
Operations
#sect8
Bugs
#sect9
Keywords
