Most source code in PenPoint has a similar structure. Although Empty Application is a very simple application, it has a similar layout to other applications.
Remember that application programs have at least one class (the application class itself), so an application program is composed of at least these two files:
• The
method table
that specifies the messages to which this class responds and the functions that handle those messages6.5
6.5.1
• The C source code for the class. The C source code for applications is usually organized in the following .way:
• :ftdefines and typedefs
• Message handlers
• Class initialization routine
• main entry point.
The method table file always has the suffix .TBL. It looks like C code, but you process it with the method compiler MT before linking it into your program.
Method Table File
The method table file lists all the messages that the class handles. The PenPoint Class Manager sends any messages not listed in the method table to the class's ancestor for handling (and possibly to the ancestor's ancestor). Looking at a class's method table gives you a good feel for what the class does.
A single method table file can have method tables for several different classes. The names of the method tables are usually pretty self-explanatory, for example, clsEmptyAppMethods is Empty Application's method table.
You can still have one function that handles several different messages, by using the wild-card capabilities of method tables. Method table wild cards match any message within a given set of messages and call the associated method. Method table wild cards are described in Part 1: Class Manager of PenPoint Architectural Reference, Volume I
Application C Code File
The application's main routine is at the end of the source file. The operating system calls the application's main routine under two circumstances:
• When installing the application (this happens only once)
• When activating individual documents (this happens each time the user turns to or floats a document that uses the application).
The C files for non-application classes don't have main routines, because only applications actually start C processes. The declaration for the main routine is:
main (argc, argv, processCount)
The argc and argv parameters are not used in PenPoint. PenPoint uses the processCount parameter to pass in the number of processes running this application. When processCount is 0, there are no other processes running this application; this indicates that PenPoint is installing the application. Once an application is installed, the process that has a process Count of 0 stays in memory until the application is deinstalled.
On installation, main initializes the application class, by calling an initialization routine. This routine precedes main in the source file. Standard practice is to name this routine using the name of the application class (with an initial capital
CHAPTER 6 I A SIMPLE APPLICATION (EMPTY APP) 99
letter), followed by "Init". For example, the initialization routine for clsEmptyApp is ClsEmptyAppInit.
When the initialization routine creates the application class, it specifies the method table used by the application class.
In the method table, you establish a relationship between the messages that your class handles and the name of a function in your C code file that handles each message. These functions are called message handlers and are similar to the
"methods" of other object-oriented systems. Message handlers should be local static routines that return STATUS. If your class does handle a message, the method table also indicates whether the Class Manager should call your class's ancestor before or after (if at all).
Code Run·Through
".,.. Message Handler Parameters 6.5.1.3
Because the Class Manager calls your message handlers, you don't get to choose message handler parameters. The arguments passed to all message handlers are:
msg The message itself.
self The object that received the message.
pArgs The message argument. This 32-bit value can be either a single argument or a pointer to a structure containing a number of arguments.
ctx A context maintained by the Class Manager.
pData The instance data of self.
Because the parameters to message handlers are always the same,
\PENPOINT\SDK\INC\CLSMGR.H defines several macros to generate standard message handler functions, given only the function name (MsgHandler), or given the function name and types to cast its arguments to (msgHandlerWithTypes).
At the beginning of an application source file are these items: .
• hnclude directives for the header files required by the application
• The internal routines used by your application's methods
• Internal :/tdefines, and so on.
"" Empty Application's Source Code
Here's an abstract of the Empty Application's C code and method table file:
".,.. Method Table
The method table file, METHODS.TBL, specifies that Empty Application has one message handler; clsEmptyApp handles msgDestroy in a function called
EmptyAppDestroy.
MSG_INFO clsEmptyAppMethods [1 = {
#ifdef DEBUG msgDestroy,
#endif
o
} ;
"EmptyAppDestroy", objCallAncestorAfter,
6.5.2
6.5.2.1
The #ifdef and #endif statements cause the message handler to be defined only when you specify /DDEBUG in the compiler options.
,..,.,. C Source Code
There are three significant parts ofEMPTYAPP.
c:
• The main routine, which handles application installation and application startup
• The initialization routine, which is invoked by main at installation time
• The message handler for msgDestroy, which was specified in the method table.
This section presents this code without further comment. Subsequent sections in this chapter examine the code in detail.
The main routine for EMPTYAPP.C is:
6.5.2.2
1***************************************************** ***********************
main·
Main application entry point (as a PROCESS -- the app's MsgProc is where messages show up once an instance is running) .
****************************************************************************1 void CDECL
main (
int argc,
char
*
U16
argv[] , processCount)
Dbg(Debugf("main: starting emptyapp.exe[%d]", processCount);) if (processCount == 0) (
}
II Create application class.
ClsEmptyApplnit();
II Invoke app monitor to install this application.
AppMonitorMain(clsEmptyApp,objNull);
else
II Create an application instance and dispatch messages.
AppMain();
II SUI'press compiler's "unused parameter" warnings Unused(argc); Unused(argv);
1* main *1
The initialization routine invoked by main on installation is:
1****************************************************************************
ClsEmptyApplnit
Install the EmptyApp application class as a well-known UID.
****************************************************************************1 STATUS
ClsEmptyApplnit (void)
{
CHAPTER 6 I A SIMPLE APPLICATION (EMPTY APP) 101
new.cls.newArgsSize = SizeOf(APP_NEW);
new.appMgr.flags.accessory = true;
strcpy (new. appMgr . company, "GO Corporation" )';
str,cpy (new. appMgr. defaultDocName, "Empty App Document");
ObjCallJmp(msgNew, clsAppM9r, &new, s, Error);
II II
Turn on message tracing if flag is set.II
if (DbgFlagGet('F', OxlL»
Debugf("Turning on message tracing for clsEmptyApp");
(void)ObjCaIIWarn(msgTrace, clsEmptyApp, (P_ARGS) true);
return stsOK;
Error:
return s;
} 1* ClsEmptyAppInit *1
Finally, the message handler for msgDestroy is:
Code Run-Through
MsgHandlerParametersNoWarning;