Documents: 2.3 Document Control Data Fields: GenDocument Attributes

There are very few GenDocumentClass attributes that you will need to be concerned with. The GenDocumentGroup object creates and updates document objects as needed. Ordinarily, the application will not look at the GenDocumentClass instance data. If the program defines a subclass of GenDocumentClass , the subclass's methods should use only the subclass's instance data.

There is only one attribute which the program should change at run-time, and that is the GDA_PREVENT_AUTO_SAVE bit of the GDI_attrs field. This bit can be changed with the messages MSG_GEN_DOCUMENT_DISABLE_AUTO_SAVE and MSG_GEN_DOCUMENT_ENABLE_AUTO_SAVE .

GenDocumentClass is a subclass of GenContentClass and has all the functionality of that class. Since GenContent objects are rarely used directly, the class does not have its own chapter; instead, it is documented in GenContentClass . The main thing to know about the GenContent is that, like a VisContent, it is displayed in a GenView and can have visible children. It can also have generic children, though it may not have both visible and generic children at the same time.

The GDI_attrs Field

GDI_attrs, MSG_GEN_DOCUMENT_GET_ATTRS, MSG_GEN_DOCUMENT_ENABLE_AUTO_SAVE, MSG_GEN_DOCUMENT_DISABLE_AUTO_SAVE, MSG_GEN_DOCUMENT_AUTO_SAVE

The GDI_attrs word contains flags indicating the status of the document. The application can read or change any of these attributes; however, only the attribute GDA_PREVENT_AUTO_SAVE should actually be changed at run-time.

GDA_READ_ONLY: This attribute is set if the document in question is opened for read-only access.
GDA_READ_WRITE: This attribute is set if the document is opened for read/write access.
GDA_FORCE_DENY_WRITE: If this attribute is set, while the document is open, no other process will be allowed to open that document for read/write access.
GDA_SHARED_MULTIPLE: The document is opened in "shared multiple" mode.
GDA_SHARED_SINGLE: The document is opened in "shared single" mode.
GDA_UNTITLED: The document is newly-created and has not yet been saved; it is still untitled.
GDA_DIRTY: The document has been marked dirty since the last time it was saved.
GDA_CLOSING: The document is in the process of being closed.
GDA_ATTACH_TO_DIRTY_FILE: The document object is being attached to a dirty file (e.g., when restarting GEOS).
GDA_SAVE_FAILED: The user attempted to save the document, and it could not be saved (e.g., someone else denied write access, or the volume was no longer accessible).
GDA_OPENING: The document is in the process of being opened.
GDA_AUTO_SAVE_STOPPED: Auto-save was stopped while in progress.
GDA_PREVENT_AUTO_SAVE: This bit can be changed by the application at run-time. While the bit is on, auto-save is disabled.

MSG_GEN_DOCUMENT_GET_ATTRS

GenDocumentAttrs 	MSG_GEN_DOCUMENT_GET_ATTRS();

Use this message to get the GDI_attrs flags for a given document. These attribute flags give information about the document's permissions as well as about any operations currently in progress.

Source: Unrestricted--objects subclassed from GenDocumentClass often send this message to themselves.

Destination: Any GenDocument object.

Return: The object's word-sized GDI_attrs field.

Interception: You should not subclass this message.

MSG_GEN_DOCUMENT_DISABLE_AUTO_SAVE

void	MSG_GEN_DOCUMENT_DISABLE_AUTO_SAVE();

Sometimes an application needs to temporarily disable auto-save for a specific document (for example, if it is in the middle of making elaborate changes to the file). It can do this by sending this message to the document object. The document's GDA_PREVENT_AUTO_SAVE bit will be turned on, and auto-save will be disabled until the document receives a MSG_GEN_DOCUMENT_ENABLE_AUTO_SAVE .

Source: Unrestricted--objects subclassed from GenDocumentClass often send this message to themselves.

Destination: Any GenDocument object.

Interception: You should not subclass this message.

MSG_GEN_DOCUMENT_ENABLE_AUTO_SAVE

void	MSG_GEN_DOCUMENT_ENABLE_AUTO_SAVE();

This message turns off a document's GDA_PREVENT_AUTO_SAVE bit. If the bit is already off (i.e., auto-save is enabled), the message has no effect.

Source: Unrestricted--objects subclassed from GenDocumentClass often send this message to themselves.

Destination: Any GenDocument object.

Interception: You should not subclass this message.

MSG_GEN_DOCUMENT_AUTO_SAVE

void	MSG_GEN_DOCUMENT_AUTO_SAVE();

This message forces the document object to immediately auto-save its file.

Source: Unrestricted. The document object may send this message to itself.

Destination: Any GenDocument object.

Interception: This message is not generally subclassed.

The GDI_operation Attribute

GDI_operation, MSG_GEN_DOCUMENT_GET_OPERATION

A single user action can result in many routines being called and many messages being sent out. To help keep track of what's going on, GenDocumentClass has a byte-length field, GDI_operation . If the document control is in the midst of handling a user action for a given document, it will set the GDI_operation byte accordingly. The current operation is a member of the GenDocumentOperation enumerated type. This type has the following possible values:

