docs/intro.html

<HTML>
<HEAD>
   <TITLE>HTMLRenderingLib Guide</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<H1>Guide to the HTML Rendering Library</H1>
 
<P>&nbsp;</P>
 
<H3>Overview</H3>
 
<P>The HTMLRenderingLib provides facilities allowing developers to
draw HTML files. The library provides a facility developers can use
to display HTML based help content in their applications or
application packages.</P>
 
<P>The HTML rendering library provides HTML rendering objects that do
the actual HTML drawing. Routines are provided allowing applications
to create and manipultate rendering objects. These objects are
referenced through an opaque data type called an <A HREF="types.html#HRReference">HRReference</A>.
The actual implementation and details of how the rendering object
works and the data it stores are kept hidden from client applictions
and the only way to manipulate these objects is by using the routines
provided by the library.</P>
 
<P>Routines are provided for handling events directed at HTML data
displayed on the screen. Most of the work required for maintaining an
area of the screen set aside for an HTML rendering object is handled
by the HTML rendering library in the routine <A HREF="generalroutines.html#HRIsHREvent">HRIsHREvent</A>.
At the very least, in an event handling routine an application will
need to call the HTML rendering library in response to update events
(by calling <A HREF="drawing.html#HRDraw">HRDraw</A>) and activate
events (by calling <A HREF="drawing.html#HRActivate">HRActivate</A>
or <A HREF="drawing.html#HRDeactivate">HRDeactivate</A>).</P>
 
<P>To speed drawing and redrawing the library maintains a memory
based cache of previously viewed images and HTML data. This cache is
maintained inside of the application's heap zone and will grow as
pages are viewed. Left unchecked, the cache has the potential to grow
until the entire heap zone has been consumed. But, it is possible to
reclaim some of this storage by calling the <A HREF="generalroutines.html#HRFreeMemory">HRFreeMemory</A>
routine. This routine will release memory occupied by the cache for
other uses in an application.</P>
 
<P>The display characteristics for HTML rendering objects, such as
it's location on screen, the GrafPort where the HTML image is to be
drawn, the state of the scroll bars, et cetera, can be modified by
application clients. Also, a routine is provided that allows
applications to query the actual size of the HTML image after it has
been drawn by an HTML rendering object.</P>
 
<P>As one would expect, the HTML rendering library includes a set of
routines for directing HTML rendering objects to display URLs and for
scrolling the display to specific anchors. Also, it is possible to
render HTML data directly from memory rather than using a file. Along
with these routines, there are a set of utility routines for
manipulating URLs and easily creating URLs that refer to Macintosh
files.</P>
 
<P>For managing visited links, the rendering library allows
applications to associate callbacks with HTML rendering objects. The
HTML rendering library calls these routines either when it needs to
know if a link has been visited or whenever it is moving the display
to a new page.</P>
 
<P>In applications where it is appropriate to provided your own
custom URL to Macintosh file mapping scheme, it is possible to
associate a callback with a HTML rendering object that the HTML
rendering library will call to map URLs to Macintosh files.</P>
 
<P><A HREF="index.html">return to index</A></P>
 
<P><A NAME=tips></A></P>
 
<P>&nbsp;</P>
 
<H3>Programming Tips</H3>
 
<P>HTMLRenderingLib is by no means a full scale HTML environment and
should not be used as a general HTML rendering engine. In particular,
it should not be used for displaying extreemly large HTML files.
Always test the content you intend to display using the
HTMLRenderingLib to ensure it will work as expected.</P>
 
<P>Some of the HTMLRenderingLib routines leave either the grafport's
origin or the grafport's clipping region in an undefined state. If
you are drawing other objects in the same window that you are using
with an html rendering library object, then you should be aware of
this and reset these parts of the drawing environment as appropriate
before attempting to do any drawing of your own. This sample
application handles these cases appropriately.</P>
 
<P><A HREF="index.html">return to index</A></P>
 
<P>&nbsp;</P>
 
<P>&nbsp;</P>
 
<P>&nbsp;</P>
 
<P></P>
</BODY>
</HTML>


Copyright © 2003 Apple Computer, Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2003-01-30