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.

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.

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