Web page library manual

This is a preliminary manual for the Hippo HTML display library

This HTML library provides the facilities needed to display HTML/2.0 data in a TK text widget. It supports all of the HTML 2.0 constructs.

The HTML library is designed to be easy to use for simple applications, yet provide a flexible framework for sophisticated solutions. The HTML library is packaged so that all procedures and external variables are prefixed by HM. It is safe to run sed over the HTML library to globally change HM to something else if needed.

The HTML library consists of a suite of procedures and data structures which are used to interface HTML to an application. For the most part, all of the data structures are used internally by the HTML library, and may be ignored by most applications.

There are tree main types of procedures, call-ins, call-backs, and helper procs. The call-in procs, supplied by the HTML library, are called directly by the application with the appropriate arguments. The call-back procs are supplied by the application, and called by the HTML library under the appropriate circumstances, such as when the user clicks on a hypertext link. The third class of procedures, the helper procs, are utility procedures that may be used both by the HTML library and in the application's procedures to perform common HTML related tasks.

For the simplest use of the HTML library

  1. Create a text widget, called .text
  2. Initialize the text widget by calling HMinit_win .text
  3. Put an HTML document into the tcl variable html.
  4. Render the document by calling HMparse_html $html "HMrender .text"
. Any time the user clicks on a hypertext link, the HTML library will call-back the procedure (which you need to supply):
	proc HMlink_callback {win href} { ...}
   		win      The name of the text widget (.text)
   		href     The name of the link
Presumably this procedure will figure out how to turn the link into a tcl variable containing HTML, and then call
  1. HMreset_win .text to reset the text widget.
  2. Render the document by calling HMparse_html $html "HMrender .text"
When the HTML library encounters an inline image while rendering a page, it calls the procedure (you supply this one too):
	proc HMset_image {handle src}
		handle:  a handle that identifies this image
		src     The name (or url) of the image
It is up to the application to fetch the image, and make it into a TK image, by using a call something like:
	image create photo $image_name -file $src
Once the image is loaded into TK, the application should call
	HMgot_image $handle $image_name
where $handle is the token passed to HMset_image and $image_name is the name of the TK image. If, for some reason the image could not be obtained, you may set image_name to a text string that will be displayed instead. If you never call HMset_image at all, the alt entry in the image parameter list will be displayed instead.

Advanced usage

Although the procedures outlined below may be sufficient for simple uses of HTML, sophisticated applications may require finer control over the workings of the HTML library. The HTML library is constructed in layers, such tha

There are two routines that manage navigation into the middle of the document. When

	HMgoto $text_widget $where
is called, the text view is moved to make the hypertext link $where visible. A return value of 1 indicates success, whereas 0 indicates the reference was not found, either because it isn't in the document, or it hasn't been rendered yet. In the latter case, the request is queued until the destination is rendered. Any time navigation to the link is sucsessful,
	HMwhen_to $text_widget $where
is called.

The HTML library is programmable in several ways. This section will be expanded as time permits.

I plan to expand the library interface documentaion, providing infomation on existing call-backs in future releases. Some examples may include:
  • Fetching and rendering a document in sections
  • Managing a multiple document interface
  • Instantiating new documents inside of existing ones
  • For a more detailed description of how to use the advanced features of the library, see the reference guide


    home