Managing Model State

• sd-set-model-checkpoint
• sd-return-to-model-checkpoint

Introduction

Note: The functions mentioned in this document can only be used within a User Action (see Dialog Generator Manual for more information on how to create a User Action).

The purpose of the functions is to

• remember a certain model state

while being in a User Action and to

• return to a certain model state

if a specific condition is satisfied.

Examples of where this functionality may be used are:

1. Remember the model state when just entering a User Action. If a condition in the course of the User Action occurs, where the User Action decides that the command cannot succeed, the command can return to the clean model state. At this point the user can change the input values, or he finishes the command.
2. Preview or Next options in a User Command. Before previewing or doing a Next, remember the current model state. Do the operation and if you want to do an Unpreview or Back just return to the previously remembered state.

What's possible, what's not:

1. jumping to a state which was created previous to the current model stage is possible (within the frame of the User Action).
2. jumping to a state which was created later as the current model state is only possible, if after the jump to a previous state no sd-call-cmds or sd-set-model-checkpoint call occured.

SD-SET-MODEL-CHECKPOINT  [function]

(sd-set-model-checkpoint)

Description:

Sets a checkpoint at the current model state.
For a more detailed description of the purpose of this function see the explanation at top of this document.

Return Value:

checkpoint {CHECKPOINT} - the handle to the checkpoint

nil - failure

Example:

(setq recover-state (sd-set-model-checkpoint))

SD-RETURN-TO-MODEL-CHECKPOINT  [function]

(sd-return-to-model-checkpoint checkpoint)

Description:

Returns to the model state where checkpoint was set.
For a more detailed description of the purpose of this function see the explanation at top of this document.

Parameters:

checkpoint {CHECKPOINT} - the handle to a checkpoint where to return to.

Return Value:

t - success

nil - failure

Example:

(setq recover-state (sd-set-model-checkpoint))
;; do some modeling operations (e.g.):
(sd-call-cmds (line :two_points 0,0 100,0))
;; ...
(sd-return-to-model-checkpoint recover-state)