ADC Home > Reference Library > Reference > Carbon > Graphics & Imaging > HTML Rendering Library Reference (Not Recommended) >

Next Page > Hide TOC

Legacy Documentclose button

Important: The HTML Rendering Library is deprecated as of Mac OS X v10.4. A much more complete solution for displaying HTML and web content in your application is provided by the Web Kit. See WebKit Objective-C Programming Guide for guidelines on using the Web Kit.

HTML Rendering Library Reference (Not Recommended)

Framework
Carbon/Carbon.h
Declared in
HTMLRendering.h

Overview

Important: The HTML Rendering Library is deprecated as of Mac OS X v10.4. A much more complete solution for displaying HTML and web content in your application is provided by the Web Kit. See WebKit Objective-C Programming Guide for guidelines on using the Web Kit.

Whereas the HTML Rendering Library takes a specified HTML file and draws text and images in a window, the Web Kit inserts a browser window into your document. The user can specify any URL and follow links in the Web Kit view window. Because the Web Kit takes a completely different approach to displaying HTML and web content from that used by the HTML Rendering Library, you cannot make a one-to-one substitution of Web Kit methods for HTML Rendering Library functions. However, the basic features of the Web Kit can be implemented very quickly, and Web Kit offers much greater capability than the HTML Rendering Library. With the Web Kit, your application can include anything from an HTML viewing window to a full-featured web browser.

Although the Web Kit is an Objective-C interface, you can call it from a Carbon application. See Accessing the Web Kit From Carbon Applications for details.

The HTML Rendering Library gives your application the ability to draw text and images in a window, as specified by HTML data. Note that this API does not include other features of HTML browsers, such as history tracking or plug-in support. The kinds of tasks you can perform with the HTML Rendering Library include

Functions by Task

Identifying The HTML Rendering Library

Handling Newly Visited Links

Handling Previously Visited Links

Obtaining and Disposing of HRReference Values

Formatting the Rendering Area

Intercepting and Redirecting URL’s

Setting and Updating the Rendering Area

Setting Graphics and Display Options

Working With Events

Navigating HTML Pages

Obtaining Information About Pages

Converting URL and FSSpec Data

Working With Universal Procedure Pointers

Miscellaneous

Functions

HRHTMLRenderingLibAvailable

Reports whether the HTML Rendering Library is available. (Deprecated. Use Web Kit instead; see WebKit Objective-C Programming Guide.)

pascal Boolean HRHTMLRenderingLibAvailable

Return Value

Returns true if the HTML Rendering Library is available; returns false otherwise.

Special Considerations

Because the Web Kit takes a completely different approach to displaying HTML and web content from that used by the HTML Rendering Library, you cannot make a one-to-one substitution of Web Kit methods for HTML Rendering Library functions. However, the basic features of the Web Kit can be implemented very quickly, and Web Kit offers much greater capability than the HTML Rendering Library. Although the Web Kit is an Objective-C interface, you can call it from a Carbon application. See Accessing the Web Kit From Carbon Applications for details.

Availability
Declared In
HTMLRendering.h

Callbacks

HRNewCFURLProcPtr

(Deprecated. Use Web Kit instead; see WebKit Objective-C Programming Guide.)

typedef OSStatus (*HRNewCFURLProcPtr)
(
   CFURLRef url,
   CFStringRef targetString,
   Boolean addToHistory,
   void * refCon
);

If you name your function MyHRNewCFURLProc, you would declare it like this:

OSStatus MyHRNewCFURLProc (
   CFURLRef url,
   CFStringRef targetString,
   Boolean addToHistory,
   void * refCon
);

Availability
Declared In
HTMLRendering.h

HRNewURLProcPtr

An application-defined function that tracks newly visited links. (Deprecated. Use Web Kit instead; see WebKit Objective-C Programming Guide.)

typedef OSStatus (*HRNewURLProcPtr) (
   const char * url,
   const char * targetFrame,
   Boolean addToHistory,
   void * refCon
);

If you name your function MyHRNewURLProc, you would declare it like this:

OSStatus MyHRNewURLProc (
   const char * url,
   const char * targetFrame,
   Boolean addToHistory,
   void * refCon
);

Parameters
url

A pointer to a C string containing the URL of the link.

targetFrame

A pointer to a C string containing the name of the target frame.

addToHistory

The HTML Rendering Library passes true in this parameter to indicate that you should add this link to a link-tracking history. It is up to your application to do any link-tracking.

refCon

An arbitrary value set by your application. This value is passed by your application when you call the function HRRegisterNewURLUPP and passed back when the HTML Rendering Library calls your MyNewURLProc function. You may find this value useful for referring to an object instance or a structure, for example.

Return Value

A result code. See “HTML Rendering Library Result Codes.”

Discussion

You may find this function useful for maintaining a history list, for example. The sequence of steps required to implement an application-defined function to track visited links is as follows:

  1. Obtain a UPP for your application-defined function by calling the function NewHRNewURLUPP.

  2. Register your application-defined function by passing the UPP to the function HRRegisterNewURLUPP.

  3. When the HTML Rendering Library calls your application-defined function, take note of the URL being visited.

