Documents: 4.6 Advanced DC Usage: Some Other Internal Messages

| Up: GEOS SDK TechDocs | Up | Prev: 4.5 Forcing Actions 
DocumentCommonParams, MSG_GEN_DOCUMENT_NEW, MSG_GEN_DOCUMENT_OPEN, MSG_GEN_DOCUMENT_CLOSE, MSG_GEN_DOCUMENT_QUICK_BACKUP, MSG_GEN_DOCUMENT_RECOVER_QUICK_BACKUP, MSG_GEN_DOCUMENT_SAVE, MSG_GEN_DOCUMENT_SAVE_AS, MSG_GEN_DOCUMENT_SAVE_AS_TEMPLATE, MSG_GEN_DOCUMENT_COPY_TO, MSG_GEN_DOCUMENT_REVERT, MSG_GEN_DOCUMENT_EDIT_USER_NOTES, MSG_GEN_DOCUMENT_CHANGE_TYPE, MSG_GEN_DOCUMENT_CHANGE_PASSWORD, MSG_GEN_DOCUMENT_RENAME, MSG_GEN_DOCUMENT_SET_EMPTY, MSG_GEN_DOCUMENT_CLEAR_EMPTY, MSG_GEN_DOCUMENT_SET_DEFAULT, MSG_GEN_DOCUMENT_CLEAR_DEFAULT, MSG_GEN_DOCUMENT_CLOSE_IF_CLEAN_UNNAMED, MSG_GEN_DOCUMENT_SEARCH_FOR_DOC, MSG_GEN_DOCUMENT_TEST_FOR_FILE, MSG_GEN_DOCUMENT_AUTO_SAVE, MSG_GEN_DOCUMENT_UPDATE, MSG_GEN_DOCUMENT_CHECK_FOR_MODIFICATIONS, MSG_GEN_DOCUMENT_CLOSE_FILE, MSG_GEN_DOCUMENT_REOPEN_FILE, MSG_GEN_DOCUMENT_GET_VARIABLE, MSG_GEN_DOCUMENT_REVERT_NO_PROMPT, MSG_GEN_DOCUMENT_FILE_CHANGED_REINITIALIZE_CREATED_UI, MSG_GEN_DOCUMENT_CLOSE_IF_OPEN_FOR_IACP_ONLY, MSG_GEN_DOCUMENT_MOVE_TO

The following messages are for internal use by the Document Control objects only. The GenDocumentControl object sends each of these messages to an appropriate GenDocument object to instruct it to perform a certain action; no intervention by the application is necessary, or appropriate. However, some applications may wish to subclass one or more of these messages, simply to find out when the message is being sent (and thus when a particular action is being performed). Any application which does this must make sure to call the superclass without changing any of the arguments.

