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