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

Chapter 9 - Apple Guide API

Summary of Apple Guide API

Constants

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*/
};
enum {
   /*guide file active list types*/
   kAGViewFullHowdy        = 1,  /*full howdy*/
   kAGViewTopicAreas       = 2,  /*Topic Area*/
   kAGViewIndex            = 3,  /*Index*/
   kAGViewLookFor          = 4,  /*Look For*/
   kAGViewSingleHowdy      = 5,  /*Single List howdy*/
   kAGViewSingleTopics     = 6   /*Single List topics*/
};
enum AGDBTypeBit
{  /*guide file types returned by AGGetAvailableDBTypes*/
   kAGDBBitAny          = 0x00000001,/*one or more guide */
                                     /* files are present*/
   kAGDBTypeBitHelp     = 0x00000002,/*Help guide file*/
   kAGDBTypeBitTutorial              /*Tutorial guide */
                        = 0x00000004,/* file*/
   kAGDBTypeBitShortcuts             /*Shortcuts guide */
                        = 0x00000008,/* file*/
   kAGDBTypeBitAbout    = 0x00000010,  /*About guide file*/
   kAGDBTypeBitOther    = 0x00000080   /*Other guide file*/
};
enum {
   /* Apple Guide Apple events*/
   kAGEventDoCoach            = 'doco', /*coachmark event*/
   kAGEventDoHuh              = 'dhuh', /*huh event*/
   kAGEventGoNext             = 'gonp', /*go next event*/
   kAGEventGoPrev             = 'gopp', /*go previous event*/
   kAGEventHidePanel          = 'pahi', /*hide panel event*/
   kAGEventReturnBack         = 'gobk', /*return back event*/
   kAGEventShowPanel          = 'pash', /*show panel event*/
   kAGEventTogglePanel        = 'patg'  /*toggle panel event*/
};
enum {
   kAGFrontDatabase           = 1   /*refers to active guide file*/
};
enum {
   /*values returned by AGGetFrontWindowKind*/
   kAGNoWindow,                     /*guide file isn't open*/
   kAGAccessWindow,                 /*access window is showing*/
   kAGPresentationWindow            /*panel is showing*/
};
enum {
   /*values returned by AGGetStatus*/
   kAGIsNotRunning,           /*app portion of AG not in memory*/
   kAGIsSleeping,             /*app portion of AG in memory but */
                              /* no guide file is open*/
   kAGIsActive                /*app portion of AG in memory */
                              /* and a guide file is open*/
};
enum {
   /*guide file types, used by the functions AGFileGetIndDB */
   /* and AGFileGetDBCount, from AGFile*/
   kAGFileDBTypeAny           = 0,  /*any or all guide files*/
   kAGFileDBTypeHelp          = 1,  /*Help guide file*/
   kAGFileDBTypeTutorial      = 2,  /*Tutorial guide file*/
   kAGFileDBTypeShortcuts     = 3,  /*Shortcuts guide file*/
   kAGFileDBTypeAbout         = 4,  /*About guide file*/
   kAGFileDBTypeOther         = 8   /*Other guide file*/
};

Data Types

typedef unsigned long  UInt32;
typedef unsigned short UInt16;
typedef signed   short SInt16;
typedef UInt32 AGRefNum;
typedef UInt32 AGCoachRefNum;
typedef UInt32 AGContextRefNum;
typedef UInt16 AGStatus;
typedef UInt16 AGWindowKind;
typedef UInt32 AGEvent;
typedef SInt16 AGErr;
typedef struct AGAppInfo
{
   AEEventID      eventId;       /*event ID*/
   long           refCon;        /*reference constant*/
   void           *contextObj;   /*private*/
}
typedef struct AGAppInfo, *AGAppInfoPtr, **AGAppInfoHdl;
typedef pascal OSErr (*CoachReplyProcPtr)(Rect *pRect, Ptr name,
                                            long refCon);
typedef pascal OSErr (*ContextReplyProcPtr)
                        (Ptr pInputData, Size inputDataSize, 
                         Ptr *ppOutputData, Size *pOutputDataSize,
                         AGAppInfoHdl hAppInfo);
/*typedefs from AGFile*/
typedef FSSpec             AGFileFSSpecType;
typedef short              AGFileSelectorCountType;
typedef short              AGFileSelectorIndexType;
typedef OSType             AGFileSelectorType;
typedef long               AGFileSelectorValueType;
typedef short              AGFileDBType;
typedef ConstStr63Param    AGFileDBMenuNamePtr;
typedef short              AGFileDBScriptType;
typedef short              AGFileDBRegionType;
typedef short              AGFileMajorRevType;
typedef short              AGFileMinorRevType;
typedef short              AGFileCountType;

Functions

Starting Up Apple Guide

AGErr AGStart(void);
AGErr AGQuit(void);
AGStatus AGGetStatus(void);

