HTML Library interface Summary

This document describes how to use the HTML library. Unless otherwise noted, win refers to the name of the text widget to contain the HTML.

Primary call-in procedures

These procedures are the basic application entry points.

HMinit_win {win}
Initialize a text widget for displaying HTML. This returns the name of the global variable used to store the page state by the library.
HMreset_win {win}
Reset a used text widget to a clean state by removing all text and page specific text tags and marks.
HMgoto {win where}
Either position, or schedule the position of the document at the where reference. Return TRUE if the positioning succeeded. A callback to HMwent_to will be made when the positioning is completed.
HMgot_image {handle image}
Called from the HMset_image callback when an image was successfully created. image is the name of a Tk image, and handle is the handle passed in by HMset_image
HMparse_html {html cmd start}
Parse html. Cmd gets called once for each html tag. Start is a dummy html tag that wraps the entire document. The default value of start, hmstart initializes the text widget tag state for a new page.

Primary call-backs

These are the procedures that the application needs to supply.

HMset_image {win handle src}
Called when an inline image is first seen. Src is the URL for the image. The application should create a Tk image, then call HMgot_image.
HMlink_callback {win href}
Called when the user clicks on a hypertext link, image map, or (by default) an isindex selection. Href is the name of the hypertext link.
HMsubmit_form {win param query}
This is called when the user hits the submit button on a form. Param is the list of HTML parameters passed in with the FORM html tag, and query is a list whose even elements (starting from 0) are field names, and odd elements are the corresponding field values. The procedure HMmap_reply may be used by the application to convert the list into an HTTP POST query.
HMmark {tag win param text}
This is an application hook that, if it exists, gets called each time an HTML tag is rendered, just before any tag specific routine is called. It is intended to allow an application to associate application specific marks into the text widget, but you can use it for anything you like. There is no default implementation, and none is required.
HMtag_XXX {win param text}
This is generic HTML tag hook, where XXX is the name of the html tag (or /XXX for the end tag). Any html tag may have special code that gets run. Applications may override the default library implementations for HTML tags, or add functionality for new tags. Param is the html parameter list, and text is the name of the variable containing all of the plain text up to the next html tag.

Auxillary state-altering routines

These procedures man be used by an application to alter some aspects of the HTML display.

HMset_indent {win cm}
Sets the tab-stop for tabbing and lists.
HMset_state {win args} -update -tab -unknown -stop -size -symbols -insert
This is the procedural interface to access the internal state of the HTML rendering process. It is intended that anything an application might want to change in that state will be done through here. Currently, an application can set the update frequency (update), unknown entity character (unknown), global font size adjuster (size), list of unordered list symbols (symbols), stop the document rendering (stop), or choose a text mark at which to insert the text (insert).

Replaceable Procedures

These are library routines that have reasonable default implementations, but may be replaced by an application for more specific behavior.

HMlink_setup {win href}
This gets called once when a hypertext link is first encountered. The default implementation arranges to highlight the link upon mouse entry and exit.
HMwin_install {win item}
This procedure is called any time an embedded window (item) from a FORM is inserted into the text. The default implementation sets the indent level, alignment, and tabbing behavior.
HMsubmit_index {win param text}
This is called when submitting ISINDEX tags. The default calls HMlink_callback.
HMset_font {win tag font} This procedure is called to set the text tag tag to the font name font, which is just what the default implementation does.
HMwent_to {win where}
This procedure is called after navigation into the document occurred via a fragment reference. The default implementation flashes the link a couple of times.

Utility routines

These procedures are used by the library routines, but can also be used by the application as needed.

HMmap_reply {string}
Converts string into application/x-www-urlencoded format. for use in HTTP POST queries.
HMcgiMap {string}
Converts string from application/x-www-urlencoded format into a list of name - value pairs. This routine is not used by the library, but can be used in CGI scripts.
HMzap_white {data}
Converts all sequences of white space to a single space character.
HMmap_esc {text}
Converts all embedded entity references into their ascii form.
HMstack {win push list}
Pushes or pops a text tag (or tags) on to the current tag stacks. Push is either {} to push or / to pop. List contains an even number of elements, grouped in pairs. The first element in the pair is the name of the stack, and the second element is the value to push. When popping, the value is ignored.
HMcurrent_tags {win}
Retrieves the current text tag state by assembling the top elements of all of the text tag stacks.
HMextract_param {param key {val ""}} checks for and extracts a key value out of an HTML attribute list. If val is supplied, it names the variable that will contain the value of key. Otherwise, The variable key is used.

Primary static data structures

The HTML library uses some static global arrays that define the layout policy of various HTML tags. Applications may change or augment these arrays to effect the HTML tag to layout policy.

array HMtag_map
The indeces are HTML tag names. The value is a list of ordered pairs. The even elements (starting from 0) are text tag names, and the odd elements are their values.
array HMinsert_map
The indexes are HTML tag names. The value is the amount of white space to be added after this tag.
array HM$win
This array is used to keep all of the state information used internally by the library package for the text widget $win. Applications may add or modify some elements of this array (with care) to alter the operation of the library.

home