When you are done using your application-defined function:

  1. Unregister your application-defined function by calling the function HRUnregisterNewURLUPP.

  2. Dispose of the UPP by calling the function DisposeHRNewURLUPP.

Availability
Declared In
HTMLRendering.h

HRURLToFSRefProcPtr

(Deprecated. Use Web Kit instead; see WebKit Objective-C Programming Guide.)

typedef OSStatus (*HRURLToFSRefProcPtr)
(
   CFStringRef rootString,
   CFStringRef linkString,
   FSRef * fref,
   URLSourceType urlSourceType,
   void * refCon
);

If you name your function MyHRURLToFSRefProc, you would declare it like this:

OSStatus MyHRURLToFSRefProc (
   CFStringRef rootString,
   CFStringRef linkString,
   FSRef * fref,
   URLSourceType urlSourceType,
   void * refCon
);

Availability
Declared In
HTMLRendering.h

HRURLToFSSpecProcPtr

Converts URL data to a file system specification. (Deprecated. Use Web Kit instead; see WebKit Objective-C Programming Guide.)

typedef OSStatus (*HRURLToFSSpecProcPtr)
(
   const char * rootURL,
   const char * linkURL,
   FSSpec * fsspec,
   URLSourceType urlSourceType,
   void * refCon
);

If you name your function MyHRURLToFSSpecProc, you would declare it like this:

OSStatus MyHRURLToFSSpecProc (
   const char * rootURL,
   const char * linkURL,
   FSSpec * fsspec,
   URLSourceType urlSourceType,
   void * refCon
);

Parameters
rootURL

A pointer to a C string containing the root URL of the file to be loaded.

linkURL

A pointer to a C string containing the link URL of the file to be loaded.

fsspec

A pointer to a file system specification record (FSSpec) that you use to specify the file to which the HTML Rendering Library redirects the user.

urlSourceType

The HTML Rendering Library passes one of the following constants to indicate the type of file being searched for:

  • kHRLookingForHTMLSource indicates that the file is an HTML source document.

  • kHRLookingForImage indicates that the file is an image.

  • kHRLookingForEmbedded indicates that the file is an embedded object, such as a QuickTime movie.

  • kHRLookingForImageMap indicates that the file is an HTML image map.

  • kHRLookingForFrame indicates that the file is an HTML frameset.

refCon

An arbitrary value set by your application. This value is passed by your application when you call the function and passed back when the HTML Rendering Library calls your MyHRURLToFSSpecProc function. You may find this value useful for referring to an object instance or a structure, for example.

Return Value

A result code. See “HTML Rendering Library Result Codes.”

Discussion

This function may be useful if you want to redirect certain URL’s to application-specific files, for example. The sequence of steps required to implement an application-defined function to intercept URL’s is as follows:

  1. Obtain a UPP for your application-defined function by calling the function NewHRURLToFSSpecUPP.

  2. Register your application-defined function by passing the UPP to the function HRRegisterURLToFSSpecUPP.

  3. Respond when the HTML Rendering Library calls your application-defined function.

When you are done with your application-defined function:

  1. Unregister your application-defined function by calling the function HRUnregisterURLToFSSpecUPP.

  2. Dispose of the UPP by calling the function DisposeHRURLToFSSpecUPP.

Availability
Declared In
HTMLRendering.h

HRWasCFURLVisitedProcPtr

(Deprecated. Use Web Kit instead; see WebKit Objective-C Programming Guide.)

typedef Boolean (*HRWasCFURLVisitedProcPtr)
(
   CFURLRef url,
   void * refCon
);

If you name your function MyHRWasCFURLVisitedProc, you would declare it like this:

Boolean MyHRWasCFURLVisitedProc (
   CFURLRef url,
   void * refCon
);

Availability
Declared In
HTMLRendering.h

HRWasURLVisitedProcPtr

Keeps track of whether a given URL has been previously visited. (Deprecated. Use Web Kit instead; see WebKit Objective-C Programming Guide.)

typedef Boolean (*HRWasURLVisitedProcPtr)
(
   const char * url,
   void * refCon
);

If you name your function MyHRWasURLVisitedProc, you would declare it like this:

Boolean MyHRWasURLVisitedProc (
   const char * url,
   void * refCon
);

Parameters
url

A pointer to a C string containing the URL of the link.

refCon

An arbitrary value set by your application. This value is passed by your application when you call the function and passed back when the HTML Rendering Library calls your MyHRWasURLVisitedProc function. You may find this value useful for referring to an object instance or a structure, for example.

Return Value

If the given URL was previously visited, your application-defined function should return true. If the given URL was not previously visited, your application-defined function should return false.

Discussion

The sequence of steps required to implement an application-defined function to handle previously visited links is as follows:

  1. Obtain a UPP for your application-defined function by calling the function NewHRWasURLVisitedUPP.

  2. Register your application-defined function by passing the UPP to the function HRRegisterWasURLVisitedUPP.

  3. Respond when the HTML Rendering Library calls your application-defined function.

