GEOS SDK TechDocs
|
| 
2 Document Control Data Fields
| 
2.2 GenDocumentGroup Data
The GenDocumentControl handles interaction between the document control and the user. It maintains the File menu entries and manages the file selector. Its attributes all relate to these duties. A complete list of the attributes follows in GenDocumentControl Instance Data along with comments and the default values.
Some of these data fields can be examined but not set by the application. Data fields for purely internal use (which are neither examined, nor set, by applications) are not listed.
Code Display 13-1 GenDocumentControl Instance Data
/* The GDCI_documentToken field specifies the token characters and token ID of
* files managed by this document control. All files created by the document
* control will have these token characters, and the File Selector object will be
* set to allow only such files to be selected. This attribute is ignored if DOS
* files are being opened. */
@instance GeodeToken GDCI_documentToken = {};
/* GDCI_selectorType determines which files will be displayed by the File Selector
* generated by this object. Only one of the options may be set. By default, only
* documents are visible. */
@instance GenFileSelectorType GDCI_selectorType = GFST_DOCUMENTS;
/* Types available:
* GFST_DOCUMENTS, GFST_EXECUTABLES,
* GFST_NON_GEOS_FILES, GFST_ALL_FILES */
/* GDCI_attrs specifies certain characteristics of the file to be opened. The
* default setting is shown below. */
@instance GenDocumentControlAttrs GDCI_attrs =
((GDCM_SHARED_SINGLE << GDCA_MODE_OFFSET) |
GDCA_VM_FILE |
GDCA_SUPPORTS_SAVE_AS_REVERT |
(GDCT_NEW << GDCA_CURRENT_TASK_OFFSET))
/* Attributes available:
* GDCA_MODE:
* GDCM_VIEWER, GDCM_SHARED_SINGLE,
* GDCM_SHARED_MULTIPLE
* GDCA_CURRENT_TASK:
* GDCT_NONE, GDCT_NEW,
* GDCT_OPEN, GDCT_USE_TEMPLATE,
* GDCT_SAVE_AS, GDCT_COPY_TO,
* GDCT_DIALOG, GDCT_TYPE,
* GDCT_PASSWORD
* Other fields:
* GDCA_MULTIPLE_OPEN_FILES, GDCA_DOS_FILE_DENY_WRITE,
* GDCA_VM_FILE, GDCA_NATIVE,
* GDCA_SUPPORTS_SAVE_AS_REVERT, GDCA_DOCUMENT_EXISTS,
* GDCA_DO_NOT_SAVE_FILES
*/
/* GDCI_features specifies certain extra features of the document control. The
* default setting is shown below. */
@instance GenDocumentControlFeatures GDCI_features =
(GDCF_READ_ONLY_SUPPORTS_SAVE_AS_REVERT |
GDCF_SINGLE_FILE_CLEAN_CAN_NEW_OPEN |
GDCF_SUPPORTS_TEMPLATES |
GDCF_SUPPORTS_USER_SETTABLE_EMPTY_DOCUMENT |
GDCF_SUPPORTS_USER_MAKING_SHARED_DOCUMENTS |
GDCF_NAME_ON_PRIMARY);
/* Flags available:
* GDCF_READ_ONLY_SUPPORTS_SAVE_AS_REVERT,
* GDCF_SINGLE_FILE_CLEAN_CAN_NEW_OPEN,
* GDCF_SUPPORTS_TEMPLATES,
* GDCF_SUPPORTS_USER_SETTABLE_EMPTY_DOCUMENT,
* GDCF_SUPPORTS_USER_SETTABLE_DEFAULT_DOCUMENT,
* GDCF_SUPPORTS_USER_MAKING_SHARED_DOCUMENTS,
* GDCF_NAME_ON_PRIMARY */
/* GDCI_enableDisableList specifies objects which should be enabled whenever a
* document is opened and disabled when all documents are closed. The field is the
* handle of a chunk containing a list of optrs to the objects to be enabled and
* disabled. The default value is a null handle.*/
@instance ChunkHandle GDCI_enableDisableList;
/* The GDCI_openGroup, GDCI_importGroup, GDCI_useTemplateGroup, GDCI_saveAsGroup,
* GDCI_exportGroup, and GDCI_userLevelGroup attributes hold optrs to groups of UI
* objects to be added to the "Open," "Import," "Use Template," "Save As,"
* "Export," and "User Level", dialog boxes, respectively. The GDCI_dialogGroup
* field holds an optr to objects to be added to the opening dialog box. The optr
* is to the head of a tree of UI objects. The top object in the tree should be
* set "not usable." Default values are all null optrs. */
@instance optr GDCI_openGroup;
@instance optr GDCI_importGroup;
@instance optr GDCI_useTemplateGroup;
@instance optr GDCI_saveAsGroup;
@instance optr GDCI_exportGroup;
@instance optr GDCI_dialogGroup;
@instance optr GDCI_userLevelGroup;
/* If the GDCI_features field includes "displayNameOnPrimary" but no document is
* open, the Primary's moniker is set to the string pointed to by the
* GDCI_noNameText attribute. The default value is a null chunk handle. */
@instance ChunkHandle GDCI_noNameText;
/* If the GDCA_currentTask section of the GDCI_attrs field is set to
* GDCT_NONE on startup, then the file specified by GDCI_defaultFile will be
* opened (and, if necessary, created). The file is specified by a chunk handle of
* a null-terminated string; this string should specify the file's path relative
* to the SP_DOCUMENT standard path.The default value is a null chunk handle,
* indicating that if the startup value of GDCA_currentTask is GDCT_NONE, no
* documents should be opened. */
@instance ChunkHandle GDCI_defaultFile;
/* GDCI_templateDir is the chunk handle of a null-terminated text string which
* specifies a directory to hold template documents. The directory is specified
* relative to SP_TEMPLATE. If not set by you, this defaults to the SP_TEMPLATE
* standard path. */
@instance ChunkHandle GDCI_templateDir;
/* GDCI_documentGroup is an optr to the GenDocumentGroup object. You must set
* this field. */
@instance optr GDCI_documentGroup;
/* GDCI_targetDocName is a character array. It is set to contain the name of
* the current target file. This field is automatically updated by the document
* control. */
@instance FileLongName GDCI_targetDocName = "";
/* The Document Control automatically displays a big dialog box at startup which * lets the user choose to create, open, etc. a file. Each option has a button * (with a picture) and an explanatory text. You can override the default graphic * or text by setting any of the following fields: */
@instance ChunkHandle GDCI_dialogNewText;
@instance ChunkHandle GDCI_dialogTemplateText;
@instance ChunkHandle GDCI_dialogOpenDefaultText
@instance ChunkHandle GDCI_dialogImportText;
@instance ChunkHandle GDCI_dialogOpenText;
@instance ChunkHandle GDCI_dialogUserLevelText;
@instance @visMoniker GDCI_dialogNewMoniker;
@instance @visMoniker GDCI_dialogTemplateMoniker;
@instance @visMoniker GDCI_dialogOpenDefaultMoniker
@instance @visMoniker GDCI_dialogImportMoniker;
@instance @visMoniker GDCI_dialogOpenMoniker;
@instance @visMoniker GDCI_dialogUserLevelMoniker;
GDCI_documentToken, MSG_GEN_DOCUMENT_CONTROL_GET_TOKEN, MSG_GEN_DOCUMENT_GROUP_GET_TOKEN
The document control's file selector will display only those files whose document token matches the GenDocumentControl object's
GDCI_documentToken
attribute. All files created by the application will have the specified document tokens. There are no messages to alter the token attributes at run-time. (If the document control is used to manage DOS files, the file selector will show all non-GEOS files.)
A token is defined by a
GeodeToken
structure. The format of this structure is shown below. The first field,
GT_chars
, will vary for each document type. The second,
GT_manufID
, will be the same for the tokens of all applications and documents created by a given company.
typedef struct {
char GT_chars[TOKEN_CHARS_LENGTH];
/* TOKEN_CHARS_LENGTH = 4 */
ManufacturerID GT_manufID;
/* word-sized integer */
} GeodeToken;
The message
MSG_GEN_DOCUMENT_CONTROL_GET_TOKEN
instructs the GenDocumentControl object to write a copy of the document token to a specified address. The message has one argument: the address of a
GeodeToken
.
MSG_GEN_DOCUMENT_GROUP_GET_TOKEN
functions identically, but it is sent to the GenDocumentGroup object.
You can also find out the application's token by sending GEN_DOCUMENT_CONTROL_GET_CREATOR or GEN_DOCUMENT_GROUP_GET_CREATOR to the appropriate object. The application's token will be used as the "creator token" for any documents created by the document control.
void MSG_GEN_DOCUMENT_CONTROL_GET_TOKEN(
GeodeToken * token); /* address to copy token to */
This message gets the document token values for all documents created by this document control.
Source: Unrestricted.
Destination:
Any GenDocumentControl object.
Parameters:
token
A pointer to an empty
GeodeToken
structure.
Return: The document
GeodeToken
is written to the variable whose address is passed.
Interception: You should not subclass this message.
void MSG_GEN_DOCUMENT_GROUP_GET_TOKEN(
GeodeToken * token); /* address to copy token to */
This is the same as
MSG_GEN_DOCUMENT_CONTROL_GET_TOKEN
, except that it is sent to the GenDocumentGroup object instead of the GenDocumentControl object.
Source: Unrestricted.
Destination:
Any GenDocumentGroup object.
Parameters:
token
A pointer to an empty
GeodeToken
structure.
Return: The document
GeodeToken
is written to the variable whose address is passed.
Interception: You should not subclass this message.
void MSG_GEN_DOCUMENT_CONTROL_GET_CREATOR(
GeodeToken * token); /* address to copy token to */
This message gets the token for the application; this token is the "creator token" for all files created by the document control.
Source: Unrestricted.
Destination:
Any GenDocumentControl object.
Parameters:
token
A pointer to an empty
GeodeToken
structure.
Return: The document
GeodeToken
is written to the variable whose address is passed.
Interception: You should not subclass this message.
void MSG_GEN_DOCUMENT_GROUP_GET_CREATOR(
GeodeToken * token); /* address to copy token to */
This is the same as
MSG_GEN_DOCUMENT_CONTROL_GET_CREATOR
, except that it is sent to the GenDocumentGroup object instead of the GenDocumentControl object.
Source: Unrestricted.
Destination:
Any GenDocumentGroup object.
Parameters:
token
A pointer to an empty
GeodeToken
structure.
Return: The document
GeodeToken
is written to the variable whose address is passed.
Interception: You should not subclass this message.
GDCI_selectorType
The
GDCI_selectorType
field determines what files will be displayed by and can be opened with the file selector. The options are stored as a byte-sized enumerated type. The options are:
GDCI_attrs, MSG_GEN_DOCUMENT_CONTROL_GET_ATTRS, MSG_GEN_DOCUMENT_GROUP_GET_UI_ATTRS
The GenDocumentControl
object has eight attribute flags stored in the word-sized bitfield
GDCI_attrs
. They may be retrieved by sending
MSG_GEN_DOCUMENT_CONTROL_GET_ATTRS
to the GenDocumentControl
object or by sending
MSG_GEN_DOCUMENT_GROUP_GET_UI_ATTRS
to the GenDocumentGroup object. The attributes are set at coding time; there is no way for an application to change the attributes at run-time, although the GenDocumentControl will change some of the attributes to reflect its current state.
The attributes are
GDCI_attrs = (@default & ~GDCA_MODE) \ | (GDCM_VIEWER << GDCA_MODE_OFFSET);
GenDocumentClass
with handlers for
MSG_GEN_DOCUMENT_PHYSICAL_SAVE_AS
and
MSG_GEN_DOCUMENT_PHYSICAL_REVERT
, but this is not recommended. Ordinarily, this attribute should be off for DOS files.If a document is passed in to be opened at startup (as, for example, when a user launches an application by double-clicking a file created by the application), that file will be opened, and the initial setting of GDCA_CURRENT_TASK will be ignored. The document control automatically maintains this bitfield to correspond to whatever action the document control is currently taking. The application can find out what the document control is doing by reading the attributes and checking this field.
GenDocumentControlAttrs MSG_GEN_DOCUMENT_CONTROL_GET_ATTRS();
Use this message to find out what the GenDocumentControl object's
GDCA_attrs
flags are. The attributes cannot be changed by a message; they can only be read.
Source: Unrestricted.
Destination:
Any GenDocumentControl object.
Parameters: None.
Return: Returns a word-length bitfield containing GDCA
_attrs
record.
Interception: You should not subclass this message.
GenDocumentControlAttrs MSG_GEN_DOCUMENT_GROUP_GET_UI_ATTRS();
This message is the same as the
MSG_GEN_DOCUMENT_CONTROL_GET_ATTRS
message (see above) except that it is sent to the GenDocumentGroup object.
Source: Unrestricted.
Destination:
Any GenDocumentGroup object.
Parameters: None.
Return: A word-length record containing the GDCA
_attrs
field.
Interception: You should not subclass this message.
GDCI_features, MSG_GEN_DOCUMENT_CONTROL_GET_FEATURES, MSG_GEN_DOCUMENT_GROUP_GET_UI_FEATURES, MSG_GEN_CONTROL_CONFIGURE_FILE_SELECTOR
The
GDCI_features
attribute specifies whether certain optional functionality of the Document Control technology is enabled. The features are determined at coding time; there is no message to change features at run-time. To retrieve the features, send
MSG_GEN_DOCUMENT_CONTROL_GET_FEATURES
.
GDCA_MULTIPLE_OPEN_FILES
is on. If GDCF_SINGLE_FILE_CLEAN_CAN_NEW_OPEN is on and GDCA_MULTIPLE_OPEN_FILES is off, the "New" and "Open" triggers are enabled when the document is "clean" (i.e., the document has not been marked "dirty" since it was opened/created or saved); that is, "New" and "Open" are enabled whenever "Save" is disabled. If the user chooses "New" or "Open" when the document is "clean," the target document is closed and the new document is opened or created. If both GDCA_MULTIPLE_OPEN_FILES and GDCF_SINGLE_FILE_CLEAN_CAN_NEW_OPEN are off, the "New" and "Open" triggers are disabled whenever a document is open. By default, this attribute is on.
GDCI_noNameText
. By default, this attribute is on.
For an added degree of control, you can use
MSG_GEN_DOCUMENT_CONTROL_CONFIGURE_FILE_SELECTOR
to change the attributes of the document control's file selector.
GenDocumentControlFeatures MSG_GEN_DOCUMENT_CONTROL_GET_FEATURES();
Use this message to retrieve the current
GDCI_features
flags. The flags cannot be changed at run-time.
Source: Unrestricted.
Destination:
Any GenDocumentControl object.
Parameters: None.
Return: The GenDocumentControl's
GDCI_features
flags.
Interception: You should not subclass this message.
GenDocumentControlFeatures MSG_GEN_DOCUMENT_GROUP_GET_UI_FEATURES();
Use this message to retrieve the current
GDCI_features
flags. The flags cannot be changed at run-time.
Source: Unrestricted.
Destination:
Any GenDocumentGroup object.
Parameters: None.
Return: The GenDocumentControl's
GDCI_features
flags.
Interception: You should not subclass this message.
void MSG_GEN_DOCUMENT_CONTROL_CONFIGURE_FILE_SELECTOR(
optr fileSelector,
word flags); /* GenDocumentControlAttrs */
Configure file selector. This message can be sub-classed to modify the behavior of the file selectors that the document control uses.
GDCI_enableDisableList
The GenDocumentControl can be set to enable certain UI objects when documents are open. This is done using the
GDCI_enableDisableList
attribute. This attribute is the chunk handle of a list of object-pointers. Each of the referenced objects should start as disabled. Whenever a document is opened, a
MSG_GEN_SET_ENABLED
is sent to each object in the list. When the last document is closed, a
MSG_GEN_SET_NOT_ENABLED
is sent to each object in the list.
GDCI_openGroup, GDCI_importGroup, GDCI_useTemplateGroup, GDCI_saveAsGroup, GDCI_exportGroup, GDCI_dialogGroup, GDCI_userLevelGroup
The GenDocumentControl object manages the dialog boxes for many different user actions. The programmer can specify a tree of UI objects to be included with each of these dialog boxes. For example, to add a group of objects to the "Use Template" dialog box, the programmer should put them all in a tree (perhaps by making them all children of a
GenInteraction object) and store an object-pointer to the head of the tree in
the
GDCI_useTemplateGroup
attribute. The top object in the tree should be set "not usable."
GDCI_noNameText
The GenDocumentControl object can be set to display the name of the current target document in the moniker of the
GenPrimary
window. If this feature is enabled, and no document is opened, the
GenPrimary
will have its moniker change to the string specified by
GDCI_noNameText
. If the feature
GDCF_DISPLAY_NAME_ON_PRIMARY is disabled,
GDCI_noNameText
is ignored.
GDCI_defaultFile
If the attribute GDCA_CURRENT_TASK is initially set to GDCT_NONE and a default file is specified, the default file is automatically opened at startup. If GDCA_CURRENT_TASK is not initially set to GDCT_NONE, this attribute is ignored. This field holds the chunk handle of a null-terminated string. The string specifies the file's path relative to the SP_DOCUMENT. If the feature
GDCF_SUPPORTS_USER_SETTABLE_DEFAULT_DOCUMENT is enabled, this attribute can be changed by the user at run-time. If the file specified does not exist, it is created as an empty document; if the document exists but cannot be opened, no file is opened at startup. If the named document exists but is inappropriate (e.g. it was created by another application), no document is opened at startup.
GDCI_templateDir
If templates are supported, this is the default directory for opening and saving them. This string specifies a subdirectory to the standard path SP_TEMPLATE. If not explicitly set in the source code, the template directory will default to SP_TEMPLATE.
GDCI_documentGroup
The GenDocumentControl and the GenDocumentGroup communicate with each other via messages. To do this, each needs the optr of the other. GDCI
_documentGroup
is the optr of the
GenDocumentGroup
object for this application. It is set in the source code and may not be changed at run time.
GDCI_targetDocName
This attribute contains the name of the target document. The document control automatically sets and updates this field when necessary.
GEOS SDK TechDocs
|
| 2 Document Control Data Fields
| 2.2 GenDocumentGroup Data