AppleGuide with PowerPlant
Volume Number: 13
Issue Number: 10
Column Tag: Electronic Documentation
Using Apple Guide with PowerPlant and MacApp
by Marcelo Lombardi
About the Apple Guide Framework
The provided Apple Guide framework can be used to minimize the code-writing effort
required to incorporate Apple Guide into MacApp or PowerPlant applications. It
includes support for coaching views, panes, and default context-checking classes for
both frameworks. Two examples are provided. This article, was divided into four main
sections: (1) Understanding the framework: explains the components of the Apple
Guide Framework; (2) Using the framework: provides an overview of the sample
applications that are available on-line; (3) PowerPlant example: shows how to use the
framework to incorporate Apple Guide in PowerPlant applications; (4) MacApp
example: shows how to use the framework to incorporate Apple Guide in MacApp
applications; (5) Creating a guide file: provides very simple introduction to writing
guide files. This article assumes a basic knowledge of PowerPlant and/or MacApp.
Requirements
CodeWarrior 9 or higher, and either MacApp 3.3 or PowerPlant.
Understanding the Framework
The framework is composed of three sets of classes (see Figure 1). First, the Apple
Guide classes implement the required toolbox initialization calls, determine the
availability of Apple Guide, manage coach and context replies, open and close the help
window, and terminate the Apple Guide session. Secondly, the utility classes are very
simple classes that implement common programming tasks. In this area CA5World gets
the current A5 and restores the global A5. CHandleLock, locks and restates the state of
a handle. COSType is a class implementation of the OSType data type, and converts
char*'s to OSTypes and viceversa. CProcess obtains information about the current
process. Finally, if you are using PowerPlant, CBroadcasterWindow broadcasts a
message to tell its listener when it becomes active or inactive;
TBroadcasterWindowMA accomplishes the same function using MacApp's dependency
mechanism.
In this section, a brief overview of the AppleGuide, and the MacApp/PowerPlant
subclasses will be provided.
Figure 1. Apple Guide Framework Class Tree.
Your application will only create one CAppleGuide object. To create it, you must
initialize it by calling Initialize with the name of the Apple Guide file and the
four-byte identifier of the context handler. Initialize calls InstallContextHandler and
InstallCoachHandler which installs the context-checking and coach handling
procedures respectively. InstallContextHandler calls AGInstallContextHandler passing
a reference to the CAppleGuide object. InstallCoachHandler calls AGInstallCoachHandler
passing a reference to the CAppleGuide object. Now, when the static proc pointers
ReplyToContext or ReplyToCoach are called, they can use the reference to the
CAppleGuide to call DoReplyToContext or DoReplyToCoach. This is done for two reasons:
First, you need to be able to dispatch the call to the current reply object associated
with the frontmost document. Secondly, it provide a means for mimicking a "virtual
proc pointer", should the need for overriding CAppleGuide ever arise. Finally,
SetCoachHandler and SetContextHandler install the appropriate coach-handling and
context-handling objects depending on which window is in front. Here is how this
works:
//
// Replying mechanism from CAppleGuide.cp
//
// ReplyToCoach dispatches the call to the virtual member
// DoReplyToCoach
pascal OSErr
CAppleGuide::ReplyToCoach(Rect* pItemRect, Ptr pName, long refCon)
{
OSErr result = kAGErrItemNotFound;
CA5World anA5World;
CAppleGuide* anAppleGuide = (CAppleGuide*) refCon;
if(anAppleGuide)
{
if(anAppleGuide->DoReplyToCoach(pName, pItemRect))
result = noErr;
}
return(result);
}
// DoReplyToCoach lets the appropriate fCoachHandler ( perhaps the one
assoicated with
// the frontmost document ) handle the reply
Boolean CAppleGuide::DoReplyToCoach( Ptr inName, Rect* ioItemRect)
{
if(fCoachHandler)
return fCoachHandler->DoReplyToCoach( inName, ioItemRect);
return false;
}
//
// Header file CAppleGuide.h
//
class CAppleGuide
{
public:
/
// construction/destruction
CAppleGuide();
virtual ~CAppleGuide();
void Initialize( Str63& inName, OSType inContextID);
// API
virtual void OpenGuide();
virtual Boolean IsFrontProcess();
void SetCoachHandler(CCoachHandler * inCoachHandler);
void SetContextHandler(CContextHandler * inContextHandler);
// Accessor (can we run apple Guide ? )
Boolean CanRun();
protected:
virtual void GetProcessInfo();
virtual OSErr InstallContextHandler();
virtual OSErr InstallCoachHandler();
static pascal OSErr ReplyToContext( Ptr pInput,
Size inputDataSize,
Ptr *ppOutput,
Size *pOutputDataSize,
AGAppInfoHdl hAppInfo );
static pascal OSErr ReplyToCoach( Rect* pItemRect,
Ptr pName,
long refCon );
// You can override DoReplyToContext and/or DoReplyToCoach but
// it is better if you subclass CCoachHandler and/or
// CContextHandler
virtual Boolean DoReplyToContext( const AEEventID& inEventID,
const OSType& inID);
virtual Boolean DoReplyToCoach( Ptr inName,
Rect* ioItemRect);