To remove an application from the PenPoint computer, the user deinstalls the application.
Deinstalling an application removes the program from the loader database and removes the application directory and the application's attributes from the file system. To use the application again, the user must reinstall the program, its resources, and all other files.
~ msgFree in Deinstallation
When the user deinstalls your application, the installer program sends msgFree to your application class, which destroys the application class object.
clsAppMgr's routine to handle msgFree first calls ancestor to free itself, then it removes itself from the list of installed applications, and broadcasts its
deinstallation to all observers of clsApp.
PenPoint provides the method for handling meglnit received by an application class (because it is an instance of c;leAppMgr).
The new class object is an instance of c;leAppMgr. Thus, any messages received by your application class are handled first by the methods defined in c;leAppMgr.
8 .. 1.1.3
8 .. 1.2
1
PenPoint provides the method for megFree in deinstallation.
100 PENPOINT ARCHITECTURAL REFERENCE Part 2 I PenPoint Application Framework
". Doculllent Life Cycle
This section describes the life cycle for a document.
Figure 8-2 shows the states of a document; Table 8-2 describes the states shown in Figure 8-2.
State
Non-Existent Created Activated Opened Dormant
The document does not exist, nor does it have a directory. There is no resource file for the document.
A directory exists for the document.
A process exists, the process contains a document object, and the application data has been either initialized or restored.
The document is displayed on the screen.
A directory exists for the document, the application data is stored in a resource file, but there is no process and no document object.
CHAPTER 8 I LIFE CYCLES 101 Document Life Cycle
Created and dormant states are similar, because in those states there is a directory, but there is no process. However, in the created state there is no resource file; in dormant, there is.
The transitions shown in in Figure 8-2 are labeled. The user actions that cause these transitions are:
1 The user taps on the Create menu and chooses this application. The PenPoint Application Framework creates a directory for the document.
2 The user deletes the document before turning to the document. The PenPoint Application Framework deletes the document directory.
3 The user turns to the page containing the document. The PenPoint Application Framework starts the document process, creates a document object in the process, and initializes the document's data. If the document displays itself on screen, processing continues with transition 4.
Normally, transition 4 occurs immediately after transition 3 or transition 7 without additional user action. This transition can also occur when the user turns to a document running in hot mode or returns to a document that has an active selection.
4 The PenPoint Application Framework creates the document's main window and its views, and displays the document on screen.
S The user turns to another page. The PenPoint Application Framework removes the document from the screen and destroys its view objects. If the user didn't have anything selected and the document is not in hot mode, processing continues with transition 6.
6 If the user didn't have anything selected, this step continues from transition 5. This transition is also made if the user had something selected and then tapped anywhere on another page. The PenPoint Application Framework saves the document's data and shuts down the process.
7 The user turned back to the document. The PenPoint Application
Fram~work starts a new application process and reads the document data from the resource file. Usually when the document reaches the activated state, it continues on transition 4 to the opened state.
S The user deleted the document. The PenPoint Application Framework deletes the resource file and removes the document directory.
The following sections describe how the PenPoint Application Framework works to create, save, and destroy instances of your document.
102 PENPOINT ARCHITECTURAL REFERENCE Part 2 / PenPoint Application Framework
Creating a Document
When the user taps on the Create menu or chooses an item on the Stationery menu, the Notebook sends msgAppMgrCopy to your application class.
msgAppMgrCopy creates a new subdirectory in the directory specified in the message.' The message also stamps the directory with an attribute that indicates the application class that will use this directory.
At this point, the page exists in the Notebook Table of Contents, but does not contain any data, nor does any process exist for the document. The user might turn to the document immediately or might continue working on the current document.
Activating a Document
When the user turns the page to a document, the Notebook locates the directory that corresponds to that document and finds the directory attribute that identifies the document's application class. The Notebook then sends msgAppMgrActivate to the application class.
Although this discussion centers on the Notebook, any application can start any other application in just the same way, that is, by sending msgAppMgrActivate to an application class. msgAppMgrActivate spawns a new process by calling
OSProgramlnstantiateO.
Because there is at least one other process running the same application code (the application class), OSProgramlnstantiateO increments the last process number that it generated and passes the new process number to that new process.
The process number merely distinguishes this process from other processes running the same application code. It does not indicate the number of times that the document has been reactivated, nor does it indicate the number of processes simultaneously running the application code.
~ main in Activation
The entry point for the new process is mainO. msgAppMgrActivate transfers control to the new process at mainO. Because the process number is greater than zero, main transfers control to AppMainO. In AppMainO, the process waits to receive something.
If the application has process-private classes, it creates and initializes the classes with separate initialization routines before calling AppMainO.
8 .. 2.1
PenPoint provides megAppMgrCreate.
PenPoint provides megAppMgrActivate.
You write mainO and the class initialization routines;PenPoint provides AppMainO.
CHAPTER 8 / LIFE CYCLES 103 Document Life Cycle
This mainO comes from the Tic-Tac-Toe application (TTTAPP.C).
void CDECL main (
int char '*
U16
arge ,
a:rgv[] f
processCount) if (processCount == 0)
}
0;
StsWarn ());
StsWarn(ClsTttViewInit());
else { AppMain();
,,'-""', ... "''''-' •• ,-<.'-' 0 ) ..
II Suppress compiler's "unused parameter" warnings Unused(argc)i Unused(argv)i
1* main *1
At this point, the document consists of the 'items shown in Figure 8-3. The document directory exists and there is a process for the document.
8m3
New Document Process
msgAppMgrActivate in Activation
In the meantime, the msgAppMgrActivate that was sent by the Notebook builds a pArgs structure for msgNew and sends it to the new document process, using one of the kernel's ITC (inter-task communication) messages. (The process does not yet contain a document object to receive messages. That is why msgAppMgrActivate uses an ITC message.) The new process (which we last left waiting in AppMain), receives the pArgs and uses them to send a msgNew to your application class, using the arguments received in the ITC message.
Your application class handles msgNew by calling its ancestor, clsClass, which creates a document object (an instance of your application class) in the new process, and sends msglnit to the new object.
Because your application class is an instance of clsAppMgr.
clsAppMgr defines the method for handling msgNew.
104 PENPOINT ARCHITECTURAL REFERENCE Part 2 / PenPoint Application Framework
msglnit in Activation
Your application's method table for msglnit directs the class manager to pass the message to your ancestor (clsApp) before passing it to your method.
When clsApp receives msglnit, it opens the document's directory in the file system, allocates memory for the document's instance data, zeros the allocated memory, performs some housekeeping, updates its own instance data, and returns.
8.2.2.3
When your document receives msglnit, it initializes its instance data and saves the You must define a method for
instance data in protected memory by calling ObjectWriteO, and then returns. m5ftlnit in your application.
The instance data and application directory handle are both examples of
activate-to-terminate objects that do not have state. That is, they do not need to be saved when the document terminates.
When your application initializes the instance data, the data is local to the method. However the instance data maintained by the class manager is in
protected memory. To update the protected instance data with the local copy, call the function ObjectWriteO. ObjectWriteO stores the instance data in protected memory, where it will stay until the process is terminated.
This example shows the method for msglnit used by the Tic-T ac-T oe application.
1****************************************************************************
TttAppInit
Initialize instance data of new object.
Note: clsrngr has already initialized instance data to zeros.
****************************************************************************1
#define DbgTttAppInit(x) \
TttDbgHelper("TttAppInit",tttAppDbgSet,Ox2,x)
StsJrnp(OSHeapBlockAlloc(osProcessHeapId, SizeOf(*pInst), &pInst), \ s, Error);
pInst->placeHolder = -1L;
ObjectWrite(self, ctx, &pInst);
DbgTttAppInit (("returns stsOK")) return stsOK;
MsgHandlerPararnetersNoWarning;
Error:
if (pInst) {
OSHeapBlockFree(pInst);
DbgTttAppInit (("Error; returns Ox%lx", s)) return s;
1* TttAppInit *1
CHAPTER 8 I LIFE CYCLES 105 Document Life Cycle
msgAppActivate and msgApplnit
When the msgNew sent by AppMainO returns, AppMainO sends msgAppActivate to the document. You shouldn't define a method for msgAppActivate; let dsApp handle it.
8.2.2.4
Reminder If you don't list a message in your method table, the class manager
automatically sends it to your ancestor.
If this is the first time the document has been opened, msgAppActivate sends You must write a method for
msgApplnit and msgAppSave to the document; if the document has been opened m5gApplnit. If your document has instance data or creates
before, msgAppActivate sends msgAppRestore to the document. objects, you must also write
• Your application's method table should call ancestor (dsApp) before handling msgApplnit. dsApp creates the resource file and creates the main window.
When the message returns from dsApp, your method should create and initialize any objects that both have instance data and that you need to save.
For example, if your application uses an instance of dsText, it should create it and load any initial text at this time.
• Your application's method table should call ancestor before handling msgAppSave. This will result in the document receiving msgSave. The method for msgSave should save the document's instance data and any stateful objects to the resource file. msgSave is described later.
• Your application's method table should call ancestor before handling
msgAppRestore. This will result in the document receiving msgRestore. The method for msgRestore should restore the document's instance data and any stateful objects from the resource file. msgAppRestore and msgRestore are described later.
This example shows the method for msgApplnit for the Tic-Tac-Toe application.
methods for m5g5ave and m5gRe5tore.
1****************************************************************************
TttAppAppInit
Respond to msgAppInit. Perform one-time app life-cyle initializations.
****************************************************************************1
#define DbgTttAppAppInit(x) \
TttDbgHelper("TttAppAppInit",tttAppDbgSet,Ox20,x) MsgHandlerWithTypes(TttAppAppInit, P_ARGS, PP TTT APP_INST)
{
DbgTttAppAppInit ( (" ") ) II
II Initialize for error recovery.
II
tttViewNew.object.uid = objNull;
, scrollWin = objNull;
responsibleForView = false;
responsibleForScrollWin = false;
106 PENPOINT ARCHITECTURAL REFERENCE Part 2 I Pen Point Application Framework
II II
Create and initialize view. This creates and initializesII
data object as well.II
ObjCallJmp(msgNewDefaults, clsTttView, &tttViewNew, s, Error);
ObjCallJmp(msgNew, clsTttView, &tttViewNew, s, Error);
responsibleForView = true;
II II
Check for stationery.II
ObjCallJmp(msgViewGetDataObject, tttViewNew.object.uid, \
&dataObject, s, Error);
StsJmp(TttAppCheckStationery(dataObject), s, Error);
II II
Create and initialize scrollWin.II
StsJmp (TttUtilCreateScrollWin (tttViewNew.object.uid, &scroIIWin), \ s, Error);
responsibleForScrollWin = true;
responsibleForView = false;
II II
Make the scrollWin be the frame's client win.II
ObjCallJmp(msgAppGetMetrics, self, &am, s, Error);
ObjCallJmp(msgFrameSetClientWin, am.mainWin, (P_ARGS)scroIIWin, s, Error);
responsibleForScrollWin = false;
DbgTttAppApplnit (("returns stsOK")) return stsOK;
MsgHandlerParametersNoWarning;
Error:
if (responsibleForView AND tttViewNew.object.uid) (
ObjCallWarn(msgDestroy, tttViewNew.object.uid, pNull);
if (responsibleForScrollWin AND scrollWin) { ObjCallWarn(msgDestroy, scrollWin, pNull);
DbgTttAppApplnit (("Error; returns Ox%lx", s)) return S;
1* TttAppApplnit *1
clsApp also activates any embedded documents in the document being activated, sets its priority, and returns.
Figure 8-4 shows the document at this point. The document process now contains a number of the objects necessary for the document to be active in the PenPoint Application Framework, however it doesn't have any instances of
non-stateful components (such as views on data and user interface control objects).
CHAPTER 8 I LIFE CYCLES 107 Document Life Cycle
Document
with
UrUe,![f§;When msgAppActivate returns, AppMainO opens the document by sending msgAppOpen to the new document.