APP METRICS am;
STATUS s;
DbgTttAppClose ( ("") ) II
II Get the frame. Extract the menu bar from the frame. Then II free the menu bar.
II
ObjCallJmp(msgAppGetMetrics, self, &am, s, Error);
ObjCallJmp(msgFrameDestroyMenuBar, am.mainWin, pNull, s, Error);
DbgTt tAppClose ( ( "ret urns stsOK")) return stsOK;
MsgHandlerParametersNoWarning;
Error:
DbgTttAppClose (("Error; return Ox%lx", s)) return s;
1* TttAppClose *1
Terminating a Document
Usually, when the Notebook doses a document, it also terminates the document process (unless there is a window with an active selection or the document is running in hot mode).
If there was a window with an active selection and the user taps elsewhere in the Notebook, the selection is lost and termination continues.
The Notebook does not terminate a hot-mode document until the user deletes it.
The Notebook terminates a document by sending it msgFree.
msgFree
When your application receives msgFree, it should free any objects that it has created and release any data allocated from heap.
Your application's method table should call ancestor after handling msgFree.
When dsApp receives msgFree, it sends msgAppSave to self (the document). Your
8 .. 2 .. 5.1
You must write a method to handle m5~Free.
CHAPTER 8 I LIFE CYCLES 111
application should not handle msgAppSave. If you omit msgAppSave from the method table, the class manager will send it to clsApp.
When clsApp receives msgAppSave, it performs the following tasks:
1 Tells the embedded documents to save themselves (by self-sending msgAppSaveChildren to each one).
2 Sends msgNew to clsResFile to create a handle on the document state resource file in the document's directory. Note that when clsApp sends msgNew to clsResFile, it specifies "truncate-on-open," that is, delete all information in the file. From this point, until all objects have saved their information in the file, a drastic failure (such as loss of power or a crash) in the computer could cause a loss of data.
If data integrity is important, your application could copy its resource file when it receives msgAppSave (provided it knows the name of the resource file).
Document Life Cycle
When clsResFile receives msgNew, it writes a resource file header to the file.
3 Sends msgResW riteObject to the resource file handle and specifies self as the object to file. When the resource file handle receives msgResWriteObject, it:
Writes a resource file header that identifies the object.
Sends msgSave to the document. Your application's responsibilities for msgSave are described below.
When msgSave completes, the resource manager updates the number of bytes written to the resource file and returns stsOK for msgResWriteObject.
4 When msgResWriteObject returns, clsApp closes the resource file.
S Finally, clsApp sends msgAppTerminateProcess to your document. Allow your ancestor to handle this message, which terminates the document process.
When the document process terminates, the only thing that remains is the directory in the file system, the resource file in the directory, and the resource files for the document (plus any other files created by your document). Figure 8-6 shows what remains of the document.
112 PENPOINT ARCHITECTURAL REFERENCE Part 2 / PenPoint Application Framework
This example shows the method used by the Tic-Tac-Toe application to handle msgFree.
#define DbgTttAppFree(x) \
TttDbgHelper("TttAppFree",tttAppDbgSet,Ox4,x)
MsgHandlerWithTypes(TttAppFree, P_ARGS, PP TTT_APP_INST)
{
DbgTttAppFree «"")) OSHeapBlockFree(*pData);
DbgTttAppFree «"returns stsOK")) return stSOKi
MsgHandlerParametersNoWarningi /* TttAppFree */
msgSave
msgSave passes an OBJ_SAVE structure, which contains a handle on the file where you must store your data.
Your application's method table should call ancestor before handling msgSave.
msgSave initiates the following process:
1 When clsApp receives msgSave, it does a ObjectCallAncestor to file its instance data.
2 When ObjectCallAncestor returns, clsApp sends msgResWriteObject to the resource file handle with the document's main window as the object.
3 clsWin files any of its child objects that have wsSendFile set.
4 clsFrame files its client view, if the view has wsSendFile set.
S The view receives msgSave and saves its instance data (the UID of its data object).
6 The view sends msgResPutObject or msgResWriteObject to its data object.
This files your window data and its client window. Because views file their corresponding data objects, your document doesn't have to save these objects.
When your application receives msgSave, it should save its instance data by sending msgStreamWrite to the resource file handle; the pArgs indicate the data to save.
Finally, your application should save its stateful objects by sending msgResWriteObject or msgResPutObject to the resource file handle; the pArgs indicate the object to save. These resource file messages then send msgSave to the specified object.
8.2.5.2
You must write a method to handle msg5ave.
CHAPTER 8 I LIFE CYCLES 113 Document Life Cycle
This example shows the method for msgSave used by the Tic-Tac-Toe application.
/****************************************************************************
TttAppSave
Save self to a file.
****************************************************************************/
#define DbgTttAppSave(x) \
TttDbgHelper("TttAppSave",tttAppDbgSet,Ox8,x)
MsgHandlerWithTypes(TttAppSave, P_OBJ_SAVE, PP TTT APP_INST)
{
TTT_APP_FILED_O filed;
STATUS s;
DbgTttAppSave ( (" ") )
StsJmp (TttUtilWriteVersion (pArgs->file, CURRENT VERSION), s, Error);
TttAppFiledDataOFromInstData(*pData, &filed);
StsJmp(TttUtilWrite(pArgs->file, SizeOf(filed) , &filed), s, Error);
DbgTttAppSave (("returns stsOK"»
return stsOK;
MsgHandlerParametersNoWarning;
Error:
DbgTttAppSave (("Error; return Ox%lx", s»
return s;
/* TttAppSave */
Reactivating a Document
If the user turns back to the document, the notebook sends msgAppMgrActivate to your application class. Processing is just the same as in document activation.
However, instead of sending msgAppInit to self, clsApp responds to msgAppActivate by self-sending msgAppRestore.
Your application shouldn't handle msgAppRestore. Omit the message from your method table so that the class manager will pass it to your application's ancestor, clsApp.
When clsApp receives msgAppRestore, it starts the cascade of events that causes all objects in a document to load themselves:
l O n e of the msgAppRestore arguments is a directory handle. When clsApp receives msgAppRestore, it looks in the directory for a resource file. When it finds the resource file, it opens it by sending msgNew to clsResFile.
2 When clsResFile receives msgNew, it opens the file. If the resource file index is saved in the file, clsResFile reads it in. If the index does not exist, clsResFile creates one.
3 When the msgNew returns, clsApp sends msgResReadObject to the resource file handle, specifying self as the object to restore.
msgResReadObject sends msgRestore to the document.
4 As described below, your application's method table passes msgRestore to its ancestor first, which causes windows and client views with wsSendFile set to receive msgRestore. The object then reads its state information and uses msgResGetObject to re-create its objects.
114 PENPOINT ARCHITECTURAL REFERENCE Part 2 / PenPoint Application Framework
5 clsApp determines the name of the directory and resource file, creates a file handle on the resource file, and sends msgResReadObject to the resource file handle. The pArgs for msgResReadObject indicates self is the object to read.
msgRestore
msgResReadObject sends msgRestore to self (the document); the pArgs includes the handle on the resource file.
Your application's method table should pass msgRestore to its ancestor before handling it, which causes the main window to read its instance data. The main window also tells all its subwindows to read their objects back in. (This is similar to how the main window uses msgSave to save all of its subwindows.)
When your application receives msgRestore, it should read its instance data from the resource file (by sending msgStreamRead to the resource file handle) and should restore its stateful objects (by sending msgResReadObject to the resource file handle).
When your application reads the instance data, the data is local to the method. To write that local copy to protected memory, you must call ObjectWriteO.
This example shows the method for msgRestore used by Tic-Tac-Toe.
You must write the method to
#define DbgTttAppRestore(x) \
TttDbgHelper("TttAppRestore",tttAppDbgSet,OxlO,x)
MsgHandlerWithTypes(TttAppRestore, P_OBJ_RESTORE, PP TTT_APP_INST)
{
P_TTT_APP_INST pInst;
TTT_APP FILED_O filed;
STATUS s;
TTT VERSION version;
DbgTttAppRestore ( (" ") )
II II
Initialize for error recovery.StsJmp (TttUtilReadVersion (pArgs->file, MIN_VERSION, MAX_VERSION, \
&version), s, Error);
StsJmp(TttUtilRead(pArgs->file, SizeOf(filed) , &filed), s, Error);
StsJmp (OSHeapBlockAlloc (osProcessHeapId, SizeOf(*pInst), &pInst), \ s, Error);
TttAppInstDataFromFiledDataO(&filed, pInst);
CHAPTER 8 I LIFE CYCLES 115 Document Life Cycle
ObjectWrite{self, ctx, &plnst);
DbgTttAppRestore ({"returns stsOK")) return stsOK;
MsgHandlerParametersNoWarning;
Error:
if (plnst) {
OSHeapBlockFree{plnst);
DbgTttAppRestore{{"Errori returns Ox%lx",s)) return Si
/* TttAppRestore */
,.". Deleting a Document
When the user deletes a document from the Notebook, the Notebook sends msgAppMgrDelete to the application class, indicating the directory of the document to be deleted.
msgAppMgrDelete searches the document's directory for embedded documents.
For each embedded document, msgAppMgrDelete sends msgFree to each embedded document (if it exists), terminates the document processes (if it exists), and deletes the document's directory.
8.2.7
Chapter 9 / Elllbedded Doculllents
One of the features that differentiates the PenPoint™ operating system from many other operating systems is that components can contain other components. Both the containing component and the contained component can have views on their data. The contained component with a view on its data is called an embedded window.
Chapter 9 covers these topics:
• Embedded window marks.
• Descendants of clsEmbeddedWin.
• Moving and copying between embedded windows.
• Creating and destroying embedded windows.
• Moving or copying to an embedded window.
• Handling child embedded windows.
• Selecting an embedded window.