Inside Macintosh: Apple Guide Complete / Part 3 - Integrating Guide Files

Chapter 9 - Apple Guide API / Installing and Removing Context Check Handlers

/

AGInstallContextHandler

Use the AGInstallContextHandler function to install a context check handler.

OSErr AGInstallContextHandler
                  (ContextReplyProcPtr ContextReplyProc,
                   AEEventID eventID,long refCon,
                   AGContextRefNum *resultRefNum);

ContextReplyProc

A reference to the function called by Apple Guide in response to a context check specified in a guide file.

eventID

A four-character value that should match the value of the codeResSpec parameter in the <Define Context Check> command for this context check.

refCon

An optional reference constant that your application can provide. Apple Guide passes this as a parameter to your context check handler.

resultRefNum

A reference number. The AGInstallContextHandler function returns, through this parameter, a number that refers to the context handler.

DESCRIPTION

The AGInstallContextHandler function installs the context handler specified in the ContextReplyProc parameter and returns in the resultRefNum parameter a reference to it. Once a context check handler is installed, Apple Guide calls it in response to any context checks that specify your application as a target in the <Define Context Check> command. Apple Guide calls the context check handler only if the value specified in the command's codeResSpec parameter matches the value specified in the eventID parameter.

SPECIAL CONSIDERATIONS

Before quitting, your application should always remove any context check handlers (using AGRemoveContextHandler) that it has installed.

RESULT CODES

noErr	0	No error
kAGErrCannotInitContext	-2953	Unable to initialize context handler
kAGErrMissingAppInfoHdl	-2958	No application information handler
kAGErrMissingContextObject	-2959	No context object

.

SEE ALSO

For information on writing a context check handler, see "Responding to Context Checks" on page 9-40. For information on the <Define Context Check> command, see the chapter "Guide Script Command Reference."