The GenProcess Object

GenProcessClass is the class that you will use to define the Process object of your applications. This class includes some functionality for opening and closing geodes as well as saving to and restoring from state files. Typically, your application will define its own subclass of GenProcessClass ; this subclass will be used as your Process object and will receive all messages destined for the Process.

In this subclass you can alter the GenProcessClass , ProcessClass , or MetaClass messages you need. More often, however, the subclass will be used to define new messages that are application-global or that should be handled by your Process object.

  1 Starting and Stopping
  2 Undo Mechanism
    2.1 Undo Mechanism

The GenProcess Object: 1 Starting and Stopping

For information about the steps involved in stopping, starting, or restoring an application (and to get context information about the messages described below), see the GEOS Programming chapter.

Many of the following messages need AppAttachFlags to tell them how the process is attaching:

typedef WordFlags AppAttachFlags;
#define AAF_RESTORING_FROM_STATE						0x8000
#define AAF_STATE_FILE_PASSED						0x4000
#define AAF_DATA_FILE_PASSED						0x2000
#define AAF_RESTORING_FROM_QUIT						0x1000

• AAF_RESTORING_FROM_STATE indicates that the application is coming up from a previous state, either by re-launching using a state file, or re-entering application mode from engine mode in the same session. The UI trees will be in whatever state they were left in, which may be different than the statically declared UI tree, depending on what occurred in the application when the state file was written out (for example, a dialog box may have been on-screen). If this flag is false , the application is starting up fresh. If this flag is true , the UI does not call MSG_META_LOAD_OPTIONS and ignores any "ON_STARTUP" hints or attributes.
• AAF_STATE_FILE_PASSED indicates that the application is restoring from the state file passed in an AppLaunchBlock , presumably passed as an argument in the message also. If this flag is set, AAF_RESTORING_FROM_STATE will also be set.
• AAF_DATA_FILE_PASSED indicates that the passed AppLaunchBlock contains the name of a data file that should be opened.
• AAF_RESTORING_FROM_QUIT indicates that the application was in the process of quitting, reached engine mode, and is now being started back up into application mode. If set, will also be set, and we will be brought up in whatever state we originally entered engine mode.

MSG_GEN_PROCESS_RESTORE_FROM_STATE

void 	MSG_GEN_PROCESS_RESTORE_FROM_STATE(
        AppAttachFlags 		attachFlags,
        MemHandle 		launchBlock,
        MemHandle 		extraState);

This message is sent by the User Interface when an application is being loaded from a state file. This is sent to the process itself from MSG_META_ATTACH , whenever the application is being invoked as in MSG_GEN_PROCESS_RESTORE_FROM_STATE mode. Data passed is the same as that in MSG_META_ATTACH . The default handler fetches the application mode message, either MSG_GEN_PROCESS_OPEN_APPLICATION or MSG_GEN_PROCESS_OPEN_ENGINE , as saved in the application object, and sends that message to the process.

Note that the blocks passed need not be freed, as this is done by the caller upon return.

Source: Default GenProcessClass handler for MSG_META_ATTACH.

Destination: Self.

Interception: Intercepted generally only so that application can retrieve previously saved data out of the state block passed.

Parameters: attachFlags Flags with information about the state and data files.

launchBlock

Handle of AppLaunchBlock , or zero if none. This block contains the name of any document file passed into the application on invocation.

extraState

Handle of extra state block, or zero if none. This is the same block as returned from MSG_GEN_PROCESS_CLOSE_APPLICATION or MSG_GEN_PROCESS_CLOSE_ENGINE , in some previous MSG_META_DETACH . Process objects often use this extra block to save global variables to state files.

Return: Nothing.

MSG_GEN_PROCESS_OPEN_APPLICATION

void	MSG_GEN_PROCESS_OPEN_APPLICATION(
        AppAttachFlags		attachFlags,
        MemHandle		launchBlock,
        MemHandle 		extraState);

