Documents: 2.2 Document Control Data Fields: GenDocumentGroup Data

The GenDocumentGroup object creates and manages the document objects. In the "process" model of document control, it sends messages to the process object (or some other designated object) when the application needs to take some action. (It sends these messages even when the "object" model is being followed; however, the messages are ignored.)

A list of data fields for the GenDocumentGroup object follows in GenDocumentGroupClass instance data . Some of the data fields can be changed at run-time, and others cannot; a discussion of the data fields follows the listing. If a data field cannot be set or read by the application, it is not discussed.

Code Display 13-2 GenDocumentGroupClass instance data

/* GDGI_attrs is a record that specifies certain basic characteristics of the
 * documents to be managed. The attributes are set in the source code and are not
 * changed at run-time. The default settings are below. */
    @instance GenDocumentGroupAttrs				GDGI_attrs = (GDGA_VM_FILE |
					GDGA_SUPPORTS_AUTO_SAVE |
					GDGA_AUTOMATIC_CHANGE_NOTIFICATION |
					GDGA_AUTOMATIC_DIRTY_NOTIFICATION |
					GDGA_APPLICATION_THREAD |
					GDGA_AUTOMATIC_UNDO_INTERACTION |
					GDGA_CONTENT_DOES_NOT_MANAGE_CHILDREN);
	/* The following flags are available: 
	 * 	GDGA_VM_FILE,			
	 *	GDGA_NATIVE,
	 *	GDGA_SUPPORTS_AUTO_SAVE, 
	 *	GDGA_AUTOMATIC_CHANGE_NOTIFICATION,
	 * 	GDGA_AUTOMATIC_DIRTY_NOTIFICATION, 
	 * 	GDGA_APPLICATION_THREAD,
	 *	GDGA_VM_FILE_CONTAINS_OBJECTS,
	 *	GDGA_CONTENT_DOES_NOT_MANAGE_CHILDREN,
	 * 	GDGA_LARGE_CONTENT,
	 * 	GDGA_AUTOMATIC_UNDO_INTERACTION */

/* GDGI_untitledName is the name suggested when a new document is
 * first saved. */
    @instance ChunkHandle			GDGI_untitledName;

/* The GenDocumentGroup object creates a document object for each document
 * opened. The attribute GDGI_documentClass is a pointer to the class definition
 * which will be used for document objects. By default, it points to the
 * definition of GenDocumentClass, so document objects belong to GenDocumentClass.
 * If you use a subclass of GenDocumentClass, you must change this attribute to
 * point to the new class. */
    @instance ClassStruc *			GDGI_documentClass = 
					(ClassStruc *) &GenDocumentClass;

/* Ordinarily, the Document Group creates document objects by instantiating an
 * object of the class indicated by GDGI_documentClass. However, it can be
 * instructed instead to duplicate a specific document object for each new
 * document. To arrange this, set the GDGI_genDocument to point to the document
 * object to duplicate. */
    @instance optr 			GDGI_genDocument;

/* If the Procedural model is used, whenever the application needs to take an
 * action, messages will be sent to the output of the GenDocumentGroup.
 * Ordinarily, the output will be the process object. If the Object model is used,
 * this attribute is generally left as a null pointer. */
    @instance optr			GDGI_output;

/* The GenDocumentGroup object communicates with the GenDocumentControl
 * object through messages. To do this, each one needs an object-pointer to the
 * other. This is set in the source code. */
    @instance optr			GDGI_documentControl;

/* The GenDocument (or subclass) objects can behave as Content objects. The
 * document control can automatically connect GenDocument objects to the GenView
 * if told to do so. The GDGI_genView field is an object-pointer to a GenView
 * object. */
    @instance optr			GDGI_genView;

/* In a multiple-document model, the document control can be set up to work with
 * the display control. When this functionality is enabled, the
 * GenDocumentGroup will automatically duplicate a specified block (generally
 * one containing a GenDisplay object), attach the Display object to the specified
 * GenDisplayGroup object, and set the header for the GenDisplay to the name of
 * the document. When the document is closed, the block is freed. */
    @instance optr			GDGI_genDisplay; 
