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

Chapter 9 - Apple Guide API

Introduction

This chapter describes two sets of routines: those in the Apple Guide API and those in the AGFile library. The routines in the Apple Guide API are available in System 7.5 or later. The routines prefixed with "AGFile" are not included in System 7.5 but are part of the AGFile library; to use these routines you must link the AGFile library with your application when you build it.

You can use functions in the Apple Guide API and AGFile library to

• start up Apple Guide and get information about its status
• get the number and type of guide files available
• open and close guide files
• work with open guide files
• get information about guide files
• provide object location for coachmarks
• respond to context checks

Determining Whether Apple Guide Is Available

To determine whether Apple Guide is available, call the Gestalt function with the gestaltHelpMgrAttr selector and check the value of the response parameter. If the bit indicated by the constant gestaltAppleGuidePresent is set, then Apple Guide (and its API) is available. If the bit indicated by the constant gestaltAppleGuideIsDebug is set, then the Apple Guide Debug extension is installed (you use the Apple Guide Debug extension only for debugging your guide file).

enum {
   gestaltHelpMtrAttr      'help'   /*Gestalt selector for Help Mgr */
                                    /* and Apple Guide*/
   gestaltAppleGuidePresent = 31,   /*Apple Guide API is available*/
   gestaltAppleGuideIsDebug = 30    /*Apple Guide Debug extension */
                                    /* is installed*/ 
};

For example, this code determines whether Apple Guide is available:

   long response = 0;
   OSErr err;

   err = Gestalt(gestaltHelpMgrAttr, &response);
   if (err == noErr && (response & (1 << gestaltAppleGuidePresent)))
      /*Apple Guide is available*/
      kAppleGuideAvailable = 1
   else
      /*Apple Guide is not available*/
      kAppleGuideAvailable = 0;

For information on the Gestalt function, see the chapter "Gestalt Manager" in Inside Macintosh: Operating System Utilities.