Documents: 3.2 Basic DC Messages: From the Doc Control Objects

GEOS SDK TechDocs

3.1 Other Document Group Messages

4 Advanced DC Usage

Often the document control will need to notify the application to take an action. For example, when a document is created, the application needs to be told to initialize the document and the user interface. There are two basic models for handling these situations: the "Procedure" model and the "Object" model. (The differences between these models are discussed at more length in the section Document Control Models .) Each model has its own way of messaging.

Under the Procedure model, every time the application needs to be notified, the document control sends a message to the GenDocumentGroup's output object, which is ordinarily the process object. Under the Object model, the affected document object will send a message to itself; this message has no handler under GenDocumentClass , so the application must use a subclass of GenDocumentClass with handlers for these messages.

A single user action can generate several messages. For example, when the user opens a document, four messages are sent: MSG_..._PHYSICAL_OPEN , MSG_..._READ_CACHED_DATA_FROM_FILE , MSG_..._CREATE_UI_FOR_DOCUMENT , and MSG_..._ATTACH_UI_TO_DOCUMENT . Furthermore, a given message might be sent as the result of several different user actions; for example, the message MSG_..._CREATE_UI_FOR_DOCUMENT is sent when the user creates a new file or opens an existing one. If a handler needs to know what user action precipitated a given message, it can send a MSG_GEN_DOCUMENT_GET_OPERATION to the document object.

Messages Handled under the Procedure Model

Whenever the application needs to be notified to take an action, a message will be sent to the GenDocumentGroup's output object. Two arguments accompany such messages: A pointer to the relevant document object and the handle of the file associated with that document. All of these messages are exported from MetaClass , so they can be handled by objects of any class.

Each of these messages corresponds to a document-model message, all of which are described in Messages Handled under the Object Model . These are just the basic messages; for more advanced functionality, see the message listings in the advanced section.

MSG_META_DOC_OUTPUT_INITIALIZE_DOCUMENT_FILE

void	MSG_META_DOC_OUTPUT_INITIALIZE_FILE(
        optr		document, /* document object to initialize */
        FileHandle		file); /* Handle of file to initialize */

The GenDocumentGroup object sends this message out when a new document has been created and needs to be initialized. Applications which use VM files will allocate the map block and initialize it. If an application maintains data caches for its files, it should initialize the caches at this point.

Note that the handler for this message should not take any UI-related actions. These should be left to the handlers for MSG_META_DOC_OUTPUT_CREATE_UI_FOR_DOCUMENT and MSG_META_DOC_OUTPUT_ATTACH_UI_FOR_DOCUMENT .

Source: The GenDocumentGroup object.

Destination: The output of GenDocumentGroup (usually the Process object).

Parameters: document The optr of the document object which has just been created.

file

The FileHandle of the file which has just been created or opened.

Interception: If you are using the Procedure model, you must write a handler for this message in whatever class will be receiving it (usually the process class).

MSG_META_DOC_OUTPUT_CREATE_UI_FOR_DOCUMENT

void	MSG_META_DOC_OUTPUT_CREATE_UI_FOR_DOCUMENT(
        optr		document, /* Pointer to document object */
        FileHandle		file); /* Handle of file associated with 
				 * document object */

The GenDocumentGroup object sends this message after a document has been created or opened. Before this message is sent, the GenDocumentControl object will enable those objects on its GDCI_enableDisableList , and the GenDocumentGroup object will copy the GenDisplay resource for the document (if one is defined).

Applications that use dynamic UI objects will commonly respond to this message by creating the objects for the newly-opened document. Applications that use static UI objects will commonly respond to this message by enabling the objects.

Source: The GenDocumentGroup object.

Destination: The output of GenDocumentGroup (usually the Process object).

Parameters: document The optr of the appropriate document object.

file

The FileHandle of the appropriate file.

Interception: If you are using the Procedure model, you must write a handler for this message in whatever class will be receiving it (usually the process class).

MSG_META_DOC_OUTPUT_ATTACH_UI_TO_DOCUMENT

void	MSG_META_DOC_OUTPUT_ATTACH_UI_TO_DOCUMENT(
        optr		document, /* optr of document object */
        FileHandle 		file); /* handle of file for this document */

