Guides/Multi-page Forms

A multi-page form is created with creategroup command and a number of sub-forms. As a result, the sub-forms can be flipped through, as in a wizard, or a tabbed form, or a configuration screen.

Specification

Here's annotated specification from wd commands

creategroup id ; causes parent commands to be ignored so that, when a form definition is run, the child controls created are in the current form.

• • we need a main parent form and a number of separate sub-forms for each page; in the resulting form all the controls will be merged into one form;

The id is a control in the current form, usually a tab control, and child-creates are offset from that control.

• • we need an anchor control in the main form to offset the positions of sub-form controls; it can also be a groupbox or a static label or graphic;

Controls created under creategroup are hidden and are part of a group with the id from their ignored pc command. The setshow command with a group id hides or shows the controls in a group.

• • controls within each sub-form are groupped and commonly referenced with the id of their ignored parent, e.g. wd 'set setshow f1 1'

A form definition loaded under creategroup is a normal form definition that can be designed and tested with the form editor. It is loaded by a main form with a form_run that is bracketed by creategroup commands. The first creategroup gives the id of a control in the main form and the final creategroup command has no parameter and ends the group.

creategroup ; ends the group started by a previous creategroup command.

In addition, we need a switch control that will trigger the setshow commands to flip between the pages. It could be a tab control, a listbox, a radiobutton group, or even a couple of Previous/Next wizard buttons.

Example

As an example, we will create a form with two pages. The anchor will be a static separator line. The switch will be a listbox. (Click Main script link to download.) [{{#file: "multi_page.ijs"}} Download script: multi_page.ijs ]

NB. multi_page - example of sub-form groups
NB. 04/20/2007 Oleg Kobchenko

«main form»
«sub-form pages»
«form_run with creategroup»
«switch handler and verb»
«other handlers»
fp_run''

First, we define the main form fp for "form-parent". The stGroup static will used as the anchor and lbSwitch listbox as the switch. [{{#file: "main form"}} Download script: main form ]

FP=: 0 : 0
pc fp;pn "Multi Screen";
xywh 6 6 59 120;cc lbSwitch listbox bottommove;
xywh 73 6 112 10;cc stLabel static;cn "Select";
xywh 70 16 179 1;cc stGroup staticbox ss_etchedhorz rightmove;
xywh 6 132 243 1;cc stBottom staticbox ss_etchedhorz topmove rightmove bottommove;
xywh 143 140 44 12;cc ok button leftmove topmove rightmove bottommove;cn "OK";
xywh 196 140 44 12;cc cancel button leftmove topmove rightmove bottommove;cn "Cancel";
pas 6 6;pcenter;
rem form end;
)

Then need the sub-form pages. Note how they are just ordinary forms that can be created and tested independently with Form Editor. Form ids f1 and f2 will be used to show and hide the sub-forms. [{{#file: "sub-form pages"}} Download script: sub-form pages ]

F1=: 0 : 0
pc f1;pn "Multi Screen";
xywh 6 6 50 10;cc stcOne static;cn "One";
xywh 56 6 50 11;cc edOne edit;
xywh 6 22 50 10;cc stTwo static;cn "Two";
xywh 56 22 50 11;cc edTwo edit;
xywh 6 39 50 10;cc stThree static;cn "Three";
xywh 56 39 50 11;cc edThree edit;
pas 6 6;pcenter;
rem form end;
)

F2=: 0 : 0
pc f2;pn "Multi Screen";
xywh 6 6 50 10;cc stcFour static;cn "Four";
xywh 56 6 50 11;cc edFour edit;
xywh 6 22 50 10;cc stFive static;cn "Five";
xywh 56 22 50 11;cc edFive edit;
pas 6 6;pcenter;
rem form end;
)

Here we create the main form first and then define the sub-form within the creategroup brackets. Note the anchor id is a valid id or one of the main form controls: stGroup static horizontal line here. [{{#file: "form_run with creategroup"}} Download script: form_run with creategroup ]

fp_run=: 3 : 0
  wd FP
  wd 'creategroup stGroup'
  wd F1
  wd F2
  wd 'creategroup'
  wd 'set lbSwitch Alpha Beta'
  wd 'setselect lbSwitch 0'
  'Alpha' switch 0
  wd 'pshow;'
)

The handler of switch control lbSwitch determines the selection and calls the switch verb, which is isolated for calling programmatically such as from main form initialization code. [{{#file: "switch handler and verb"}} Download script: switch handler and verb ]

fp_lbSwitch_select=: 3 : 0
  lbSwitch switch 0".lbSwitch_select
)

switch=: 4 : 0
  wd 'set stLabel *',x
  wd 'setshow f1 ',":y=0
  wd 'setshow f2 ',":y=1
)

Other handlers for closing the main form and showing runtime properties. [{{#file: "other handlers"}} Download script: other handlers ]

fp_close=: 3 : 0
  wd'pclose'
)

fp_ok_button=: 3 : 0
  require 'grid'
  grid wdq
)

Contributed by Oleg Kobchenko.

---