how your application initializes itself, the user will now see the application in the
Accessories window, or in the Stationery- notebook and Stationery pop-up menu.
E ...
u Z
o u Z
·After installation, your code is in a similar state to an MS-DOS .EXE or .COM program that has just been loaded into memory but not yet run. However, when the MS-DOS program terminates, it removes itself from memory. PenPoint programs stay in memory until the user removes the application.
Running a PenPoint Application
3.3When running an MS-DOS program, the user has to find a file that contains data understood by the program. When the user decides to stop using the program, he or she must save the data to a file and then exit. If the user chooses a file that the program doesn't understand, the program might display garbled information, at best, and at worst the program might crash.
~
PenPoint takes a fundamentally different approach; the user creates a document from a list of available applications and, at some laJer time, tells PenPoint to activate the document. The user doesn't have to activate the document immediately after creating it and, in fact, can create many, many documents without activating any of them.
",. Life Cycle of a Document
The standard components of an application include its application code, application object, resource file, instance directory, process, and main window.
The full life cycle of a document created by an application includes these operations:
• Document creation (create file)
• Activation (create process)
• Opening (open on screen)
• Closing (remove from screen)
• Termination (terminate process)
• Destruction (delete file)
Active documents save their internal state in the file system, but this is invisible to the user: there is no need to save or load the application's state explicitly from one session to the next.
". Activating a Document
When the user activates the document, Pen Point finds out from the document what application it requires and creates a process that "runs" the application (the reason for the quotes is explained below under Application Classes and Instances).
When the user deactivates the document, PenPoint saves all information for the document and then destroys the application process.
3.3.1
3.3.2
The important thing in PenPoint is that the document remains in the computer from the time it is created until the time that the user deletes it, but the application process exists only while the document is active.
",. Not All Active Documents are On-Screen
It's only when the user activates a particular document that the document has a running application process. When the user activates a document, the PenPoint Application Framework creates an application process and calls the standard entry point in your code (main) in such a way that your application can tell that it is starting an application process (and not being installed). .
However, just because a document is running, doesn't mean that it must be on-screen; conversely, if a document is not on-screen, its process might still be runnmg.
The most common example of this is when the user makes a selection in a document and then turns to another document (perhaps to find a target for a move or copy). The document that owns the selection must remain active until it is told to release the selection.
A second example is the user chooses Accelerated Access Speed from the Access document option sheet (sometimes called hot mode), the application processes wili continue running, even when the user has turned to another page.
For a third example, you might want to create a stock-watcher type program that runs in the background most of the time. This type of program will also be active but not on-screen.
",. Application Classes and Instances
A PenPoint computer contains only one copy of your application code in memory, but a user can simultaneously activate several documents that use your application. Pen Point can do this because your application code is a PenPoint class and an active document is an instance of your application class.
When the user installs your application, your application creates your application class. When the user activates a document that uses your application, the
Application Framework creates an instance of your application class.
Accept this as Gospel now. We will spend pages and pages in this and other manuals explaining how this works.
". PenPoint Drives Your Application
Because of all these states that an application can be in, an application can't take control and start drawing on the screen and processing input when its main function is called. Nor can your application find out on its own ifit is on-screen or should terminate. Instead it must be directed what to do by the PenPoint Application Framework. The Application Framework sends messages to documents (and hence to your application code) to initialize data, display on screen, save their state, read their state, shut down, and so on. This is why applications must be implemented as classes.
For example, when a document needs to be started up to do some work, the PenPoint Application Framework sends msgAppActivate (read this as "message
3.3.3
3.3.4
3.4
CHAPTER 3 I .APPLICATION CONCEPTS 25 Application Objects
app activate") to the document. When the user turns to a document's page, the PenPoint Application Framework sends it msgAppOpen.
A typical MS-DOS program written in C has a main routine that displays a welcome message, parses its command line, creates a user interface, initializes structures, and then waits for user input. By contrast, a PenPoint application's main routine usually creates the application object and then immediately goes into a loop waiting for messages to the application ~bject to arrive. Because all
applications enter this loop, there is a routine, AppMain, which enters the loop for you.
".. Application Obiects
Most PenPoint applications perform three minimum actions:
• Respond to user and system events (including PenPoiht Application Framework messages)
• Create one or more windows for user input and to display output
• Create one or more objects to maintain their data.
There are object classes already written in PenPoint for each of these actions:
clsApp, clsWin, and clsObjeet, respectively. These classes do the right kinds of things for applications themselves, windows, and data. They provide a skeleton of correct behavior, although obviously GO's code doesn't create tie-tac-toe appli-cations, tic-tae-toe windows, or 3x3 "board" data objects. To get the behavior you want, you often need to use descendant classes that inherit from existing classes.
3.5
This section overruns with the terminology of classes.
De5cendant, Inheritance, and other terms are explained in the next section, "How Classes Interact."
E
IIIU
Z o
u
~
Z. Figure 3-1