The GenDocumentGroup object sends this message when the UI for a newly-opened document has been created. It also sends this message when re-opening a document as part of restoring GEOS from a state file. Applications may respond to this by attaching dynamic UI objects and setting the values of static UI objects.

Source: The GenDocumentGroup object.

Destination: Output of GenDocumentGroup (usually the Process object).

Parameters: document The optr of the document object.

file

The FileHandle of the appropriate file.

MSG_META_DOC_OUTPUT_DETACH_UI_FROM_DOCUMENT

void 	MSG_META_DOC_OUTPUT_DETACH_UI_FROM_DOCUMENT(
        optr		document, /* pointer to document object */
        FileHandle 		file); /* handle of file for this document */

The GenDocumentGroup sends this message when a document is being closed, whether because a user closes the file or because the application is being closed. It also sends this message when GEOS is in the process of saving itself to a state file prior to shutting down. Applications generally respond to this by detaching dynamic UI objects. Note that the GenDocumentControl object will automatically disable any objects in its GDCI_enableDisableList .

Source: The GenDocumentGroup object.

Destination: Output of GenDocumentGroup (usually the Process object).

Parameters: document The optr of the appropriate document object.

file

The FileHandle of the appropriate file.

Interception: If you are using the Procedure model, you must write a handler for this message in whatever class will be receiving it (usually the process class).

MSG_META_DOC_OUTPUT_DESTROY_UI_FOR_DOCUMENT

void	MSG_META_DOC_OUTPUT_DESTROY_UI_FOR_DOCUMENT(
        optr	document, /* pointer to document object */
        FileHandle 	file); /* handle of file for this document */

The GenDocumentGroup object sends this message out when a document is being closed, whether because a user closes the file or because the application is being closed. Applications will generally disable static display objects and delete dynamic display objects. Note that the GenDocumentControl object will automatically disable all objects in its GDCI_enableDisableList , and the GenDocumentGroup will delete the display block it created for a document, if any.

Source: The GenDocumentGroup object.

Destination: Output of GenDocumentGroup (usually the Process object).

Parameters: document The optr of the appropriate document object.

file

The FileHandle of the appropriate file.

Interception: If you are using the Procedure model, you must write a handler for this message in whatever class will be receiving it (usually the process class).

MSG_META_DOC_OUTPUT_ATTACH_FAILED

void	MSG_META_DOC_OUTPUT_ATTACH_FAILED(
        optr	document, /* pointer to document object */
        FileHandle 	File); /* (former) handle of file for this document */

When GEOS restores itself from state, the document control tries to reattach all documents which were attached when GEOS was shut down. If this is impossible (as for example if a document was deleted after GEOS shut down), the GenDocumentGroup object will send this message to its output.

Source: The GenDocumentGroup object.

Destination: Output of GenDocumentGroup (usually the Process object).

Parameters: document The optr of the appropriate document object.

file

The FileHandle of the appropriate file.

Interception: If you are using the Procedure model, you must write a handler for this message in whatever class will be receiving it (usually the process class).

Messages Handled under the Object Model

If an application uses the Object model of document control, it will generally not handle the messages to the GenDocumentGroup's output. Instead, it will define a subclass of GenDocumentClass ; this subclass will have methods for those situations which require the application's attention. Note that GenDocumentClass does not have handlers for any of these messages; if the application does not define a method for a given message, that message will have no effect.

MSG_GEN_DOCUMENT_INITIALIZE_DOCUMENT_FILE

Boolean	MSG_GEN_DOCUMENT_INITIALIZE_DOCUMENT_FILE();

When a new document is created, the document object sends this message to itself. VM file based applications will generally respond to this message by allocating and initializing the map block. DOS file based applications will commonly initialize data structures for a default file. If an application maintains data caches for its files, it should initialize the caches at this point.

The application should not take any UI-related actions; those should be postponed until the messages MSG_GEN_DOCUMENT_CREATE_UI_FOR_DOCUMENT and MSG_GEN_DOCUMENT_ATTACH_UI_TO_DOCUMENT are received.

Source: A GenDocument object.

Destination: The document object sends this message to itself.

Parameters: Nothing.

Return: If the handler could not initialize the file, it should return true ; the document control will then destroy the new file.

MSG_GEN_DOCUMENT_CREATE_UI_FOR_DOCUMENT

void	MSG_GEN_DOCUMENT_CREATE_UI_FOR_DOCUMENT();

