GEOS SDK TechDocs
|
| 
4.3 Working with DOS files
| 
4.5 Forcing Actions
In addition to the basic messages discussed above, there are messages the document control sends out which do not ordinarily need to be handled. Some of these messages have been discussed above; most of the rest are described here.
MSG_META_DOC_OUTPUT_WRITE_CACHED_DATA_TO_FILE, MSG_GEN_DOCUMENT_WRITE_CACHED_DATA_TO_FILE, MSG_META_DOC_OUTPUT_READ_CACHED_DATA_FROM_FILE, MSG_GEN_DOCUMENT_READ_CACHED_DATA_FROM_FILE
Sometimes an application will want to keep frequently-accessed data in memory. For example, if you are managing Virtual Memory files, you may want to copy the map block to a fixed memory block instead of locking the block every time you need to read or change it. This is known as caching data.
If you cache data, you must make sure that the application's version of the data is consistent with the disk file. The document control helps keep track of this. Whenever the file (or the state) is saved, the document control will first send a message instructing the application to write the cache to the file, then it will save the file. Similarly, when the file is opened or GEOS is restarted from state, the document control will send a message instructing the application to reload the cached data from the file.
There is one special concern. The user cannot save a file unless it has been marked dirty; also, the document control does not send
MSG_..._WRITE_CACHED_DATA_TO_FILE
to documents which are not dirty. Therefore, if you change the data cache without actually altering the file, you should send a
MSG_GEN_DOCUMENT_GROUP_MARK_DIRTY
to the GenDocumentGroup.
void MSG_META_DOC_OUTPUT_READ_CACHED_DATA_FROM_FILE(
optr document, /* optr of document object */
FileHandle file); /* FileHandle of associated file */
The GenDocumentGroup sends this message when the document needs to read cached data. In particular, it sends this when a document is opened, when a document is reverted to its last-saved state, and when a document is re-opened as GEOS restores from state. If the application maintains a data cache, it should read the data from the file at this point. If the document does not cache data, it can ignore this message.
Note that if the document control notices that the file has changed on disk, it will not send this message; it will, however, send a
MSG_META_DOC_OUTPUT_DOCUMENT_HAS_CHANGED
. The handler for that message should reread the cache or call the handler for this message.
Source: The GenDocumentGroup object.
Destination: Output of GenDocumentGroup (usually the Process object).
Parameters: document The optr of the appropriate document object.
Interception: You must write a handler for this message in whatever class will be receiving it (usually the process class).
void MSG_GEN_DOCUMENT_READ_CACHED_DATA_FROM_FILE();
The document object
sends this message to itself when the document needs to read cached data. In particular, it sends this when a document is opened, when a document is reverted to its last-saved state, and when a document is re-opened as GEOS restores from state. If the application maintains a data cache, it should read the data from the file at this point. If the document does not cache data, it can ignore this message.
Note that if the document control notices that the file has changed on disk, it will not send this message; it will, however, send a
MSG_GEN_DOCUMENT_DOCUMENT_HAS_CHANGED
. The handler for that message should reread the cache or call the handler for this message.
Source: A GenDocument object.
Destination: The document object sends this message to itself.
void MSG_META_DOC_OUTPUT_WRITE_CACHED_DATA_TO_FILE(
optr document, /* optr of document object */
FileHandle file); /* FileHandle of associated file */
The GenDocumentGroup object sends this message when the document needs to write cached data back to the file. In particular, it sends this message just before a document is saved, auto-saved, or "Saved As," and before the document is closed as GEOS shuts down. The document should write its cached data back to the file. If the document does not cache data, it can ignore this message.
Warnings: This message will not be sent if the document is clean. Therefore, if you change the data cache without changing the file, you should send a
MSG_GEN_DOCUMENT_GROUP_MARK_DIRTY_BY_FILE
to the GenDocumentGroup object.
Source: The GenDocumentGroup object.
Destination: Output of GenDocumentGroup (usually the Process object)
Parameters: document The optr of the appropriate document object.
Interception: You must write a handler for this message in whatever class will be receiving it (usually the process class).
void MSG_META_DOC_OUTPUT_WRITE_CACHED_DATA_TO_FILE();
The document object sends this message to itself when the document needs to write cached data back to the file. In particular, it sends this message just before a document is saved, auto-saved, or "Saved As," and before the document is closed as GEOS shuts down. The document should write its cached data back to the file. If the document does not cache data, it can ignore this message.
Warnings: This message will not be sent if the document is clean. Therefore, if you change the data cache without changing the file, you should send a
MSG_GEN_DOCUMENT_GROUP_MARK_DIRTY_BY_FILE
to the GenDocumentGroup object.
Source: A GenDocument object.
Destination: The document object sends this message to itself.
There are a few other messages which are worth knowing about. These messages alert the application to special situations. Most applications can ignore these messages; however, for a few, these messages should be handled.
void MSG_META_DOC_OUTPUT_SAVE_AS_COMPLETED(
optr document, /* optr of document object */
FileHandle file); /* FileHandle of associated file */
The GenDocumentGroup object sends this message when a "Save As" operation has been successfully completed.
Source: The GenDocumentGroup object.
Destination: Output of GenDocumentGroup (usually the Process object).
Parameters: document The optr of the appropriate document object.
Interception: You must write a handler for this message in whatever class will be receiving it (usually the process class).
void MSG_GEN_DOCUMENT_SAVE_AS_COMPLETED();
The document object sends this message to itself when a "Save As" operation has been successfully completed.
Source: A GenDocument object.
Destination: The document object sends this message to itself.
void MSG_META_DOC_OUTPUT_DOCUMENT_HAS_CHANGED(
optr document, /* optr of document object */
FileHandle file); /* FileHandle of associated file */
If the GDGA_AUTOMATIC_CHANGE_NOTIFICATION attribute of the GenDocumentGroup object is set to on, a timer will periodically check to see if any open documents have been changed by another application. If they have, the GenDocumentGroup object will send this message out. The application should respond by redisplaying the data on the screen and rereading any cached data from the file.
Source: The GenDocumentGroup object.
Destination: Output of GenDocumentGroup (usually the Process object).
Parameters: document The optr of the appropriate document object.
Interception: You must write a handler for this message in whatever class will be receiving it (usually the process class).
void MSG_GEN_DOCUMENT_DOCUMENT_HAS_CHANGED();
If the GDGA_AUTOMATIC_CHANGE_NOTIFICATION attribute of the GenDocumentGroup object is set to on, a timer will periodically check to see if any open documents have been changed by another application. If they have, the document object will send this message out. The application should respond by redisplaying the data on the screen and rereading any cached data from the file.
Source: A GenDocument object.
Destination: The document object sends this message to itself.
GEOS SDK TechDocs
|
| 4.3 Working with DOS files
| 4.5 Forcing Actions