NAME
htext - Create and manipulate hypertext widgets
SYNOPSIS
htext pathName ?option value?...
_________________________________________________________________
DESCRIPTION
The htext command creates a new window (given by the path
Name argument) and makes it into a htext widget. Addi
tional 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 win
dow 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 wid
get, 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.
FILE FORMAT
The format of htext text file is typically ASCII text.
Text enclosed by special double characters (by default,
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 wid
get 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.
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 selec
tion. 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.
VARIABLES
The following global Tcl variables are maintained when an
htext file is parsed.
htext(widget)
is the pathname of the htext widget.
is the name of the file the htext widget is cur
rently parsing. It is the empty string when the
-text option is used.
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.
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.
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 loca
tion 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 sur
rounding the window. For example, if
anchorPos is center then the window is cen
tered 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 sur
rounding 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.
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 cav
ity 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
padded by the value. The default is 0.
-relheight value
Specifies the height of the cavity contain
ing window relative to the height of path
Name. Value is real number indicating the
ratio of the height of the cavity to the
height of pathName. As the height of path
Name 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 cav
ity 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 win
dow 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.
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 FORMAT for a descrip
tion of the htext file format.
-font fontName
Sets the font of the text in the htext wid
get 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 char
acters is evaluated as a block of Tcl com
mands. 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
bar, 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 scroll
bar, 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
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 coordi
nates. The command returns an empty string.
pathName search pattern ?from? ?to?
Returns the number of the next line matching pat
tern. 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.
BUGS
Text with embedded tabs can be obscured by child windows
when scrolled horizontally.
KEYWORDS
hypertext, widget
Man(1) output converted with
man2html