This message is sent by the User Interface when an application is being loaded from its resource blocks. Applications will often intercept this message to set up certain things before being put on-screen. This is the handler in which, for example, you would register for certain notifications such as the quick-transfer notification.

This is sent to the process itself from MSG_META_ATTACH , whenever the application is being restored to application mode (as opposed to engine mode), or whenever it is being invoked as in application mode. Data passed is the same as that in MSG_META_ATTACH . The default handler sets the GenApplication object GS_USABLE, and brings the UI up on screen.

This message may be intercepted to open up any data file passed, before the UI for the application is actually set GS_USABLE. Note that the blocks passed need not be freed, as this is done by the caller upon return.

If you intercept this message and need to send MSG_META_QUIT from within the handler, make sure to either send the quit after calling the superclass, or send the quit via MSG_META_FLUSH_INPUT_QUEUE. (If this is not done, the system will think that an IACP connection is open, aborting the quit.)

Source: GenProcessClass default handler for MSG_META_ATTACH only.

Destination: Same object.

Interception: Frequently intercepted by an application's own process class to find out when an application is first coming alive in the system. You must pass this message on to the superclass, or the application will never come up. Be aware that the entire UI tree for the application is the equivalent of not usable (~GS_USABLE) before the superclass is called, and is usable and up on screen visually after it is called. Thus, it is best to do non-UI related things, and changing of generic attributes and hints before calling the superclass. You must wait until after calling the superclass to perform any operations which require that objects be fully usable (e.g. bringing up a dialog box). Make sure that if you send MSG_META_QUIT from within your handler that you follow the guidelines mentioned above.

Parameters: attachFlags State information about the state and data files.

launchBlock

Handle of AppLaunchBlock , or zero if none. This block contains the name of any document file passed into the application on invocation.

extraState

Handle of extra state block, or zero if none. This is the same block as returned from MSG_GEN_PROCESS_CLOSE_APPLICATION or MSG_GEN_PROCESS_CLOSE_ENGINE , in some previous MSG_META_DETACH .
Is freed by caller--subclasses should not free the extra state block.

Return: Nothing.

MSG_GEN_PROCESS_CLOSE_APPLICATION

MemHandle MSG_GEN_PROCESS_CLOSE_APPLICATION();

This message is sent by the User Interface whenever the application is being shut down (during a detach) and it had been launched in application (as opposed to engine) mode.

Source: GenProcessClass default handler for MSG_META_DETACH only

Destination: Self

Interception: Convenient place for code that needs to be executed before application exits, for non-engine mode cases. Superclass must be called.

Parameters: None.

Return: Handle of block to save (or NULL for none). Process objects often save global variables to a state file in an extra block. This is the handle of that block.

MSG_GEN_PROCESS_OPEN_ENGINE

void 	MSG_GEN_PROCESS_OPEN_ENGINE(
        AppAttachFlags 		attachFlags,
        MemHandle 		launchBlock);

This is sent to the process itself from MSG_META_ATTACH , whenever the application is being restored to engine mode, or whenever it is being invoked as in engine mode. Data passed is the same as that in MSG_META_ATTACH . There is no default handler.

This message may be intercepted to open up any data file passed, before any engine commands are delivered to the process. Note that the blocks passed need not be freed, as this is done by the caller upon return.

Source: GenProcessClass default handler for MSG_META_ATTACH only.

Destination: Self.

Interception: Generally unnecessary, though can be intercepted if notification of going into this mode is necessary.

Parameters: attachFlags State of state and data files.

launchBlock

Handle of AppLaunchBlock , or NULL if none. This block contains the name of any document file passed into the application on invocation.

Return: Nothing.

MSG_GEN_PROCESS_CLOSE_ENGINE

void 	MSG_GEN_PROCESS_CLOSE_ENGINE();