/* GDGI_genDisplayGroup points to the GenDisplayGroup which manages the 
 * GenDisplays. */
    @instance optr			GDGI_genDisplayGroup;

/* Each GEOS document has a protocol number, which identifies the version of
 * the application that created it. The GDGI_protocolMajor and
 * GDGI_protocolMinor attributes specify the protocol number to be assigned to
 * all documents created by the document control. */
    @instance word			GDGI_protocolMajor = 1;
    @instance word			GDGI_protocolMinor = 0;

The GDGI_attrs Field

GDGI_attrs, MSG_GEN_DOCUMENT_GROUP_GET_ATTRS

This attribute specifies certain characteristics of the documents to be opened. These attributes are generally set in the source code and can not be changed at run-time. They are stored in a word-sized bitfield.

GDGA_VM_FILE: This attribute is on if the documents to be opened are GEOS Virtual Memory files. By default, it is on.
GDGA_NATIVE: This attribute is on if the documents to be opened are in the file system's native format (i.e. they are not GEOS files). By default, it is off.
GDGA_SUPPORTS_AUTO_SAVE: If this attribute is on, the documents will be periodically auto-saved. It works only with VM files (unless you subclass GenDocument to handle MSG_GEN_DOCUMENT_PHYSICAL_UPDATE ; see Working with DOS files ). It works by periodically updating the file to disk. It should probably be turned off if "Save As" and "Revert" are disabled. By default, the attribute is on. The program can temporarily disable auto-save for a document by sending the document object MSG_GEN_DOCUMENT_DISABLE_AUTO_SAVE .
GDGA_AUTOMATIC_CHANGE_NOTIFICATION: If this attribute is on, the GenDocumentGroup object will periodically check all open documents to see if they have been changed by another process. If a document has changed, the document control will send MSG_META_DOC_OUTPUT_DOCUMENT_HAS_CHANGED to the application. This attribute is useful if the application may be reading multi-user files.
GDGA_AUTOMATIC_DIRTY_NOTIFICATION: This attribute is relevant only for GEOS files. If the attribute is on, whenever a file is marked "dirty," the file system will automatically notify the document control. The document control will then take appropriate actions (enable the "Save" trigger, etc.). The document control will also present a "Save changes before closing" dialog box if the document is closed before being saved. If GDGA_AUTOMATIC_DIRTY_NOTIFICATION is off, or if the documents are DOS files, the application will have to notify the document control when the document is dirty. It does this by sending a MSG_GEN_DOCUMENT_GROUP_MARK_DIRTY to the GenDocumentGroup object (under the procedure model), or by sending a MSG_GEN_DOCUMENT_MARK_DIRTY to the document object (under the object model). By default, GDGA_AUTOMATIC_DIRTY_NOTIFICATION is on.
GDGA_APPLICATION_THREAD: If this attribute is on, the GenDocumentGroup object is run by the application thread, as are its (document-object) children. By default, it is on.
GDGA_VM_FILE_CONTAINS_OBJECTS: If the document control manages Virtual Memory Object files, this attribute should be set to on. By default, this attribute is off.
GDGA_CONTENT_DOES_NOT_MANAGE_CHILDREN: The application's main VisContent, if any, does not manage its children. By default, this attribute is on.
GDGA_LARGE_CONTENT: The application's main VisContent uses the large model. By default, this attribute is off.
GDGA_AUTOMATIC_UNDO_INTERACTION: The application sends out undo set-context messages automatically as necessary.

MSG_GEN_DOCUMENT_GROUP_GET_ATTRS

GenDocumentGroupAttrs 	MSG_GEN_DOCUMENT_GROUP_GET_ATTRS();

Use this message to find out the attributes of the GenDocumentGroup object. Note that the attributes cannot be changed at run-time; they can only be examined.

Source: Unrestricted.

Destination: Any GenDocumentGroup object.

Parameters: None.

Return: Flags in GDGI_attrs bitfield.

