GEOS SDK TechDocs
|
| 
| 
1 Starting and Stopping
| 
2.1 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.
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.
Return: Nothing.
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
GEOS SDK TechDocs
|
|
| 1 Starting and Stopping
| 2.1 Undo Mechanism