NOTE:
This project is no longer being maintained: it was developed for my masters thesis, which was completed in early 1997. I still, however, welcome any questions or comments that people may have.

[Home] [ToC] [Up] [Prev] [Next]

iHTML Browser Services

Documents

The browser's document services include functions for examining and modifying the global state of a document through its HTML parse tree, reporting information about the document, and managing the browser's interaction with the rest of the iHTML system. These services are implemented are part of the browser's own glue.

Types

IHBrowser

Synopsis: A handle on a single browser window, in which an HTML or other document may be viewed.
Definition: void* (This is an opaque type that is defined by the browser's internal implementation.)
See Also: IHDocument, IHGlobalInfo

The IHBrowser is a handle on the display context for a document. This is typical a user interface window that the browser is managing, in which it is displaying an IHDocument.

IHDocument

Synopsis: An particular HTML document the browser is currently displaying or has available in its RAM cache.
Definition: void* (This is an opaque type that is defined by the browser's internal implementation.)
See Also: IHBrowser, IHGlobalInfo

The IHDocument is a handle on a particular HTML document in the system, representing a particular document scripting context. It is the interface to examining and displaying HTML trees, and other document-level operations.

Because integral part of the iHTML architecture is the manipulation of actual HTML parse trees, this document should not be thought of as representing any particular HTML markup. Instead, it is actual the URL from which the markup (and scripts, graphics, etc. associated with it) was retrieved.

Functions

BR_AllocResources

Synopsis

Allocate browser resources needed for a document's scripting interface.

IHBrowser
		BR_AllocResources(IHGlobalInfo* ii)

Arguments

(IHGlobalInfo*) gi: The iHTML Library scripting interface that the browser will be running.

Return

(IHBrowser) Resources the browser needs for the interface.

See Also

IHDocument. IHBrowser. IHGlobalInfo

This routine is called when first starting a new document interface. It is used by the browser to allocate any resources it needs specifically for that interface, and for any other setup that needs to be done. This routine should return a non-zero value to indicate success, which will be placed into the give IHGlobalInfo's 'browser' field.

This routine is called AFTER the document has been parsed, e.g. the IHGlobalInfo's modules and objects lists have been filled in.

When called, gi->document is guaranteed to contain the browser document the interface is on.

BR_FreeResources

Synopsis

Free browser resources previously allocated with BR_AllocResources().

void BR_FreeResources(IHGlobalInfo* gi,
		IHBrowser br)

Arguments

(IHGlobalInfo*) gi: The iHTML Library scripting interface that the browser will be running.
(IHBrowser) br: The browser-side resources to deallocate.

Return

nothing.

See Also

IHDocument. IHBrowser. IHGlobalInfo

Frees and cleans up any browser-side resources that were allocated by a previous call to BR_AllocResource(). This function is called by the iHTML Library prior to deallocating the scripting interface.

BR_GetDocHTMLTree

Synopsis

Get the HTML parse tree that is currently being displayed by a document.

HTMLNode BR_GetDocHTMLTree(IHDocument
		doc)

Arguments

(IHDocument) doc: The browser-side document.

Return

(HTMLTree) The root of the HTML tree that doc is currently displaying.

See Also

IHDocument. HTMLNode

Returns a handle on the root of the HTML parse tree that is currently being displayed in the given document.

BR_Reformat

Synopsis

Re-evaluate and draw a document's HTML parse tree.

void BR_Reformat(IHDocument
		doc)

Arguments

(IHDocument) doc: The browser-side document.

Return

nothing

See Also

IHDocument. HTMLNode

Examines and re-formats the document's current HTML parse tree. This must be called if any changes are made to it, so that they are correctly reflected in the display. If a document has a document-level scripting interface, this function must be called initially to display it.

BR_ReportError

Synopsis

void BR_ReportError(IHDocument doc,
		const char* str, ...)

Arguments

(IHDocument) doc: The document context the error occurred in, or NULL.
(const char*) str: A description of the error, which may contain printf-style formatters for interpreting the arguments that follow.

Return

nothing.

See Also

IHDocument

Reports an error condition to the user. str can contain standard printf()-style formatters, and any additional arguments are interpreted as per printf(). The doc argument is used to determine the context the error occurred in; it may be NULL, in which case it is assumed to be a global error, not associated with any particular document.

BR_SetDocHTMLTree

Synopsis

Set the HTML parse tree that is to be displayed in a document. being displayed by a document.

void BR_SetDocHTMLTree(IHDocument doc,
		HTMLNode tree)

Arguments

(IHDocument) doc: The browser-side document.
(HTMLMarkup) tree: The markup to display.

Return

nothing.

See Also

IHDocument. HTMLNode

Sets the given HTML parse tree as the text currently being displayed by the document. The document is automatically reformatted and the new text displayed.

Calling this function passes ownership of the parse tree over to the document -- the browser will automatically deallocate it whenver it deallocates the document itself. You can still manipulate internal parts of this tree, however, while it is owned by the document.

Note that this function does not deallocate any tree that is already associated with the document. Thus, if a program wished to create a completely new tree to replace a document's current tree, it must do something like this:

HTMLNode old_tree;
old_tree = BR_GetDocHTMLTree(doc);
BR_SetDocHTMLTree(new_tree);
BR_FreeMarkup(old_tree);

BR_ShowLink

Synopsis

Display information about a hypertext link to the user.

void BR_ShowLink(IHDocument doc,
		const char* text)

Arguments

(IHDocument) doc: The browser-side document context.
(const char*) text: Text of link to display.

Return

nothing

See Also

IHDocument

Displays information about a hypertext link within the browser, to the user. A NULL 'text' clears any previous link report. This provides access to the browser's mechanism for displaying information to the user about links that, for example, the pointer is over, and is only intended for this type of use. It could be called, for example, in a language that implements client-side imagemaps.

BR_ShowProgress

Synopsis

Display a progress report to the user.

void BR_ShowProgress(IHDocument doc,
		const char* text)

Arguments

(IHDocument) doc: The browser-side document context.
(const char*) text: Message to display.

Return

nothing

See Also

IHDocument

Displays the given text as a running progress report within the browser. This text is shown in an out-of-the-way place; it is not intended to draw the user's attention to important information, but rather as a small status report on the browser's activity. A NULL 'text' clears any previous progress report.

[Home] [ToC] [Up] [Prev] [Next]

_________.oo_Q_Q_oo.____________________________________________

Dianne Kyra Hackborn <hackbod@angryredplanet.com>
Last modified: Tue Oct 8 07:56:28 PDT 1996

This web page and all material contained herein is Copyright (c) 1997 Dianne Hackborn, unless otherwise noted. All rights reserved.