Interception: You should not subclass this message.

The GDGI_untitledName Field

 GDGI_untitledName, MSG_GEN_DOCUMENT_GROUP_GET_DEFAULT_NAME

The first time a new document is saved, the document control presents a "Save As" dialog box. If the GDGI_untitledName field is set to point to a string, that string will be suggested as the name of the document. If the attribute is not set, no name will be suggested. The current default name can be retrieved by sending MSG_GEN_DOCUMENT_GROUP_GET_DEFAULT_NAME to the GenDocumentGroup object.

MSG_GEN_DOCUMENT_GROUP_GET_DEFAULT_NAME

GenDocumentGroupAttrs 	MSG_GEN_DOCUMENT_GROUP_GET_DEFAULT_NAME(
        char *buffer); /* Address to write default name */

This message instructs the GenDocumentGroup object to copy the GDGI_untitledName attribute to the specified address. In addition, the message will return the GDGI_attrs word of the GenDocumentGroup object. If you just want the attributes, use MSG_GEN_DOCUMENT_GROUP_GET_ATTRS .

Source: Unrestricted.

Destination: Any GenDocumentGroup object.

Parameters: buffer A pointer to a character buffer. This buffer should be of length FILE_LONGNAME_BUFFER_SIZE or greater.

Return: The record of flags stored in GDGI_attrs .

*buffer: Null-terminated name string.

Interception: You should not subclass this message.

Warnings: Make sure the buffer is long enough to hold any file name. Otherwise, the method may overwrite data after the buffer. The constant FILE_LONGNAME_BUFFER_SIZE, defined in file.def , is equal to the maximum file name length, counting the null terminator.

The GDGI_documentClass Field

GDGI_documentClass

Each time a document is opened, the GenDocumentGroup creates a document object. Ordinarily, the document object is a member of GenDocumentClass . However, sometimes the programmer will want to add functionality to the document objects, doing so by defining a subclass of GenDocumentClass . (For example, in the object model of document control, the program implements most functionality by defining new methods for the document class.) If this is the case, the programmer will have to make sure the GenDocumentGroup object creates document objects from the new class. One can do this by setting the GDGI_documentClass field to point to the class structure of the new document object class. By default, this field points to GenDocumentClass .

The GDGI_genDocument Field

GDGI_genDocument

Ordinarily, the document group creates new document objects by instantiating objects from the class specified in GDGI_documentClass . However, you can instead provide a document object for the document group to duplicate. To do this, set the GDGI_genDocument field to the optr of the "template" document object. This object should be marked "not usable."

The GDGI_output Field

GDGI_output, MSG_GEN_DOCUMENT_GROUP_GET_OUTPUT, MSG_GEN_DOCUMENT_GROUP_SET_OUTPUT

Every time something happens which needs to be handled by the application, the document control notifies the application in two ways: The relevant document object sends a message to itself, and the GenDocumentGroup object sends a message to its designated output object. In the Procedural model of document control, the document-object messages are ignored, and the GenDocumentGroup messages are sent to an object (usually the process object) which has handlers for the messages. In the Object model, the GDGI_output attribute is left as a null pointer, and GenDocumentClass is subclassed to handle the messages.

MSG_GEN_DOCUMENT_GROUP_GET_OUTPUT

optr	MSG_GEN_DOCUMENT_GROUP_GET_OUTPUT();

Under the Procedural model of document control, the GenDocumentGroup sends messages to a designated output object. To get the optr of that output object, send this message to the GenDocumentGroup object.

Source: Unrestricted.

Destination: Any GenDocumentGroup object.

Return: Returns the optr of the document group's output object.

Interception: You should not subclass this message.

MSG_GEN_DOCUMENT_GROUP_SET_OUTPUT

void	MSG_GEN_DOCUMENT_GROUP_SET_OUTPUT(
        optr	output); /* The new recipient of the GenDocumentGroup's
		output messages */

Under the Procedural model of document control, the GenDocumentGroup object sends messages to a designated output object. Use this message to change the recipient of the output.

