Legacy Document

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

Chapter 9 - Apple Guide API / Application-Defined Routines

Responding to Context Checks /

MyContextReplyProc

A context check handler checks the condition associated with a context check and returns the result.

Here is the syntax of a context check handler function:

pascal OSErr MyContextReplyProc
                     (Ptr pInputData, Size inputDataSize,
                     Ptr *ppOutputData,
                     Size *pOutputDataSize,
                     AGAppInfoHdl hAppInfo);

pInputData

A pointer to the input data. Apple Guide places any parameters specified by the context check in the data area pointed to by this parameter. Apple Guide concatenates the parameters in a byte array (word-aligned); your context check handler function retrieves the data through this parameter. You can cast pInputData to a pointer to a data structure that describes the parameters specified by your <Define Context Check> command.

inputDataSize

The size of the input data in bytes.

ppOutputData

Your context check handler function should return, through this parameter, a pointer to a short integer. The short integer should contain the result of the context check, 1 for true and 0 for false.

pOutputDataSize

Your context check handler function should return, through this parameter, the size of the output data in bytes, usually sizeof(short).

hAppInfo

A handle to a structure of type AGAppInfo.

            typedef struct AGAppInfo
            {
               AEEventID   eventId;       /*event ID*/
               long        refCon;        /*app's refCon*/
               void        *contextObj;   /*private*/
            }

Apple Guide places the event ID and reference constant (specified in the call to AGInstallContextHandler) into the eventId and refCon fields of this structure. The eventId field corresponds to the value of the codeResSpec parameter in the <Define Context Check> command for this context check. You can use the refCon field for any purpose. The contextObj field is used by Apple Guide and your application should not use or change this field.

DESCRIPTION

Your MyContextReplyProc function should perform the context check and return the result of the context check through the ppOutputData parameter.

EXAMPLES

Here's an example of a context check installed by the SurfWriter application. The SurfWriter application defines these context checks in its guide file using the <Define Context Check> command:

<DCC> "SWDictionaryIsOpen", 'SWdd', 'WAVE', short:1, LPSTRING
<DCC> "SWThesaurusIsOpen", 'SWdd', 'WAVE', short:2, LPSTRING

Here's how SurfWriter Guide uses one of these context checks to dynamically adjust the display of its panels:

<Panel> "Dictionary:intro"
<Skip If> SWDictionaryIsOpen("Standard")
<Panel> "Dictionary:open"
<Panel> "Dictionary:lookupWord"

The SurfWriter application installs its context check handler using the AGInstallContextHandler function.

/*gEventID = 'SWdd'*/
myErr = AGInstallContextHandler(SWIsOpenContextCheck, 
                                 gEventID, 
                                 &gRefCon, &gResultRefNum);

This is how it defines its context check handler function. (A context check in an external module receives the same parameters, but it has a single entry point, main.)

pascal OSErr SWIsOpenContextCheck
                     (Ptr inputDataPtr, Size inputDataSize, 
                      Ptr *ppOutputData, Size *pOutputSize, 
                      AGAppInfoHdl hAppInfo)
{
   Boolean  isOpen   =  false;
   OSErr    myErr    =  noErr;
   /*app-defined structure contains two fields, a short and a string*/
   MyContextCheckParams    myCCParams;

   myCCParams = *((MyContextCheckParams *) inputDataPtr);

   switch (myCCParams.selector)
   {
   case 1:     /*check whether a specified dictionary is open*/
      isOpen = MyCheckDictionary(myCCParams);
      break;
   case 2:     /*check whether a specified thesaurus is open*/
      isOpen = MyCheckThesaurus(myCCParams);
      break;
   default: 
      break;
   }
   /*return result of context check (true or false) in the */
   /* ppOutputData parameter*/
   myErr = MySetContextResult(&isOpen, sizeof(Boolean), 
                               ppOutputData, pOutputSize);
   /*if error occurs, return appropriate function result */
   /* indicating error*/
   return(myErr);
}
OSErr MySetContextResult(void *theData, Size theSize, 
                          Ptr *outMessage, Size *outSize)
{
   Ptr    p;
   
/*the context check routine must return a pointer to a short */
/* in the ppOutputData parameter */
/* (Apple Guide will dispose of the pointer on return)*/
/*(1 = true, 0 = false) indicates the result of the context check*/
/*The routine must also return the size of the ppOutputData */
/* in the pOutputSize parameter*/
   if (p = NewPtr(theSize))
   {
      BlockMove(theData, p, theSize);
      *outSize = theSize;
      *outMessage = p;
      return(noErr);
   }
   else
      return(MemError());
}

RESULT CODES

The MyContextReplyProc function should return noErr if successful, or an appropriate result code otherwise.