Several of these messages pass, as an argument, a structure of type DocumentCommonParams . This structure contains information about the file associated with the document object. If you intercept any of these messages, you may wish to examine this structure. However, be sure that you do not alter any of its fields. The structure has the following definition:

 typedef struct {
	FileLongName			DCP_name;
	DiskHandle			DCP_diskHandle;
	PathName			DCP_path;
	GenDocumentAttrs			DCP_docAttrs;
	DocumentOpenFlags			DCP_flags;
	IACPConnection			DCP_connection;
} DocumentCommonParams;
DCP _name
The name of the document in question.
DCP _diskHandle
The dosk handle of the disk (or standard path) containing the document.
DCP _path
The path to the document (relative to the disk handle in DCP _diskHandle ).
DCP _docAttrs
The GenDocumentAttrs of the document in question.
DCP _flags
The DocumentOpenFlags of the document in question.
DCP _connection
If the document is opened for an IACP connection, this field specifies the IACP connection that requestged the document be opened. If the user opened the document directly, this field will be zero. (This field is only set when the structure is passed with MSG_GEN_DOCUMENT_OPEN or MSG_GEN_DOCUMENT_SEARCH_FOR_DOC; otherwise, the field's value is undefined.)

MSG_GEN_DOCUMENT_NEW

Boolean	MSG_GEN_DOCUMENT_NEW(
        word *			fileOrError,
        DocumentCommonParams *			params);

The GenDocumentControl object sends this message to the GenDocument object to instruct it to create a new document.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: params A pointer to a DocumentCommonParams structure. This structure specifies the name and location for the file.

Return: true (i.e., non-zero) if error.

*fileOrError
If return value is false , this will be the file handle of the new document. If return value is true , this will be a member of the FileError enumerated type.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

Structures: The DocumentCommonParams structure (described on typedef struct { FileLongName DCP_name; ).

MSG_GEN_DOCUMENT_OPEN

Boolean	MSG_GEN_DOCUMENT_OPEN(
        word *			fileOrError,
        DocumentCommonParams *			params);

The GenDocumentControl object sends this message to the GenDocument object to instruct it to create a new document.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: params A pointer to a DocumentCommonParams structure. This structure specifies the name and location for the file.

Return: true (i.e., non-zero) if error.

*fileOrError
If return value is false , this will be the file handle of the new document. If return value is true , this will be a member of the FileError enumerated type.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

Structures: The DocumentCommonParams structure (described on typedef struct { FileLongName DCP_name; ).

MSG_GEN_DOCUMENT_CLOSE

DocQuitStatus 				MSG_GEN_DOCUMENT_CLOSE(
        IACPConnection		connection);

The GenDocumentControl object sends this message to the GenDocument object to instruct it to close a document.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: IACPConnection The IACP connection requesting the close (or zero if the close was requested by a user).

Return: A member of the DocQuitStatus enumerated type (described below).

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

Structures: The return value is a member of the DocQuitStatus enumerated type. This type has the following members:

DQS_OK
The documentwas updated and closed successfully.
DQS_CANCEL
The close operation was canceled before it could be completed.
DQS_DELAYED
The close operation has been delayed.
DQS_SAVE_ERROR
The handler was unable to update the file to the disk.

MSG_GEN_DOCUMENT_QUICK_BACKUP

void	MSG_GEN_DOCUMENT_QUICK_BACKUP();

The GenDocumentControl object sends this message to the GenDocument object to instruct it to make a quick backup of a document.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: None.

Return: Nothing.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_RECOVER_QUICK_BACKUP

void	MSG_GEN_DOCUMENT_RECOVER_QUICK_BACKUP();

The GenDocumentControl object sends this message to the GenDocument object to instruct it to recover a document from a quick backup.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: None.

Return: Nothing.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_SAVE

Boolean	MSG_GEN_DOCUMENT_SAVE();

The GenDocumentControl object sends this message to the GenDocument object to instruct it to save a document.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: Nothing.

Return: true if error.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_SAVE_AS

Boolean MSG_GEN_DOCUMENT_SAVE_AS(
        word *			fileOrError,
        DocumentCommonParams *			params);

The Document Control object sends this message to a Document object to instruct it to "Save As" its document. The DocumentCommonParams structure specifies the new name and location for the file.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: fileOrError A pointer to a word-sized variable.

params
A pointer to a DocumentCommonParams structure specifying the new name and location for the file.

Return: true if an error occurred.

*fileOrError
If the routine returned false , this contains the file handle of the new file. If it returned true , this contains a FileError code.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_SAVE_AS_TEMPLATE

Boolean MSG_GEN_DOCUMENT_SAVE_AS_TEMPLATE(
        word *			fileOrError,
        DocumentCommonParams *			params);

The Document Control object sends this message to a Document object to instruct it to save its document as a template. The DocumentCommonParams structure specifies the name and location for the template.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: fileOrError A pointer to a word-sized variable.

params
A pointer to a DocumentCommonParams structure specifying the new name and location for the file.

Return: true if an error occurred.

*fileOrError
If the routine returned false , this contains the file handle of the new file. If it returned true , this contains a FileError code.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_COPY_TO

Boolean	MSG_GEN_DOCUMENT_COPY_TO(
        DocumentCommonParams *			params);

The GenDocumentControl object sends this message to the GenDocument object to instruct it to copy the current document to a new location, while keeping the original copy open. The DocumentCommonParams structure specifies the name and location for the copy.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: params A pointer to a DocumentCommonParams structure specifying the new name and location for the file.

Return: true if error.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_REVERT()

Boolean	MSG_GEN_DOCUMENT_REVERT();

The GenDocumentControl object sends this message to the GenDocument object to instruct it to "Revert" its document.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: None.

Return: true if error.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_EDIT_USER_NOTES

void	MSG_GEN_DOCUMENT_EDIT_USER_NOTES();

The GenDocumentControl object sends this message to the GenDocument object to instruct it to perform an "Edit User Notes" operation.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: None.

Return: Nothing.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_CHANGE_TYPE

void	MSG_GEN_DOCUMENT_CHANGE_TYPE(
        GenDocumentType		type);

The GenDocumentControl object sends this message to the GenDocument object to instruct it to change its document's type to the type specified in type .

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: type The new type of the document.

Return: Nothing.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

Structures: A member of the GenDocumentType enumerated type. This type has the following members:

GDT_NORMAL
The document is a normal document.
GDT_READ_ONLY
The document is available for read-only access.
GDT_TEMPLATE
The document is a template.
GDT_READ_ONLY_TEMPLATE
The document is a template, and is opened read-only.
GDT_PUBLIC
The document is "public" (and thus is, by default, opened read-only).
GDT_MULTI_USER
The document can be read by several users at once.

MSG_GEN_DOCUMENT_CHANGE_PASSWORD

void	MSG_GEN_DOCUMENT_CHANGE_PASSWORD(
        char *		password);

The GenDocumentControl object sends this message to the GenDocument object to instruct it to change the document's password.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: password A pointer to a null-terminated string containing the document's new password.

Return: Nothing.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_RENAME

void	MSG_GEN_DOCUMENT_RENAME();

The GenDocumentControl object sends this message to the GenDocument object to instruct it to rename its document.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: None.

Return: Nothing.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_SET_EMPTY

void	MSG_GEN_DOCUMENT_SET_EMPTY();

The GenDocumentControl object sends this message to the GenDocument object to instruct it to make its document the new model for "empty" documents.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: None.

Return: Nothing.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_CLEAR_EMPTY

void	MSG_GEN_DOCUMENT_CLEAR_EMPTY();

The GenDocumentControl object sends this message to the GenDocument object to inform it that there is no longer a file to serve as the model for "empty" documents.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: None.

Return: Nothing.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_SET_DEFAULT

void	MSG_GEN_DOCUMENT_SET_DEFAULT();

The GenDocumentControl object sends this message to the GenDocument object to instruct it to make its document the default document to open on startup.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: None.

Return: Nothing.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_CLEAR_EMPTY

void	MSG_GEN_DOCUMENT_CLEAR_EMPTY();

The GenDocumentControl object sends this message to the GenDocument object to inform it that there is no longer a default file to open on startup.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: None.

Return: Nothing.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_CLOSE_IF_CLEAN_UNNAMED

void	MSG_GEN_DOCUMENT_CLOSE_IF_CLEAN_UNNAMED();

The GenDocumentControl object sends this message to the GenDocument object to instruct it to close its document if the document has not been changed or saved since it was created.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: None.

Return: Nothing.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_SEARCH_FOR_DOC

Boolean	MSG_GEN_DOCUMENT_SEARCH_FOR_DOC(
        DocumentCommonParams *			params);

The GenDocumentControl object sends this message to the GenDocument object to check if it has the specified document open, and bring it to the front if that document exists.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: params A DocumentCommonParams structure specifying the document sought. The DCP_connection field specifies the IACP connection looking for that document (or zero if the request came directly from the user).

Return: true if the Document object has that document open.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

Structures: The DocumentCommonParams structure (described on typedef struct { FileLongName DCP_name; ).

MSG_GEN_DOCUMENT_TEST_FOR_FILE

Boolean	MSG_GEN_DOCUMENT_TEST_FOR_FILE(
        FileHandle		file,
        optr		*docFound);

The GenDocumentControl object sends this message to the GenDocument object to ask if that Document has the file with the specified handle open. If it does, the GenDocument is to write its optr to the passed variable.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: file The FileHandle of the file being sought.

docFound
A pointer to an optr-sized variable.

Return: true if the Document has the specified file open.

*docFound
The optr of the Document object, if the Document has the specified file open; otherwise, this variable is left unchanged.

Return: Nothing.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_AUTO_SAVE

void	MSG_GEN_DOCUMENT_

The GenDocumentControl object sends this message to the GenDocument object to instruct it to

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: None.

Return: Nothing.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_UPDATE

Boolean	MSG_GEN_DOCUMENT_UPDATE(
        word *		error);

The GenDocumentControl object sends this message to the GenDocument object to instruct it to write changes in its document to the disk.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: error A pointer to a word-sized variable.

Return: true if an error occurred.

*error
A FileError code, or zero if no error occurred.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_CHECK_FOR_MODIFICATIONS

void	MSG_GEN_DOCUMENT_CHECK_FOR_MODIFICATIONS();

The GenDocumentControl object sends this message to the GenDocument object to instruct it to check if its file has been modified on the disk.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: None.

Return: Nothing.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_CLOSE_FILE

void	MSG_GEN_DOCUMENT_CLOSE_FILE(
        IACPConnection		connection);

The GenDocumentControl object sends this message to the GenDocument object to instruct it to close its file, without removing the document object itself. (This is done, e.g., when the Document performs a "Move To"; it must close the file, move it, and reopen it.)

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: connection The IACP connection requesting that the file be closed, or zero if the request came directly from the user.

Return: Nothing.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_REOPEN_FILE

void	MSG_GEN_DOCUMENT_REOPEN_FILE();

The GenDocumentControl object sends this message to the GenDocument object to instruct it to reopen its file (after having handled a MSG_GEN_DOCUMENT_CLOSE_FILE).

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: None.

Return: Nothing.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_GET_VARIABLE

void	MSG_GEN_DOCUMENT_GET_VARIABLE(
        VisTextGraphic *		graphic,
        char *		buffer);

The GenDocumentControl object sends this message to the GenDocument object to get information about a variable graphic. (This message is used by the text object to implement variable graphics.)

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: graphic A pointer to a VisTextGraphic structure.

char
A pointer to a 100-byte buffer.

Return: Both buffers filled in appropriately.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_REVERT_NO_PROMPT

void	MSG_GEN_DOCUMENT_REVERT_NO_PROMPT();

The GenDocumentControl object sends this message to the GenDocument object to instruct it to "Revert" its document without prompting the user.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: None.

Return: true if error.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_FILE_CHANGED_REINITIALIZE_CREATED_UI

void	MSG_GEN_DOCUMENT_FILE_CHANGED_REINITIALIZE_CREATED_UI();

The GenDocumentControl object sends this message to the GenDocument object to inform it that its associated file has changed, and it should reinitialize its UI and reload any cached data.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: None.

Return: Nothing.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_CLOSE_IF_OPEN_FOR_IACP_ONLY

void	MSG_GEN_DOCUMENT_CLOSE_IF_OPEN_FOR_IACP_ONLY()

The GenDocumentControl object sends this message to the GenDocument object to instruct it to close its document if the document is open only for an application-mode IACP connection.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: None.

Return: Nothing.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

MSG_GEN_DOCUMENT_MOVE_TO

Boolean	MSG_GEN_DOCUMENT_MOVE_TO(
        DocumentCommonParams			params);

The GenDocumentControl object sends this message to the GenDocument object to instruct it to perform a "Move To" operation. The DocumentCommonParams structure specifies the new name and location for the file.

Source: The GenDocumentControl object.

Destination: A GenDocument object.

Parameters: params A pointer to a DocumentCommonParams structure. This structure specifies the new name and location for the file.

Return: true (i.e. non-zero) if error.

Interception: This message is not normally intercepted. If you intercept it, be sure to send the message to the superclass with arguments unchanged.

Structures: The DocumentCommonParams structure (described on typedef struct { FileLongName DCP_name; ).

| Up: GEOS SDK TechDocs | Up | Prev: 4.5 Forcing Actions