96 PENPOINT ARCHITECTURAL REFERENCE Part 2 I PenPoint Application Framework
State Description
Not Installed The application is totally unknown to PenPoint. The user cannot create or turn to documents for the application, because the application class does not exist.
Installed The application appears on the Create menu. The user can create and turn to documents for the application.
The following sections describe application installation in broad strokes.
Application installation is described in more detail in Part 13: Installation API The transitions in Figure 8-1 are labeled. The user actions that cause these
transitions begin when the user turns to the Connections notebook in applications view and performs the following actions:
1 Checks the Install check box in the applications view of the Connections notebook. The PenPoint operating system loads the application .EXE file from disk into the loader database, and creates the application class.
2 Clears the Install check box to deinstall the application. The PenPoint operating system deletes the application class and removes the .EXE file from memory.
Installing an Application
The most important part of installing an application is creating the application class. Although most of your application contains methods (functions) that handle messages that documents can receive, your application is also responsible for sending msgNew to clsAppMgr to create a new application class.
When the user installs your application, the application installer loads the appli-cation executable file from a ,user-specified volume to the PenPoint computer. The object code isn't stored in the file system; rather, PenPoint stores the object code in an area of protected memory known as the loader database.
main in Application Installation
The installer calls the kernel function OSProgramlnstantiateO to create a process using your application and transfers control to your application's main routine, which is the process's entry point. main calls an application class initialization routine, which establishes space for the class instance data and declares the ancestor for instances of the class (usually clsApp).
main is the entry point for all application processes. OSProgramlnstantiateO passes three parameters to main, argc, argv, and appProcess, which is a UI6 that contains a process number. OSProgramInstantiateO assigns the process a process number of 0, because there are no other processes running this application code (at this time).
!
You create main and the application class initialization routine.
CHAPTER 8 / LIFE CYCLES 97 Application Class Life Cycle
If main finds that the process number equals 0, it calls initialization routines for the application class and any other classes used by the application class. Finally, it calls AppMonitorMainO, which starts the application monitor for the application class.
If main finds that the process number is greater than 0, the application calls AppMain, a routine provided by PenPoint, which creates a document for that application.
This example shows the main routine used by the Tic-Tac-Toe application:
main (
*
U16 processCount) if (processCount == 0) {
TttSymbolslnit();
StsWarn(ClsTttApplnit());
StsWarn(ClsTttViewlnit());
StsWarn(ClsTttDatalnit());
AppMonitorMain(clsTttApp, objNull);
else {
() ,:
~~ Application Class Initialization Routine
When main finds that the process number is 0, it calls the initialization routine for that application class (and initializes any other classes required by the application) .
The initialization routine for the application class creates an instance of clsAppMgr, which is the application class object.
The routine declares an APP _MGR_NEW structure, initializes it (by sending msgNewDefaults to clsAppMgr), modifies some of the arguments, and then sends msgNew to clsAppMgr.
8.1.1.2
You must write the application class initialization routine.
98 PENPOINT ARCHITECTURAL REFERENCE.
Part 2 I PenPoint Application Framework
This example shows the applications class initialization routine for the Tic-T ac-Toe application.
new.appMgr. ,accessory false;
strcpy(new.appMgr.companYf IlGO );
/1 213 (octal) is the ncircle-c n new. = "\213 1992 GO
ObjCaIIJmp(msgNew, clsAppMgr, &new, s, Error);
return stsOK;
Error:
return S;
All Reserved,";
The message arguments specify the application class's well-known UID and ancestor (which for applications is almost always clsApp), the name of the application, its initial state (whether it is a floating document, whether it runs in hot mode, and so on), the size of its instance data, and the ID of its method table.
If new. appMgr. defaultDocName contains pNull, the PenPointApplication Framework will look for the default document name in
tagAppMgrDefaultDocName in the resource file APP.RES. This allows you to localize your default document names by having different resource files (and thus a different tagAppMgrDefaultDocName) for different languages or locales.
Because the application class uses a process, it can have a full-scale environment, just like an application instance. This environment includes a floating window list and initialized local copies of theProcessResList and theUndoManager. Using this environment, your process 0 can actually provide its own user interface, if
necessary for altering application-global ~ettings. However, most of the time this overhead is unnecessary. When you don't need a full enviroment for process 0, set the fullEnvironment flag to false.
At this point, the process can send messages, but it has no object that can receive messages.
CHAPTER 8 I LIFE CYCLES 99 Application Class Life Cycle
clsAppMgr creates the new object by sending msglnit to its ancestor, clsClass.
clsClass creates an application class object (an instance of clsAppMgr) for process O. The new application class can now receive messages as well as send them.
clsClass then sends msglnit to the new instance of clsAppMgr (the application class object). In response to msglnit, the application class sends msglnit to its ancestor (clsClass) and then allocates and initializes its instance data.
When msglnit returns from clsClass, clsAppMgr initializes the instance data that your application class will use to create instances of itself (documents). The instance data includes your application name, your company's name, your icon, the initial size and location for floating documents (if floating), whether it is a hot mode application or not, and whether the user can create instances of it or not.
(Some applications, such as device drivers, should not be user-creatable.)
".,.. AppMonitorMainO in Installation
The last step that main executes in installing an application class is to create an application monitor in your application class.
The application monitor is an object in your application class that helps to maintain installation information about the application, including the UID of the application manager object and the location of the application's home.
You create the application monitor by calling AppMonitorMainO. The
application monitor is described in Chapter 13, The Application Monitor Class.