This message is sent by the User Interface whenever the application is being shut down (during a detach) and it had been launched in "engine" mode.

Source: GenProcessClass default handler for MSG_META_DETACH only.

Destination: Self.

Interception: Convenient place for code that needs to be executed before the application exits, for engine mode cases. Superclass must be called.

MSG_GEN_PROCESS_CLOSE_CUSTOM

MemHandle MSG_GEN_PROCESS_CLOSE_CUSTOM();

This message is sent by the User Interface whenever the application is being shut down (during a detach) and it had been launched in some custom mode (not application or engine) that GenProcessClass doesn't know about.

Source: Subclass of GenProcessClass .

Destination: Self.

Interception: Convenient place for code that needs to be executed before the application exits, for custom mode cases. Superclass must be called.

Parameters: None.

Return: Handle of block to save (or NULL for none).

MSG_GEN_PROCESS_ATTACH_TO_PASSED_STATE_FILE

MemHandle 	MSG_GEN_PROCESS_ATTACH_TO_STATE_FILE(
        AppAttachFlags		attachFlags,
        MemHandle		launchBlock);

This message is sent by the User Interface whenever the application is being attached to a state file. This message is sent when either restoring from state or detaching. May be subclassed to provide forced state behavior.

Source: GenProcessClass default handler for MSG_META_ATTACH .

Destination: Self.

Interception: May be intercepted to force use of a particular state file (by changing the name of the state file to use before calling superclass).

Parameters: attachFlags AppAttachMode (matches that in AppLaunchBlock ).

launchBlock

Block of structure AppLaunchBlock .

Return: Handle of extra block of state data (zero for none).

MSG_GEN_PROCESS_CREATE_NEW_STATE_FILE

word MSG_GEN_PROCESS_CREATE_NEW_STATE_FILE(
         MemHandle appInstanceReference);

This replaces MSG_GEN_PROCESS_ATTACHED_TO_PASSED_STATE_FILE if no state file had been specified in that message. This message's default handler will create a new state file and attach it normally. Can be subclassed to provide forced state file usage (e.g. use a different naming scheme).

Source: GenProcessClass default handler for MSG_META_DETACH, if not quitting.

Destination: Self.

Interception: May be intercepted to change name of state file to create.

Parameters: appInstanceReference
Block handle to block of structure AppInstanceReference .

Return: VM file handle (NULL if you want no state file).

MSG_GEN_PROCESS_DETACH_FROM_STATE_FILE

void 	MSG_GEN_PROCESS_DETACH_FROM_STATE_FILE(
        MemHandle 		extraState,
        word 		appStates);

This message is sent by the User Interface when the application is detaching or quitting (may or may not be attached to a state file) and the detach is nearly complete.

Source: GenProcessClass default handler for MSG_META_DETACH , if not quitting.

Destination: Self.

Interception: Not generally done. Default behavior is what you want.

Parameters: extraState Block handle of extra block to be saved (as returned from MSG_GEN_PROCESS_CLOSE_APPLICATION , MSG_GEN_PROCESS_CLOSE_ENGINE or MSG_GEN_PROCESS_CLOSE_CUSTOM ). If the block is not transferred to the state file), it must be freed (if non-zero) by the handler for this message.

appStates

ApplicationStates record with information about the application state.

Return: Nothing.

MSG_GEN_PROCESS_INSTALL_TOKEN

void 	MSG_GEN_PROCESS_INSTALL_TOKEN();

This message is sent by the desktop to a process to get that process to install its token and moniker lists into the token database.

Source: Generally whatever geode launched this application in engine mode (e.g. GeoManager).

Destination: GenProcessClass object of any geode launched in engine mode.

Interception: May be intercepted to install additional tokens. Default behavior installs only application icon.

Parameters: None.

Return: Nothing.

MSG_GEN_PROCESS_GET_PARENT_FIELD

optr 	MSG_GEN_PROCESS_GET_PARENT_FIELD();