GDO_NORMAL: This is the usual setting. If the document is not currently handling a user action, this is the setting.
GDO_SAVE_AS: When the user chooses "Save As," the byte is set to this value. It remains at this value until the new document has been opened and saved.
GDO_REVERT: The setting from the time the user chooses "Revert" until the file has been restored to its last-saved state.
GDO_REVERT_QUICK: The setting from the time the user chooses "restore from backup" until the file has been restored.
GDO_ATTACH: The setting while the UI is being created for and attached to a given document. When a file document is created or opened, the GDI_operation field is set to this after GEOS has opened the file, and it remains at this setting until the application finishes attaching the UI.
GDO_DETACH: The setting while the UI is being detached from a given document, but before the actual file is closed.
GDO_NEW: The setting while a new file is being created. When the file is created and initialized, the GDI_operation will change to GDO_ATTACH .
GDO_OPEN: The setting while an existing file is being opened. When the file is created and initialized, the GDI_operation will change to GDO_ATTACH .
GDO_SAVE: The setting while a document is being saved.
GDO_CLOSE: After the UI has been detached, the GDI_operation byte is set to this value until the document object is destroyed.
GDO_AUTO_SAVE: The setting while a file is being updated (i.e. auto-saved) to disk.

MSG_GEN_DOCUMENT_GET_OPERATION

GenDocumentOperation 	MSG_GEN_DOCUMENT_GET_OPERATION();

Use this message to find out what user action a given document object is in the midst of processing. This is useful if you are handling some message and want to find out the context in which that message was sent. Note that although the message returns a word-length value, the GDI_operation enumerated type is byte-length; it is thus safe to cast the return value to a byte-length variable.

Source: Unrestricted--objects subclassed from GenDocumentClass often send this message to themselves.

Destination: Any GenDocument object.

Return: Returns a member of the GenDocumentOperation enumerated type corresponding to the document object's current operation.

Interception: You should not subclass this message.

File Information

GDI_fileHandle, GDI_diskHandle, GDI_volumeName, GDI_fileName, MSG_GEN_DOCUMENT_GET_FILE_NAME, MSG_GEN_DOCUMENT_GET_FILE_HANDLE

The document object stores certain data about the file associated with it. In particular, the instance data records the document's path, its full file name, and the handles of the file and the disk volume containing the file. This data can be retrieved by sending messages to the document object.

MSG_GEN_DOCUMENT_GET_FILE_NAME

void	MSG_GEN_DOCUMENT_GET_FILE_NAME(
        char *buffer); /* Address to write file name to */

This message instructs a GenDocument to write the name of its file (without the path) to the specified address.

Source: Unrestricted--objects subclassed from GenDocumentClass often send this message to themselves.

Destination: Any GenDocument object

Parameters: buffer Buffer of length FILE_LONGNAME_BUFFER_SIZE.

Return: Writes file's virtual name into the passed buffer as a null-terminated string.

Warnings: Make sure the buffer passed is of length FILE_LONGNAME_BUFFER_SIZE; otherwise the method might overwrite other data.

Interception: You should not subclass this message.

MSG_GEN_DOCUMENT_GET_FILE_HANDLE

FileHandle 	MSG_GEN_DOCUMENT_GET_FILE_HANDLE();

This message returns the handle of the file associated with a given GenDocument object.

Source: Unrestricted--objects subclassed from GenDocumentClass often send this message to themselves.

Destination: Any GenDocument object.

Return: Returns handle of file associated with that document object.

Interception: You should not subclass this message.

GenContentClass

The GenContent generic object is similar to the VisContent visible object in that it interacts directly with the GenView. While the VisContent allows an application to display a visible hierarchy of objects within the view, however, the GenContent allows either generic or visible object hierarchies to be displayed. This is the one case where you may ordinarily have visible objects be children of a generic object. Note that you should not have both visible and generic objects as children of the same GenContent; if you do so, results are undefined.

Any GenView whose content is a GenContent (or subclass) should have its GVA_GENERIC_CONTENTS attribute set.

GenContentClass is a subclass of GenClass and therefore inherits all the instance data, messages, and hints of all generic objects. The GenContent also has two other instance data fields, however; these are

@instance byte			GCI_attrs = 0;
@instance optr			GCI_genView;

The GCI_attrs field contains a record of VisContentAttrs and is used by document objects for visual updates and interaction with the GenView. This record may be retrieved with MSG_GEN_CONTENT_GET_ATTRS or set with MSG_GEN_CONTENT_SET_ATTRS .

The GCI_genView field contains the optr of the GenView object displaying the GenContent. This, too, is used by document objects to manage interaction with the GenView.

MSG_GEN_CONTENT_GET_ATTRS

byte	MSG_GEN_CONTENT_GET_ATTRS();

This message returns the record of VisContentAttrs set in the GenContent's GCI_attrs field.

Source: Unrestricted.

Destination: Any GenContent object

Parameters: None.

Return: The GCI_attrs settings.

Interception: Unlikely.

MSG_GEN_CONTENT_SET_ATTRS

void	MSG_GEN_CONTENT_SET_ATTRS(
        byte	attrsToSet,
        byte	attrsToClear);

This message sets the attributes in the GenContent's GCI_attrs record.

Source: Unrestricted.

Destination: Any GenContent object.

Parameters: attrsToSet A record of VisContentAttrs indicating which flags should be set. Those set in attrsToSet will be set in GCI_attrs .

attrsToClear: A record of VisContentAttrs indicating which flags should be cleared. Those cleared in attrsToClear will be cleared in GCI_attrs . Note that if a flag is set in both parameters, it will end up cleared.

Return: Nothing.

Interception: Unlikely.

GEOS SDK TechDocs |

2.2 GenDocumentGroup Data | Next:

3 Basic DC Messages