Source: Unrestricted.

Destination: Any GenDocumentGroup object.

Parameters: output The optr of the object which will receive the output.

Interception: You should not subclass this message.

The GDGI_documentControl Field

GDGI_documentControl

The GenDocumentControl and the GenDocumentGroup communicate with each other via messages. To do this, each needs an optr to the other. GDCI_documentControl is an optr to the GenDocumentGroup object for this application. It is set in the source code and is not changed at run time.

Dynamically Creating Displays

GDGI_genDisplay, GDGI_genDisplayGroup, MSG_GEN_DOCUMENT_GROUP_GET_DISPLAY, MSG_GEN_DOCUMENT_GROUP_GET_DISPLAY_GROUP

In a multi-document application, each document will ordinarily have its own GenDisplay object and often many other UI objects as well. The document control can be instructed to dynamically create a number of objects for each new document and destroy these objects when the document is closed.

If an application is going to have the document control create and manage GenDisplay objects, it must declare a GenDisplayGroup object. The GenDisplayGroup should be declared normally; however, it should be given no children. In the source code, the GenDocumentGroup object's GDGI_genDisplayGroup data field should contain an optr to the GenDisplayGroup object.

The application should also declare a template resource. This resource should contain a single generic tree; the top object in this tree should be a GenDisplay object which is set "not usable." The GenDocumentGroup object's GDGI_genDisplay field should contain an optr to that GenDisplay.

When a new document object is created, the document control will automatically copy the resource containing the GenDisplay referenced by GDGI_genDisplay , make the new GenDisplay a child of the GenDisplayGroup referenced by GDGI_genDisplayGroup , and set the new GenDisplay as "usable." When the document object is destroyed (because the document is closed), the document control will automatically destroy that document's copy of the resource.

MSG_GEN_DOCUMENT_GROUP_GET_DISPLAY

optr	MSG_GEN_DOCUMENT_GROUP_GET_DISPLAY();

The GDGI_genDisplay field can be set to point to a GenDisplay object. If GDGI_genDisplay is not a null optr, then the document control will duplicate the resource containing the referenced GenDisplay whenever a new document object is created. The duplicate GenDisplay is made a child of the GenDisplayGroup object indicated by GDGI_genDisplayGroup . By using this message, you can get an optr to that "template" display object. Any changes made to that object will be copied whenever a new document object is created.

Source: Unrestricted.

Destination: Any GenDocumentGroup object.

Return: Returns the optr of the "template" GenDisplay.

Interception: You should not subclass this message.

MSG_GEN_DOCUMENT_GROUP_GET_DISPLAY_GROUP

optr	MSG_GEN_DOCUMENT_GROUP_GET_DISPLAY_GROUP();

If a GenDisplayGroup object is used to manage GenDisplay objects, the GenDocumentGroup object will contain an optr to the GenDisplayGroup. By using this message, you can get an optr to the GenDisplayGroup object.

Source: Unrestricted.

Destination: Any GenDocumentGroup object.

Return: Returns the optr of the GenDisplayGroup object.

Interception: You should not subclass this message.

Connecting Documents with a GenView

GDGI_genView, MSG_GEN_DOCUMENT_GROUP_GET_VIEW

The document control can be instructed to automatically connect the output of a GenView to the document object associated with the view. That way, the document object can handle all the messages relating to the view. This is naturally only done when the application is using the Object model; if it is using the Procedural model, a GenView will most likely send its messages to the Process object.

There are two ways to enable this functionality. One way is appropriate only to single-document applications; the other is appropriate to multi-document applications.