This message is sent by process-libraries (such as the Spool Object Library) to find out which field object is its parent. This message will return the field of the first client of the library.

Source: Unrestricted.

Destination: GenProcessClass object.

Interception: Not necessary, as default behavior implements utility.

Parameters: Nothing.

Return: Parent field.

MSG_GEN_PROCESS_SEND_TO_APP_GCN_LIST

void	MSG_GEN_PROCESS_SEND_TO_APP_GCN_LIST(@stack
        word		sendFlags,
        EventHandle 		event,
        MemHandle 		block,
        word		manufListType,
        ManufacturerID 		manufID);

This message sends the specified event to all the objects registered with the passed GCN list. This message should be subclassed by UI Controller objects.

The handler here merely sends the request on to GenApplication using MSG_META_GCN_LIST_SEND . Controllers should use this message, however, over direct communication with the application object, to ensure orderly updating of the list status event. One such failure case which is fixed is two target text objects, one run by the process thread in a view, the other a GenText run by the UI thread. If the GenText has the target and the user clicks quickly on view then GenText, the GenText may process both messages about the target being lost and gained before the process text object receives its gained and lost pair. If both objects sent MSG_META_GCN_LIST_SEND directly to the GenApplication object, the GenText's status would be wiped out by the subsequent reporting by the process text object. This problem is avoided by having both process and UI objects call here to pass status update info. This works because target changes start out ordered in the UI thread, and that order is passed on to the process thread in either of the two cases.

Source: Any object wishing to update an application GCN list. Don't use queue-order altering message flags such as MF_PLACE_IN_FRONT when sending this message. As a convention must be established for the flag MF_FORCE_QUEUE in order to ensure orderly results, the convention in use is this: Don't pass it.
A typical call should use only the MF_STACK, MF_FIXUP_DS, and/or MF_FIXUP_ES flags, if needed.

Destination: GenProcessClass (application process) only.

Interception: Should not generally be intercepted, as GenProcessClass provides correct behavior. If intercepted and not sent onto superclass, event passed must be destroyed and data block reference count decremented, to avoid leaving obsolete data on the heap.

Parameters: sendFlags Flags to pass on to GCNListSend() .

event

Classed event to pass on to the list.

block

Handle of extra data block, if used (otherwise NULL). Blocks of this type must have a reference count, which may be initialized with MemInitRefCount() and be incremented for any new usage with MemIncRefCount() . Methods in which they are passed are considered such a new usage, and must have MetaClass handlers which call MemDerefCount() . Current messages supported are MSG_META_NOTIFY_WITH_DATA_BLOCK and MSG_NOTIFY_FILE_CHANGE .

manufListType

This may be a GCNStandardListType or any other word which acts as a GCN list ID.

manufID

Manufacturer ID, which helps identify the GCN list.

The GenProcess Object: 2 Undo Mechanism

The Undo mechanism is implemented at the GenProcess level; this allows the undo mechanism to be applicable to any application or process. In general, Undo allows a process, usually within an application, but possibly within a library, to reverse changes made in the state of other objects. GEOS allows an almost unlimited number of stored and reversible Undo actions; the practical limit is somewhere around 100 actions.

Undo actions are stored within undo chains . These chains allow queued actions to be undone in reverse order. Each element in an undo chain is made up of an UndoActionStruct . These structures are usually added with an AddUndoActionStruct . This structure has several elements:

typedef struct {
	UndoActionStruct				AUAS_data;
	optr				AUAS_output;
	AddUndoActionFlags				AUAS_flags;
} AddUndoActionStruct

A chain of undo actions is stored for each object. If you want your object to recognize undo-able actions, you must add the undo actions yourself and intercept MSG_META_UNDO when those actions are played back. The object should be able to understand the data within the UndoActionStruct to perform the Undo action.