The GenDocument object sends this message to itself after a document has been created or opened. Before this message is sent, the GenDocumentControl object will enable those objects on its GDCI_enableDisableList , and the GenDocumentGroup object will copy the GenDisplay block for the document (if one is defined).

Applications that use dynamic UI objects will commonly respond to this message by creating the objects for the newly-opened document. Applications that use static UI objects will commonly respond to this message by enabling the objects.

Source: A GenDocument object.

Destination: The document object sends this message to itself.

MSG_GEN_DOCUMENT_ATTACH_UI_TO_DOCUMENT

void	MSG_GEN_DOCUMENT_ATTACH_UI_TO_DOCUMENT();

The document object sends this message to itself when the UI for a newly-opened document has been created. It also sends this message when re-opening a document as part of restoring GEOS from a state file. Applications may respond to this by attaching dynamic UI objects and setting the values of static UI objects.

Source: A GenDocument object.

Destination: The document object sends this message to itself.

MSG_GEN_DOCUMENT_DETACH_UI_FROM_DOCUMENT

void	MSG_GEN_DOCUMENT_DETACH_UI_FROM_DOCUMENT();

The document object sends this message when a document is being closed, whether because a user closes the file or because the application is being closed. It also sends this message when GEOS is in the process of saving itself to a state file prior to shutting down. Applications generally respond to this by detaching dynamic UI objects. Note that the GenDocumentControl object will automatically disable any objects in its GDCI_enableDisableList .

Source: A GenDocument object.

Destination: The document object sends this message to itself.

MSG_GEN_DOCUMENT_DESTROY_UI_FOR_DOCUMENT

void	MSG_GEN_DOCUMENT_DESTROY_UI_FOR_DOCUMENT();

The GenDocumentGroup object sends this message out when a document is being closed, whether because a user closes the file or because the application is being closed. Applications will generally disable static display objects and delete dynamic display objects. Note that the GenDocumentControl object will automatically disable all objects in its GDCI_enableDisableList , and the GenDocumentGroup will delete the display block it created for a document, if any.

Source: A GenDocument object.

Destination: The document object sends this message to itself.

MSG_GEN_DOCUMENT_ATTACH_FAILED

void	MSG_GEN_DOCUMENT_ATTACH_FAILED();

When GEOS restores itself from state, the document control tries to reattach all documents which were attached when GEOS was shut down. If this is impossible (as for example if a document was deleted after GEOS shut down), the document object will send this message to itself.

Source: A GenDocument object.

Destination: The document object sends this message to itself.

Messages Associated with Common User Actions

A single user action can precipitate several application-handled messages. This section lists the messages associated with each of several common user actions. Note that some messages are sent as the result of many user actions. If a handler needs to find out what user action caused a message to be sent, it should send MSG_GEN_DOCUMENT_GET_OPERATION to the document object.

If a message is not ordinarily handled, it is enclosed in [brackets] below. These messages are documented in the advanced usage section. Actions taken by the document control objects (other than messages sent) are listed in italics . The messages listed are sent by the appropriate GenDocument object to itself. If the message is not subclassed by the GenDocument object, it sends a corresponding procedural-model message (of the form MSG_META_DOC_OUTPUT...) to the GenDocumentGroup object's output. The one exception is MSG_GEN_DOCUMENT_PHYSICAL_SAVE_AS; as noted on MSG_META_DOC_OUTPUT_PHYSICAL_SAVE_AS_FILE_HANDLE , this message does not have a corresponding MSG_META_DOC_OUTPUT_PHYSICAL_SAVE_AS.

• New document is created:
  [ MSG_GEN_DOCUMENT_PHYSICAL_CREATE ]
  new file is created
  VM files: initialize VM attributes, token, protocol
  MSG_GEN_DOCUMENT_INITIALIZE_DOCUMENT_FILE
if saveAs/Revert supported, save file so revert will return to this state
  [ MSG_GEN_DOCUMENT_WRITE_CACHED_DATA_TO_FILE ]
  [ MSG_GEN_DOCUMENT_PHYSICAL_SAVE ]
  MSG_GEN_DOCUMENT_CREATE_UI_FOR_DOCUMENT
