To write a Wizard, a module that runs in its own window is required. The recommended window parameters are:
Width = 520
Height = 360
Style = 0b1010010100000111
It is perfectly feasible to run a Wizard within a Display Manager page. To do this, the following attributes should be defined in the page's source file.
Constant WinFlag = 1;
Constant PageStyle = 0;
Constant
PageWidth = 520;
Constant PageHeight = 360;
Constant PagWinOpt =
0b1010010100000111;
Constant NoStretch = 1;
For reasons that should become clear, the recommended (but not the only) way of structuring the Wizard module is to have an outer module with two states, with all the necessary initialization done on the transition between these, and a child module containing the Wizard code, which is launched as the final step.
The subsequent description will assume this model and will use the term "Parent" to refer to the outer module, and "Wizard" to refer to the Wizard code module.
As mentioned, the Parent performs the initialization of resources required by the Wizard. It is also likely that in its main state, it has to monitor a Cancel flag and to tear down the structure if the flag is set.
The Wizard has a few special requirements:
• The first step of the Wizard user interface must correspond to the first state in the module.
• The Wizard must launch a copy of \WizardEngine into its own scope. It will need to retain the Object value in order to access the helper modules.
• A number of variables which are passed to the instance of \WizardEngine, and that control the action of the Wizard are required.
• The Wizard must have a state named, "Finish". This is not necessarily the final state in the Wizard, but is the final step of the user interface. As many additional states as are required to perform the Wizard's completion tasks may come after the "Finish" state.
• If the Wizard is to perform Tag configuration, it may be useful for the Wizard to be instantiated with a suitable Parms array and a Root variable so that it can impersonate a tag instance.
In practice, the Wizard module starts at its first state and is then navigated between its various states by the controlling WizardEngine that responds to the user's use of the "Next" and "Back" buttons, as well as providing the programmatic flow control. Once the Wizard reaches its "Finish" state, and the user presses the "Finish" button, the Wizard then does whatever is required to perform its required operations. There is no going back from this point; the Wizard must complete its task. All necessary validation must be performed prior to the Wizard reaching the Finish state.