When you are done using your application-defined function:

  1. Unregister your application-defined function by calling the function HRUnregisterWasURLVisitedUPP.

  2. Dispose of the UPP by calling the function DisposeHRWasURLVisitedUPP.

Availability
Declared In
HTMLRendering.h

Data Types

HRNewCFURLUPP

(Deprecated. Use Web Kit instead; see WebKit Objective-C Programming Guide.)

typedef HRNewCFURLProcPtr HRNewCFURLUPP;

Availability
Declared In
HTMLRendering.h

HRNewURLUPP

(Deprecated. Use Web Kit instead; see WebKit Objective-C Programming Guide.)

typedef HRNewURLProcPtr HRNewURLUPP;

Availability
Declared In
HTMLRendering.h

HRReference

(Deprecated. Use Web Kit instead; see WebKit Objective-C Programming Guide.)

typedef struct OpaqueHRReference * HRReference;

Availability
Declared In
HTMLRendering.h

HRURLToFSRefUPP

(Deprecated. Use Web Kit instead; see WebKit Objective-C Programming Guide.)

typedef HRURLToFSRefProcPtr HRURLToFSRefUPP;

Availability
Declared In
HTMLRendering.h

HRURLToFSSpecUPP

(Deprecated. Use Web Kit instead; see WebKit Objective-C Programming Guide.)

typedef HRURLToFSSpecProcPtr HRURLToFSSpecUPP;

Availability
Declared In
HTMLRendering.h

HRWasCFURLVisitedUPP

(Deprecated. Use Web Kit instead; see WebKit Objective-C Programming Guide.)

typedef HRWasCFURLVisitedProcPtr HRWasCFURLVisitedUPP;

Availability
Declared In
HTMLRendering.h

HRWasURLVisitedUPP

(Deprecated. Use Web Kit instead; see WebKit Objective-C Programming Guide.)

typedef HRWasURLVisitedProcPtr HRWasURLVisitedUPP;

Availability
Declared In
HTMLRendering.h

Constants

Scrollbar State

(Deprecated. Use Web Kit instead; see WebKit Objective-C Programming Guide.)

typedef SInt16 HRScrollbarState;
enum {
   eHRScrollbarOn = 0,
   eHRScrollbarOff = 1,
   eHRScrollbarAuto = 2
};

Constants
eHRScrollbarOn

Tells the HTML Rendering Library to draw scrollbars at all times. If the data does not fill the current view, the scroll bars are inactive.

Available in Mac OS X v10.0 and later.

Declared in HTMLRendering.h.

eHRScrollbarOff

Tells the HTML Rendering Library never to draw scrollbars. You may find this option useful if the HTML rendering area you specify does not extend to the edge of a window.

Available in Mac OS X v10.0 and later.

Declared in HTMLRendering.h.

eHRScrollbarAuto

Tells the HTML Rendering Library to draw scrollbars as needed. This is the default setting.

Available in Mac OS X v10.0 and later.

Declared in HTMLRendering.h.

Renderer HTML Type

(Deprecated. Use Web Kit instead; see WebKit Objective-C Programming Guide.)

enum {
   kHRRendererHTML32Type = 'ht32'
};

URL Source Type

(Deprecated. Use Web Kit instead; see WebKit Objective-C Programming Guide.Use Web Kit instead; see WebKit Objective-C Programming Guide.)

typedef UInt16 URLSourceType;
enum {
   kHRLookingForHTMLSource = 1,
   kHRLookingForImage = 2,
   kHRLookingForEmbedded = 3,
   kHRLookingForImageMap = 4,
   kHRLookingForFrame = 5
};

Constants
kHRLookingForHTMLSource

Indicates that the file is an HTML source document.

Available in Mac OS X v10.0 and later.

Declared in HTMLRendering.h.

kHRLookingForImage

Indicates that the file is an image.

Available in Mac OS X v10.0 and later.

Declared in HTMLRendering.h.

kHRLookingForEmbedded

Indicates that the file is an embedded object, such as a QuickTime movie.

Available in Mac OS X v10.0 and later.

Declared in HTMLRendering.h.

kHRLookingForImageMap

Indicates that the file is an HTML image map.

Available in Mac OS X v10.0 and later.

Declared in HTMLRendering.h.

kHRLookingForFrame

Indicates that the file is an HTML frameset.

Available in Mac OS X v10.0 and later.

Declared in HTMLRendering.h.

Result Codes

The most common result codes returned by HTML Rendering Library are listed in the table below. HTML Rendering Library may also return codes noErr (0), and paramErr (-50).

Result CodeValueDescription
hrHTMLRenderingLibNotInstalledErr -5360

The HTML Rendering Library is not available.

Available in Mac OS X v10.0 and later.

hrMiscellaneousExceptionErr -5361

An unexpected exception occurred.

Available in Mac OS X v10.0 and later.

hrUnableToResizeHandleErr -5362

Unable to resize a handle to the required size.

Available in Mac OS X v10.0 and later.



Next Page > Hide TOC

© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-07-13)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.