Samples

Turning your application into an SGML/HyTime browser is a matter of using a few simple functions. Once a document is loaded, it can immediately be displayed and navigated in any window, or used for retrieval of the contained information. This section includes small samples of these uses.

Loading a Document

An SGML document is loaded by a simple command:

  HDOC hDoc = SvOpenNameDoc("doc.sgm", NULL, HNIL, NULL, 0);

SvOpenNameDoc invokes the SGML parser to load the SGML entity doc.sgm. The parser resolves the named document through the entity manager and returns a handle to the parsed entity. SvOpenNameDoc is a powerful function, as it allows you to open an SGML document by any name, and supply the actual entity from any source by customizing the entity manager. By default, the entity manager interprets the name as a plain file name.

SvOpenNameDoc further allows you to explicitly specify the DTD of the document, and to supply a parser message receiver function, to which all warnings and errors encountered during the parse process are reported.

Synex ViewPort™ is also capable of opening a document by content, where the document entity is either supplied in a single memory block, or as a generating procedure that passes the entity contents—fragment by fragment—to the parser. For instance, the latter approach allows you to open a document directly from a socket.

Displaying a Document

It is straightforward to display a document in a window:

  SvDisplayPage(Window, hDoc, HNIL, HNIL, 0, HNIL, HNIL, 0);

SvDisplayPage combines a document and a style sheet, and displays it in a specified window where scrollbars, window resizing, and mouse processing are automatically handled. This command turns your application into an SGML browser.

If a style sheet is not explicitly specified (as in the example above), Synex ViewPort™ selects the default style sheet of the document. SvDisplayPage also allows you to:

• specify a navigator, turning the document view into an active table of contents
• restrict the displayed view to a specific element
• initially position the displayed view at a specific element
• specify page options, for instance allowing you to include the document markup and processing instructions of the displayed view

Traversing the SGML Markup

Several Synex ViewPort™ API functions are designated for object information retrieval. For instance, an HDOC object contains HTAG objects describing the SGML markup. There are several ways of retrieving the HTAG objects, such as:

• the top—root—element
• an element with a specific ID
• an element specified using a TEI location pointer
• elements with specific content

It is also possible to loop through the entire SGML tree and investigate or process every element individually, one by one. The function below exemplifies such processing. Assuming a start at the document root, we have:

void WalkSGMLTree(HTAG hTag) { 
  /* Do any preprocessing of the element */ 
  if (SvMoveTagToChild(hTag)) { 
  do { 
    WalkSGMLTree(hTag); 
  } while (SvMoveTagToNext(hTag); 
  SvMoveTagToPar(hTag); 
  } 
  /* Do any postprocessing of the element */ 
}

Traversing all HyTime CLINKs

A common need is the ability to retrieve elements meeting a specific criteria. By using TEI locators, elements may be scanned for a specific GI or attribute value. This example uses TEI location pointers to enumerate all HyTime clinks of a document.

void EnumerateClinks(HDOC hDoc) { 
  /* Retrieve an element handle to the document root */ 
  HTAG hTag = SvGetRootTag(hDoc); 
  /* Enumerate all clink elements */ 
  while (SvMoveTagToTEI(hTag, "HERE NEXT (1 * HyTime clink)")) { 
    /* Do any processing on the clink element */
  } 
  /* Release the element handle */
  SvUnlock(hTag);
}

Note: A careful reader—familiar with TEI and C programming—will notice a minor bug. The function will fail to enumerate the root element if it happens to be a HyTime clink, so one should address this special case as well: this is left as an exercise to the reader!

In this brief introduction, we have looked at 8 of the Synex ViewPort™ functions, and indicated the usefulness of ViewPort in addressing both dynamic and static browsing requirements from any source: memory, network, or CD-ROM..