GEOS SDK TechDocs
|
| 
1.2 Document Control Interaction
| 
2 Document Control Data Fields
GEOS allows two distinct models of document control, a Procedural model and an Object model. While the two models use the same objects, they embody different programming philosophies.
The Procedural model of document control is much like traditional, non-object-oriented programming. Under this model, whenever a situation arises that needs the application's attention, the document control objects will send a message to a single object (generally the Process object). This object handles all of these situations.
Under the
Object
model of document control, the application defines a subclass of
GenDocumentClass
. This new document class has methods to handle situations needing the application's attention. This model is based on the philosophy of object-oriented programming; each document object has code to handle situations arising for that document.
The main difference between the two models is where the messages are sent. Under the Procedural model, messages are sent to the Process object; under the Object model, messages are sent to the appropriate document object. Every message sent in the Procedural model corresponds to a message sent in the Object model.
The Procedural model is simpler to use; it does not require the application to subclass objects. It is thus well-suited for simple applications which will have only one file open at a time. It may also be an easier model for programmers who are new to object-oriented programming. The Object model, on the other hand, is best suited for applications which will have many documents open at once; the application can let every document object manage a single document without worrying about other open documents.
The Procedural model of document control is much like traditional, procedure-oriented programming. This model is simpler to implement than the object-model. It is well suited for simple applications which have only one document open at a time.
Under the Procedural model of document control, every time a situation arises which requires the application's attention, the document control objects will send an appropriate message to the GenDocumentGroup object's output. These messages are imported from
MetaClass
, so all objects can handle them. The application will generally use global variables for run-time data storage.
For example, when a new document needs to be initialized, the
document control sends a
MSG_META_DOC_OUTPUT_INITIALIZE_DOCUMENT_FILE
to its output object. The output object takes any appropriate steps (e.g., storing the file handle, setting up the map block, etc.).
The
Object
model of document control is better suited to advanced applications and applications which will have more than one document open at a time. Under this model, the application defines a subclass of
GenDocumentClass
. This new document class has handlers for situations requiring the application's attention. It also has local variables (i.e., instance data fields) which store any information the application will need about this document.
Whenever a situation arises that needs the application's attention, the relevant document object will send a message to itself. This document object will then handle the message. For example, an application might define its own document class,
MyAppDocumentClass
(a subclass of
GenDocumentClass)
. Suppose a new document has been created and needs to be initialized. First, the GenDocumentGroup object will create a new document object by instantiating an object of
MyAppDocumentClass
. Next, the new document object will send itself a
MSG_GEN_DOCUMENT_INITIALIZE_DOCUMENT_FILE.
MyAppDocumentClass
will have a handler for this message; the handler will initialize the file as well as the document object's data structures.
The simplest way to show the difference between the two models is to see how a single event is handled. This section examines one specific case, in which a document needs to be initialized; other cases are handled analogously.
Suppose a situation arises needing the application's attention; for example, a document is created and needs to be initialized. First, the document object will send an appropriate message to itself. In this case, it would send itself the message
MSG_GEN_DOCUMENT_INITIALIZE_DOCUMENT_FILE
. If the application uses a subclass of
GenDocumentClass
and this subclass has a handler for
MSG_GEN_DOCUMENT_INITIALIZE_DOCUMENT_FILE
, the messager will call that method; otherwise, the messager will call the handler defined for this message by
GenDocumentClass
. The handler in
GenDocumentClass
will find out the
GenDocumentGroup
object's output optr. If this optr is non-null, the handler will send an appropriate message (in this case,
MSG_META_DOC_OUTPUT_INITIALIZE_DOCUMENT_FILE
) to the output object.
Note that, under normal circumstances, the application will handle only one of the two messages. For example, if the application writes a handler for
MSG_GEN_DOCUMENT_PHYSICAL_SAVE
, the handler defined by
GenDocumentClass
will not be called; as a result,
MSG_META_DOC_OUTPUT_PHYSICAL_SAVE
will not be sent to the
GenDocumentGroup
object's output. This is not usually a problem, since the application will generally handle one message or the other. If, for some reason, it needs to have both messages sent, the handler for
MSG_GEN_DOCUMENT_SAVE
should contain a
@callsuper
instruction.
GEOS SDK TechDocs
|
| 1.2 Document Control Interaction
| 2 Document Control Data Fields