A single-document application using the Object model should declare the GenView normally as part of the generic tree. (It might well be placed on the GenDocumentControl object's GDCI_enableDisableList .) The source code should set the GDGI_genView field to be an optr to the GenView. When a document is opened, the document control will automatically set the GenView object to direct its output to the document object.

A multi-document application using the Object model should use the document control's ability to create and manage GenDisplay objects. The application will have a resource which is duplicated for each open document. This resource will contain a generic tree, at the head of which is a GenDisplay. To use a GenView, all the application has to do is put a GenView in the tree headed by that GenDisplay, and set GDGI_genView to point to that GenView. When a document object is created, the document control will automatically have the new GenView (in the duplicate resource) send its output to the new GenDocument.

MSG_GEN_DOCUMENT_GROUP_GET_VIEW

optr MSG_GEN_DOCUMENT_GROUP_GET_VIEW();

The GenDocumentGroup object can be set to automatically link document objects to GenView objects. Use this message to find out what the designated GenView is. If there is no such GenView , this message will return a null optr.

Source: Unrestricted.

Destination: Any GenDocumentGroup object.

Return: The optr of the GenView object (specified in GDGI_genView).

Interception: You should not subclass this message.

Document Protocols

GDGI_protocolMajor, GDGI_protocolMinor, MSG_GEN_DOCUMENT_GROUP_GET_PROTOCOL

Every GEOS file (and each application that creates such files) has a protocol associated with it. Protocols are used to make sure an application knows if a given document was created by a different version of the application. They are stored in the file's FEA_PROTOCOL extended attributes (see the File System chapter). The protocol is of the form "MAJOR.MINOR," where both "MAJOR" and "MINOR" are 16-bit unsigned integers. The application's protocol is specified by the GDGI_protocolMajor and GDGI_protocolMinor attributes of the GenDocumentGroup object.



All documents created by an application will have the application's protocol number. If a document has the same major protocol number as the application but a lower minor protocol number, the document is compatible with the application. If the document has a lower major protocol number, the document is incompatible with the application; it can be opened only if a routine has been defined to upgrade the document. If the document has a higher protocol than the application (i.e. its major protocol number is higher, or it has the same major protocol number and a higher minor protocol number), the document control will not open the file; it will present an error message. By default, the GenDocumentGroup
 
object has a 
GDGI_protocolMajor
 of one and a 
GDGI_protocolMinor
 of zero.

When the user opens an earlier but compatible document, the GenDocumentGroup opens the file and attaches it to a document object. Then, the (newly-created) document object sends itself 
MSG_GEN_DOCUMENT_UPDATE_EARLIER_COMPATIBLE_DOCUMENT;
 the GenDocumentGroup then sends its output object the message 
MSG_META_DOC_OUTPUT_UPDATE_EARLIER_COMPATIBLE_DOCUMENT
. If neither of these messages is handled, the document will be opened as if it were of the current protocol (since it is compatible). Often an application will not handle these messages.

If the user tries to open an earlier and incompatible document, the GenDocumentGroup opens the file and attaches it to a document object. Then, the document object sends a 
MSG_GEN_DOCUMENT_UPDATE_EARLIER_INCOMPATIBLE_DOCUMENT
 to itself, and the GenDocumentGroup sends a 
MSG_META_DOC_OUTPUT_UPDATE_EARLIER_INCOMPATIBLE_DOCUMENT
 to its output. If neither message is handled, the GenDocumentGroup closes the file unchanged and removes the document object, and the GenDocumentControl presents an error message (since the document is incompatible). If either message is handled, the document will be opened normally after the handler exits.

Note that the document control will not automatically change the protocol number for a file after it has been updated. If you wish this done, you should have the handler for the message call one of the routines to change the FEA_PROTOCOL extended attribute.



 
MSG_GEN_DOCUMENT_GROUP_GET_PROTOCOL
dword	MSG_GEN_DOCUMENT_GROUP_GET_PROTOCOL();

Use this message to get the protocol number associated with the GenDocumentGroup. A protocol number is composed of two parts, a major component and a minor component. This message returns a double-word; the high word is the major component, and the low word is the minor component. 

Source:	Unrestricted.

Destination:	GenDocumentGroupClass.

Return:	Returns a dword-sized value; the high word contains the major protocol number, and the low word contains the minor protocol number.

Interception:	You should not subclass this message.




| GEOS SDK TechDocs
| 
 
 | 2.1 GenDocumentControl Data 
 | 2.3 GenDocument Attributes