Synex ViewPort API Overview

The API is the control panel of the Synex ViewPort™ engine. It consists of:

• A set of object types
• A set of API functions
• A set of callbacks

Object Types

The Synex ViewPort™ API uses a few object types that represent the basic objects of the kernel. Using the API is mainly a matter of investigating, manipulating, and combining the Synex ViewPort™ objects.

There are five fundamental objects:

• HDTD, a document type definition.
• HDOC, an SGML document.
• HSSH, a style sheet.
• HNAV, a navigator.
• HWEB, a web.

These object types have already been introduced.

Synex ViewPort™ also contains five sub-object types:

• HENT, an entity declaration.
• HNOT, a notation declaration.
• HTAG, an SGML element.
• HTAGSET, a collection of SGML elements.
• HANCHOR, a web anchor.

An HENT represents an entity declaration. These objects reside in HDTDs (as general and parameter entities) and in HDOCs (as general entities). HENTs are, for instance, used in SGML to identify and reference external entities, such as other SGML documents, graphics, audio, etc.

An HNOT represents a notation declaration. These objects reside in HDTDs and HDOCs, and can be attached to HENTs. An HNOT is a format declaration, specifying the data type of an HENT.

An HTAG represents an element—a tag—in the SGML tree of an HDOC, or rather a location, as the HTAG object can be moved around in the tree. An HTAG can also identify—or position itself at—pseudo elements and NDATA entities.

An HTAGSET is a container where a collection of HTAGs can be stored. An HTAGSET can both be manually created, element by element, or built by an SGML query, collecting the sought elements—for instance all <ANIMAL> elements containing the word cat. An HTAGSET can be passed on to the hardcopy generator, constraining the hardcopy output to the contained elements.

An HANCHOR represents an anchor in an HWEB. The anchor concept was introduced in a previous section.

Synex ViewPort™ also defines an HPAGE object type. An HPAGE object is a rectangular area where a document or a zoomable graphics is displayed. The HPAGE object is not part of the Synex ViewPort™ kernel, but part of the windowing environment of the platform:

• An HWND in Microsoft Windows
• A Widget under Motif
• A Metrowerks PowerPlant LView object on the Macintosh

This illustration shows the objects and their internal relations:

Relations of Synex ViewPort™ objects

API Functions

There are about 300 functions available in the C API.

Callbacks

Whenever Synex ViewPort™ needs advice or information from the main application, it invokes callbacks. By responding to callbacks it becomes possible to:

• Customize the Entity Manager
• Customize the SDATA Manager
• Extend the built-in link capabilities
• Customize the display of notation data, e.g. play a sound or launch a video viewer
• Customize the behavior when a navigator entry is selected
• Generate text to be displayed in the browser
• Add arbitrary widgets (such as buttons and data input fields) in the browser
• Control the positioning of new document views, launched from within the kernel.
• Control the loading of documents (when the user follows cross-document links)
• Redefine system messages (for translation to other languages)

Synex ViewPort™ also uses callbacks to inform the main application about state changes, such as when the user has made a text selection or scrolled a page. This allows the main application to synchronize its logical state and behavior at all times.