Provided by: blt-dev_2.5.3+dfsg-7build1_amd64 
NAME
htext - Create and manipulate hypertext widgets
SYNOPSIS
htext pathName ?option value?...
_________________________________________________________________
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.
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.
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.
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(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 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 FORMAT
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.
BUGS
Text with embedded tabs can be obscured by child windows when scrolled horizontally.
KEYWORDS
hypertext, widget