There are two AddUndoActionFlags which affect when and how undo notification occurs. If AUAF_NOTIFY_BEFORE_FREEING or AUAF_NOTIFY_IF_FREED_WITHOUT_BEING_PLAYED_BACK is set in the AddUndoActionFlags , it not only receives MSG_META_UNDO but also receives MSG_META_UNDO_FREEING_ACTION when the undo mechanism frees the action. You can check the flags in the AddUndoActionStruct passed with this message to decide what action to take.

The object wishing to register an action for undo sends the process MSG_GEN_PROCESS_UNDO_START_CHAIN. For each action in this undo chain (there may be multiple actions in a single chain) send MSG_GEN_PROCESS_UNDO_ADD_ACTION; pass this message the AddUndoActionStruct action of the action to add. Finally, send MSG_GEN_PROCESS_UNDO_END_CHAIN to mark the end of this undo chain. Undo chains may be nested within each other.

The messages following this section also describe supplemental behavior that you may find useful. In addition to these messages, GenProcessClass also provides the following routines:

GenProcessUndoGetFile() returns a file handle of a Huge Array or DB item to hold undo information. Use this routine to get a file to put such undo information into.

GenProcessUndoCheckIfIgnoring() allows an application or library to check whether an application is ignoring undo information; in this case, it can avoid creating unnecessary undo information.

MSG_GEN_PROCESS_UNDO_START_CHAIN

void 	MSG_GEN_PROCESS_UNDO_START_CHAIN(@stack
        optr 	title,
        optr 	owner);

This message notifies the process of the start of an undo-able action. Note that all this message does is increment a count--a new undo chain is created when the count goes from zero to one. This allows a function to perform a number of undo-able actions and have them all grouped as a single undo-able action.

Source: Any object wanting to register an action for undo.

Destination: GenProcessClass only.

Interception: In general, should not be intercepted.

Parameters: title The null-terminated title of this action. If NULL, then the title of the undo action will be the title passed with the next UNDO_START_CHAIN.

owner

The object which owns this action.

Return: Nothing.

MSG_GEN_PROCESS_UNDO_END_CHAIN

void 	MSG_GEN_PROCESS_UNDO_END_CHAIN(
        BooleanWord 		flushChainIfEmpty);

This message notifies the process of the end of an undo-able action. Note that all this message does is decrement a count--the current undo chain is terminated when the count goes from one to zero. This allows a function to perform a number of undo-able actions and have them all grouped as a single undo-able action.

Source: Any object wanting to register an action for undo.

Destination: GenProcessClass only.

Interception: In general, should not be intercepted.

Parameters: flushChainIfEmpty
Non-zero if you want to delete the chain if it has no actions; zero if the chain is OK without actions (actions will be added later).

Return: Nothing.

MSG_GEN_PROCESS_UNDO_ABORT_CHAIN

void	MSG_GEN_PROCESS_UNDO_ABORT_CHAIN();

This message aborts the current undo chain, destroying all actions in place on the current chain, and instructs the undo mechanism to ignore any undo information until the current undo chain is ended. This latter behavior is needed because the current chain may be nested within several chains, so we must ignore undo chain actions until the outermost chain is ended.

Source: Unrestricted.

Destination: GenProcess object.

Interception: Do not intercept.

MSG_GEN_PROCESS_UNDO_ADD_ACTION

VMChain 	MSG_GEN_PROCESS_UNDO_ADD_ACTION(
        AddUndoActionStruct 	*data);

This message adds a new undo action to the current undo chain.

Source: Any object wanting to register an action for undo.

Destination: GenProcessClass .

Interception: In general, should not be intercepted.

Parameters: data Structure containing information which may be used to undo action.

Return: Will return NULL if we are ignoring undo messages.
If the value passed in UAS_datatype was UADT_PTR or UADT_VMCHAIN, then will return a VMChain or DBItem which may be used to undo the action. If neither of the above cases is true, return value is meaningless.

