_TPL_Wizard - Wizard pattern (internal data type)

Usage

Wizards are used for supporting a sequence of input actions for non-advanced users. Wizards not only show the data fields to be filled, but also provide extended explanation for each step. Usually, wizards allow providing data step by step. Each time, when changing to the next step, the wizard checks the current input and displays error messages in case of errors. Thus, wizards are very helpful for users, but require more effort by the developer, who has to implement a consistent scenario.

Typically, a wizard runs in a transaction that will be committed, when the wizard is finished or rolled back, when canceling the wizard.

Structure and Design

The wizard form consists of six areas defined in the wizard_frame control.

Title

On top, the wizard title will be displayed. In the example, the title field is defined as symbol control (constant text), which has got a fixed data source containing the text to be displayed. In order to change the text, the data reference for the title field needs to be changed.

Upper

Below the title, the upper text is defined in the upper field, which contains a short description (tool tip) for the currently active wizard control. The upper field is defined as symbol with user-defined data source. The text defined for each wizard step has to be provided in the tool tip text available in the field control for the wizard form. Since text data in field controls is multilingual, there is no problem defining multilingual wizards.

Left corner

The left corner contains the wizard's icon defined in the left_upper field. The left upper field is defined as symbol (image). The image is usually stored in the resource database (resource extent) in the ADK_Bitmap extent. One may, however, also refer to an external image resource, in which case the data source reference type has to be set to user-defined, the image path has to be defined in the data reference field and the class name has to be changed from BLOB to STRING. path is provided in the data source, which is defined as user-defined string data source containing the image path in the data reference field. In order to provide the proper image path, the path in the data reference field has to be updated.

Left

The left pane contains a list of steps to be performed (step titles) and is defined in the left field. The data source for step titles is set to user-defined and need not to be changed. The title list will be generated from the titles defined for the wizard tabs. The currently selected step will be displayed with bold face letters. The left step title list changes the selection each time when starting a new step.

Buttons

On bottom of the wizard, there is a button list, which contains four default buttons (Cancel, Previous, Next, Finish). As long as e.g. the Next button cannot be clicked (because the current wizard form is not filled completely), buttons are disabled. When the button becomes a valid choice, it will be enabled. The Cancel button is always enabled.

Wizard area

The wizard_area forms the active part of the wizard. The wizard area consists of three parts. Besides the wizard control for entering data, the wizard area contains a description area in the upper part (info), which contains a short description what to do within this wizard step. The data source for the info area is user-defined and will be set by the wizard. The description is taken from the long text defined for each wizard step control. In the lower part, there is a message area (message), which allows displaying messages when some action in the wizard step went wrong. Moreover, this area may contain more hints for filling single data fields in the wizard step form. Text can be written to the message area calling the Message() function from the base context class. The data source for the message area is user-defined and will be initialized by the wizard.

Wizard steps

Any number of wizard steps or data controls might be entered in the wizard tab control. The pattern provides typical step controls as wizard_start, wizard_step1 and wizard_stop. The wizard pattern is prepared for defining up to 10 wizard steps. Wizard steps provide necessary input fields for each step. Text definitions for the wizard control provide text data for the step tool tip (upper) in the tool tip field, step title (left) in the title field and step description (info) in the long text field.

Data source

The data source for a wizard is, usually, a complex data type (persistent or transient), which is going to be filled by the wizard. Several elements in the wizard are filled from text information provided by the wizard step controls. The wizard step controls are typically based on the same complex data type as the wizard. When this is not the case, the data source has to be updated for the corresponding wizard steps.

Changing size

Since all wizard step forms need to have the same size, changing size should always start with defining the wizard step control size. The size for the wizard_area and the wizard_frame depends on the size required for info, message and and left, title and and upper areas. The size for the Wizard window is calculated from the size of the wizard_frame control (when set to 0) or should be larger. It is suggested not to allow resizing the wizard window by the user.

Behavior

Wizard windows require an extended amount of behavior implementation. The interaction between wizard steps and wizard_frame and wizard_area is provided in standard context class cStdWizard associated with wizard_area. The wizard is devided in 5 areas. Four of them are controlled by the wizard context class cStdWizard. The left pane shows the action list and the action currently executed. The left upper pane shows the image associated with the action (active image). The upper pane displays the long text defined for the action. The lower (button) pane contains the control buttons. the central pane (wizard) loads the control according to the action name.

Each wizard step should be associated with the cStdWizardBase context class or a context class inheriting from this class. Controls are loaded when pressing the Next or Previous button. DoBeforeFillData() or DoBeforeSaveData() can be overloaded in the wizard context in order to perform additional actions. Pressing the StepIn button (when available) will start a sub wizard with the action name. The sub wizard must be defined as window action.

In order to deny wizard start, one may implement an doBeforeOpen() handler in the wizard_frame context class terminating with error..