MSG_GEN_DOCUMENT_ATTACH_UI_TO_DOCUMENT
• Document is opened:
  [ MSG_GEN_DOCUMENT_PHYSICAL_OPEN ]
  [ MSG_GEN_DOCUMENT_READ_CACHED_DATA_FROM_FILE ]
  MSG_GEN_DOCUMENT_CREATE_UI_FOR_DOCUMENT
MSG_GEN_DOCUMENT_ATTACH_UI_TO_DOCUMENT
• Document is saved:
  [ MSG_GEN_DOCUMENT_WRITE_CACHED_DATA_TO_FILE ]
  [ MSG_GEN_DOCUMENT_PHYSICAL_SAVE ]
  VM files: call made to VMSave
• Document is "Saved As":
  [ MSG_GEN_DOCUMENT_WRITE_CACHED_DATA_TO_FILE ]
  [ MSG_GEN_DOCUMENT_PHYSICAL_SAVE_AS ]
  [DOS files: MSG_GEN_DOCUMENT_PHYSICAL_SAVE_AS_FILE_HANDLE ]
  VM files: VMSaveAs called
  [ MSG_GEN_DOCUMENT_SAVE_AS_COMPLETED ]
• Document is reverted to last-saved version:
  MSG_GEN_DOCUMENT_DETACH_UI_FROM_DOCUMENT
[ MSG_GEN_DOCUMENT_PHYSICAL_REVERT ]
  VM : VMRevert called
  [ MSG_GEN_DOCUMENT_READ_CACHED_DATA_FROM_FILE ]
  MSG_GEN_DOCUMENT_ATTACH_UI_TO_DOCUMENT
• Document is about to be closed:
  [MSG_GEN_DOCUMENT_PHYSICAL_CHECK_FOR_MODIFICATIONS]

If document is modified & user wants to save changes:

[ MSG_GEN_DOCUMENT_WRITE_CACHED_DATA_TO_FILE ]
[ MSG_GEN_DOCUMENT_PHYSICAL_SAVE ]
VM : VMSave called
MSG_GEN_DOCUMENT_DETACH_UI_FROM_DOCUMENT
MSG_GEN_DOCUMENT_DESTROY_UI_FOR_DOCUMENT

If document is modified and user does not want to save changes:

MSG_GEN_DOCUMENT_DETACH_UI_FROM_DOCUMENT
[ MSG_GEN_DOCUMENT_PHYSICAL_REVERT ]
VM : VMRevert called
MSG_GEN_DOCUMENT_DESTROY_UI_FOR_DOCUMENT
[ MSG_GEN_DOCUMENT_PHYSICAL_CLOSE ]

If document is not modified:

MSG_GEN_DOCUMENT_DETACH_UI_FROM_DOCUMENT
MSG_GEN_DOCUMENT_DESTROY_UI_FOR_DOCUMENT
[ MSG_GEN_DOCUMENT_PHYSICAL_CLOSE ]

If document is not modified and untitled:

MSG_GEN_DOCUMENT_DETACH_UI_FROM_DOCUMENT
MSG_GEN_DOCUMENT_DESTROY_UI_FOR_DOCUMENT
[ MSG_GEN_DOCUMENT_PHYSICAL_CLOSE ]
[ MSG_GEN_DOCUMENT_PHYSICAL_REVERT ]

• GEOS restoring from state, document being attached:
  [ MSG_GEN_DOCUMENT_PHYSICAL_OPEN ]
  [ MSG_GEN_DOCUMENT_READ_CACHED_DATA_FROM_FILE ]
  MSG_GEN_DOCUMENT_ATTACH_UI_TO_DOCUMENT
• GEOS restoring from state, attach failed:
  MSG_GEN_DOCUMENT_ATTACH_FAILED
MSG_GEN_DOCUMENT_DESTROY_UI_FOR_DOCUMENT
• GEOS shutting down, document being detached:
  [ MSG_GEN_DOCUMENT_DETACH_UI_FROM_DOCUMENT ]
  [ MSG_GEN_DOCUMENT_PHYSICAL_UPDATE ]
  VM files: VMUpdate called
  MSG_GEN_DOCUMENT_DETACH_UI_FROM_DOCUMENT
[ MSG_GEN_DOCUMENT_PHYSICAL_CLOSE ]

GEOS SDK TechDocs

3.1 Other Document Group Messages

4 Advanced DC Usage