MSG_GEN_PROCESS_UNDO_GET_FILE

VMFileHandle MSG_GEN_PROCESS_UNDO_GET_FILE();

This message returns a VM file handle to store undo actions. This message is useful to access undo data in either a huge array or DB item. You may also use GenProcessUndoGetFile() to retrieve this file instead.

Source: Any object wanting to access the undo file.

Interception: Should not be intercepted.

Parameters: None.

Return: File handle of VM file with undo information.

MSG_GEN_PROCESS_UNDO_FLUSH_ACTIONS

void 	MSG_GEN_PROCESS_UNDO_FLUSH_ACTIONS();

This message flushes the current undo chain (frees all undo actions, notifies edit control that there is no undo item).

Source: Any object using undo.

Interception: Should not be intercepted.

Parameters: None.

Return: Nothing.

MSG_GEN_PROCESS_UNDO_SET_CONTEXT

dword 	MSG_GEN_PROCESS_UNDO_SET_CONTEXT(
        dword 	context);

This message sets the current undo context. This allows the application to have separate undo chains associated with various documents or modes. This should be sent out before any other undo related messages. The document control automatically takes care of this when a document gets the model exclusive.

Passing NULL_UNDO_CONTEXT as the new context will trigger some zealous EC code if any other undo messages are sent while the context is null.

Source: Any object using undo.

Interception: Generally, should not be intercepted. Applications wanting to override the default behavior should at least flush out the current undo actions, as they will probably not be valid in the new context.