Determining Which Guide Files Are Available

UInt32 AGGetAvailableDBTypes (void);
AGFileCountType  AGFileGetDBCount
   (short vRefNum, long dirID,
 AGFileDBType databaseType,
 Boolean wantMixin);
OSErr AGFileGetIndDB(short vRefNum, long dirID,
AGFileDType databaseType,
Boolean wantMixin,
short dbIndex, FSSpecType *fileSpec);

Opening and Closing Guide Files

AGErr AGOpen(FSSpec *fileSpec, UInt32 flags,
Handle mixinControl,
AGRefNum *resultRefNum);
AGErr AGOpenWithView (FSSpec *fileSpec, UInt32 flags,
Handle mixinControl,
short viewNum,
AGRefNum *resultRefNum);
AGErr AGOpenWithSearch(FSSpec *fileSpec, UInt32 flags,
Handle mixinControl,
ConstStr255Param searchString,
AGRefNum *resultRefNum);
AGErr AGOpenWithSequence(FSSpec *fileSpec, UInt32 flags,
Handle mixinControl,
short sequenceID,
AGRefNum *resultRefNum);
AGErr AGClose(AGRefNum *resultRefNum);

Working With Open Guide Files

Boolean AGIsDatabaseOpen(AGRefNum refNum);
AGWindowKind AGGetFrontWindowKind
      (AGRefNum refNum);
AGErr AGGeneral(AGRefNum refNum, AGEvent theEvent);
AGErr AGGetFSSpec(AGRefNum refNum, FSSpec *fileSpec); 
Getting Information About Guide Files
OSErr AGFileGetDBMenuName (AGFileFSSpecType *fileSpec,
AGFileDBMenuNamePtr menuItemNameStr);
OSErr AGFileGetHelpBalloonText
   (AGFileFSSpecType *fileSpec,
 Str255 helpMenuBalloonString);
OSErr AGFileGetHelpMenuAppCreator
   (AGFileFSSpecType *fileSpec,
 OSType *helpMenuAppCreator);
OSErr AGFileGetDBType (AGFileFSSpecType *fileSpec,
AGFileDBType *databaseType);
OSErr AGFileGetDBCountry (AGFileFSSpecType *fileSpec,
AGFileDBScriptType *script,
AGFileDBRegionType *region);
OSErr AGFileGetDBVersion (AGFileFSSpecType *fileSpec,
AGFileMajorRevType *majorRev, 
AGFileMinorRevType *minorRev);
AGFileSelectorCountType AGFileGetDBSelectorCount
   (AGFileFSSpecType *fileSpec);
OSErr AGFileGetSelector(AGFileFSSpecType *fileSpec,
AGFileSelectorIndexType selectorNumber,
AGFileSelectorType *selector, 
AGFileSelectorValueType *value);
Boolean AGFileIsMixin (AGFileFSSpecType *fileSpec,
AGFileDBMenuNamePtr menuItemNameStr);
OSErr AGFileGetMixinMatchSelector
   (AGFileFSSpecType *fileSpec,
 OSType *mixinMatchSelector);

Installing and Removing Coachmark Handlers

OSErr AGInstallCoachHandler(CoachReplyProcPtr CoachReplyProc,
 long refCon,
 AGCoachRefNum *resultRefNum);
OSErr AGRemoveCoachHandler(AGCoachRefNum *theRefNum);

Installing and Removing Context Check Handlers

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

Providing Object Locations for Coachmarks

pascal OSErr MyCoachReplyProc
                     (Rect *pRect, Ptr name, long refCon);

Responding to Context Checks

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

Result Codes

noErr	0	No error
dirNFErr	-12	Directory not found or incomplete pathname
nsvErr	-35	Volume doesn't exist
ioErr	-36	I/O error
fnOpnErr	-38	File not open
fnfErr	-43	File or directory does not exist
fLckdErr	-45	File is locked
rfNumErr	-51	Bad reference number
dirNFErr	-120	Directory not found or incomplete pathname
kAGErrCannotInitCoach	-2952	Unable to initialize coach handler
kAGErrCannotInitContext	-2953	Unable to initialize context handler
kAGErrCannotOpenAliasFile	-2954	Unable to open alias
kAGErrNoAliasResource	-2955	Unable to open resource alias
kAGErrDatabaseNotAvailable	-2956	Guide file is not available
kAGErrDatabaseNotOpen	-2957	Guide file is not open
kAGErrMissingAppInfoHdl	-2958	No application information handler
kAGErrMissingContextObejct	-2959	No context object
kAGErrInvalidRefNum	-2960	The guide file was opened by another application
kAGErrDatabaseOpen	-2961	No open guide file
kAGErrInsufficientMemory	-2962	Not enough memory
afpAccessDenied	-5000	User does not have the correct access to the file