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.
- Array elements that begin with
S_
are not reset by calls to HMreset_win
.
- Array elements beginning with
T
are used by the library
as a list of text tags, the last element of which is associated with
the current text.
home