Parameters: context New context (this has no meaning to the undo mechanism--it's just a value).

Return: Old context.

Structures:

#define NULL_UNDO_CONTEXT 0

MSG_GEN_PROCESS_UNDO_GET_CONTEXT

dword 	MSG_GEN_PROCESS_UNDO_GET_CONTEXT();

This message gets the current undo context.

Source: Any object using undo.

Interception: Generally, should not be intercepted.

Parameters: None.

Return: Current context.

MSG_GEN_PROCESS_UNDO_PLAYBACK_CHAIN

void 	MSG_GEN_PROCESS_UNDO_PLAYBACK_CHAIN();

This message plays back the current undo chain, one action at a time. It simultaneously creates a "redo" chain, so the undone action can be redone.

Source: Edit control.

Interception: Generally, should not be intercepted.

Parameters: None.

Return: Nothing.

MSG_GEN_PROCESS_UNDO_IGNORE_ACTIONS

void 	MSG_GEN_PROCESS_UNDO_IGNORE_ACTIONS(
        Boolean		flushActions);

This message causes a process to reject any undo messages.

Source: Edit control.

Parameters: flushActions true to flush the queue.

Interception: Generally, should not be intercepted.

MSG_GEN_PROCESS_UNDO_ACCEPT_ACTIONS

void 	MSG_GEN_PROCESS_UNDO_ACCEPT_ACTIONS();

This message causes a process to accept undo messages again.

Source: Edit control.

Interception: Generally, should not be intercepted.

MSG_GEN_PROCESS_UNDO_CHECK_IF_IGNORING

Boolean 	MSG_GEN_PROCESS_UNDO_CHECK_IF_IGNORING();

This message checks to see if the system is currently ignoring undo actions.

Source: Edit control.

Interception: Generally, should not be intercepted.

Parameters: None.

Return: Will return true if ignoring actions.

The GenProcess Object: 2.1 Undo Mechanism: Undo Mechanism

The Undo mechanism is implemented at the GenProcess level; this allows the undo mechanism to be applicable to any application or process. In general, Undo allows a process, usually within an application, but possibly within a library, to reverse changes made in the state of other objects. GEOS allows an almost unlimited number of stored and reversible Undo actions; the practical limit is somewhere around 100 actions.

Undo actions are stored within undo chains . These chains allow queued actions to be undone in reverse order. Each element in an undo chain is made up of an UndoActionStruct . These structures are usually added with an AddUndoActionStruct . This structure has several elements:

typedef struct {
	UndoActionStruct				AUAS_data;
	optr				AUAS_output;
	AddUndoActionFlags				AUAS_flags;
} AddUndoActionStruct

A chain of undo actions is stored for each object. If you want your object to recognize undo-able actions, you must add the undo actions yourself and intercept MSG_META_UNDO when those actions are played back. The object should be able to understand the data within the UndoActionStruct to perform the Undo action.

There are two AddUndoActionFlags which affect when and how undo notification occurs. If AUAF_NOTIFY_BEFORE_FREEING or AUAF_NOTIFY_IF_FREED_WITHOUT_BEING_PLAYED_BACK is set in the AddUndoActionFlags , it not only receives MSG_META_UNDO but also receives MSG_META_UNDO_FREEING_ACTION when the undo mechanism frees the action. You can check the flags in the AddUndoActionStruct passed with this message to decide what action to take.

The object wishing to register an action for undo sends the process MSG_GEN_PROCESS_UNDO_START_CHAIN. For each action in this undo chain (there may be multiple actions in a single chain) send MSG_GEN_PROCESS_UNDO_ADD_ACTION; pass this message the AddUndoActionStruct action of the action to add. Finally, send MSG_GEN_PROCESS_UNDO_END_CHAIN to mark the end of this undo chain. Undo chains may be nested within each other.

The messages following this section also describe supplemental behavior that you may find useful. In addition to these messages, GenProcessClass also provides the following routines:

GenProcessUndoGetFile() returns a file handle of a Huge Array or DB item to hold undo information. Use this routine to get a file to put such undo information into.

GenProcessUndoCheckIfIgnoring() allows an application or library to check whether an application is ignoring undo information; in this case, it can avoid creating unnecessary undo information.

MSG_GEN_PROCESS_UNDO_START_CHAIN

void 	MSG_GEN_PROCESS_UNDO_START_CHAIN(@stack
        optr 	title,
        optr 	owner);

This message notifies the process of the start of an undo-able action. Note that all this message does is increment a count--a new undo chain is created when the count goes from zero to one. This allows a function to perform a number of undo-able actions and have them all grouped as a single undo-able action.

Source: Any object wanting to register an action for undo.

Destination: GenProcessClass only.

Interception: In general, should not be intercepted.

Parameters: title The null-terminated title of this action. If NULL, then the title of the undo action will be the title passed with the next UNDO_START_CHAIN.

owner

The object which owns this action.

Return: Nothing.

MSG_GEN_PROCESS_UNDO_END_CHAIN

void 	MSG_GEN_PROCESS_UNDO_END_CHAIN(
        BooleanWord 		flushChainIfEmpty);

This message notifies the process of the end of an undo-able action. Note that all this message does is decrement a count--the current undo chain is terminated when the count goes from one to zero. This allows a function to perform a number of undo-able actions and have them all grouped as a single undo-able action.

Source: Any object wanting to register an action for undo.

Destination: GenProcessClass only.

Interception: In general, should not be intercepted.

Parameters: flushChainIfEmpty
Non-zero if you want to delete the chain if it has no actions; zero if the chain is OK without actions (actions will be added later).

Return: Nothing.

MSG_GEN_PROCESS_UNDO_ABORT_CHAIN

void	MSG_GEN_PROCESS_UNDO_ABORT_CHAIN();

This message aborts the current undo chain, destroying all actions in place on the current chain, and instructs the undo mechanism to ignore any undo information until the current undo chain is ended. This latter behavior is needed because the current chain may be nested within several chains, so we must ignore undo chain actions until the outermost chain is ended.

Source: Unrestricted.

Destination: GenProcess object.

Interception: Do not intercept.

MSG_GEN_PROCESS_UNDO_ADD_ACTION

VMChain 	MSG_GEN_PROCESS_UNDO_ADD_ACTION(
        AddUndoActionStruct 	*data);

This message adds a new undo action to the current undo chain.

Source: Any object wanting to register an action for undo.

Destination: GenProcessClass .

Interception: In general, should not be intercepted.

Parameters: data Structure containing information which may be used to undo action.

Return: Will return NULL if we are ignoring undo messages.
If the value passed in UAS_datatype was UADT_PTR or UADT_VMCHAIN, then will return a VMChain or DBItem which may be used to undo the action. If neither of the above cases is true, return value is meaningless.

MSG_GEN_PROCESS_UNDO_GET_FILE

VMFileHandle MSG_GEN_PROCESS_UNDO_GET_FILE();

This message returns a VM file handle to store undo actions. This message is useful to access undo data in either a huge array or DB item. You may also use GenProcessUndoGetFile() to retrieve this file instead.

Source: Any object wanting to access the undo file.

Interception: Should not be intercepted.

Parameters: None.

Return: File handle of VM file with undo information.

MSG_GEN_PROCESS_UNDO_FLUSH_ACTIONS

void 	MSG_GEN_PROCESS_UNDO_FLUSH_ACTIONS();

This message flushes the current undo chain (frees all undo actions, notifies edit control that there is no undo item).

Source: Any object using undo.

Interception: Should not be intercepted.

Parameters: None.

Return: Nothing.

MSG_GEN_PROCESS_UNDO_SET_CONTEXT

dword 	MSG_GEN_PROCESS_UNDO_SET_CONTEXT(
        dword 	context);

This message sets the current undo context. This allows the application to have separate undo chains associated with various documents or modes. This should be sent out before any other undo related messages. The document control automatically takes care of this when a document gets the model exclusive.

Passing NULL_UNDO_CONTEXT as the new context will trigger some zealous EC code if any other undo messages are sent while the context is null.

Source: Any object using undo.

Interception: Generally, should not be intercepted. Applications wanting to override the default behavior should at least flush out the current undo actions, as they will probably not be valid in the new context.

Parameters: context New context (this has no meaning to the undo mechanism--it's just a value).

Return: Old context.

Structures:

#define NULL_UNDO_CONTEXT 0

MSG_GEN_PROCESS_UNDO_GET_CONTEXT

dword 	MSG_GEN_PROCESS_UNDO_GET_CONTEXT();

This message gets the current undo context.

Source: Any object using undo.

Interception: Generally, should not be intercepted.

Parameters: None.

Return: Current context.

MSG_GEN_PROCESS_UNDO_PLAYBACK_CHAIN

void 	MSG_GEN_PROCESS_UNDO_PLAYBACK_CHAIN();

This message plays back the current undo chain, one action at a time. It simultaneously creates a "redo" chain, so the undone action can be redone.

Source: Edit control.

Interception: Generally, should not be intercepted.

Parameters: None.

Return: Nothing.

MSG_GEN_PROCESS_UNDO_IGNORE_ACTIONS

void 	MSG_GEN_PROCESS_UNDO_IGNORE_ACTIONS(
        Boolean		flushActions);

This message causes a process to reject any undo messages.

Source: Edit control.

Parameters: flushActions true to flush the queue.

Interception: Generally, should not be intercepted.

MSG_GEN_PROCESS_UNDO_ACCEPT_ACTIONS

void 	MSG_GEN_PROCESS_UNDO_ACCEPT_ACTIONS();

This message causes a process to accept undo messages again.

Source: Edit control.

Interception: Generally, should not be intercepted.

MSG_GEN_PROCESS_UNDO_CHECK_IF_IGNORING

Boolean 	MSG_GEN_PROCESS_UNDO_CHECK_IF_IGNORING();

This message checks to see if the system is currently ignoring undo actions.

Source: Edit control.

Interception: Generally, should not be intercepted.

Parameters: None.

Return: Will return true if ignoring actions.