Legacy Document

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

Chapter 9 - Apple Guide API / Working With Open Guide Files

/

AGGeneral

Use the AGGeneral function to perform actions on an open guide file.

AGErr AGGeneral (AGRefNum refNum, AGEvent theEvent);

refNum

A reference number of an open guide file.

theEvent

A four-character sequence that indicates the action to perform. (These actions correspond to Apple Guide Apple events.) You specify the action using one of these constants:

            enum {
            /*Apple Guide Apple events for guide files*/
               kAGEventDoCoach   = 'doco', /*coachmark*/
               kAGEventDoHuh     = 'dhuh', /*Huh? topic*/
               kAGEventGoNext    = 'gonp', /*go next*/
               kAGEventGoPrev    = 'gopp', /*go previous*
               kAGEventHidePanel = 'pahi', /*hide panel*/
               kAGEventReturnBack= 'gobk', /*return back*/
               kAGEventShowPanel = 'pash', /*show panel*/
               kAGEventTogglePanel= 'patg' /*toggle panel*/
            };

DESCRIPTION

The AGGeneral function sends an Apple event to Apple Guide, which then performs the requested action on the guide file specified in the refNum parameter.

The parameter theEvent specifies the action to perform, as indicated by the particular Apple event constant. You can specify any of these seven types of Apple events to perform the corresponding action related to an open guide file:

• kAGEventDoCoach, to draw a coachmark that exists for the active panel of the open guide file
• kAGEventDoHuh, to open a Huh? topic that belongs to the active panel of the open guide file
• kAGEventGoNext, to go to the next panel
• kAGEventGoPrev, to go to the previous panel
• kAGEventShowPanel, to expand the active panel
• kAGEventTogglePanel, to collapse or expand panel
• kAGEventReturnBack, to return from an Oops panel

You can direct Apple events only to a guide file that was opened by your application. If you attempt to direct an event to a guide file that was not opened by your application, the AGGeneral function returns a nonzero result code.

RESULT CODES

noErr	0	No error
kAGErrDatabaseNotOpen	-2957	Guide file is not open
kAGErrInvalidRefNum	-2960	The guide file was opened by another application