Guides/Window Driver/Form Definition

A form is a collection of graphical objects displayed in a single window. The wd command

pc formname

creates a form whose name is formname. Subsequent wd commands apply to the form:

• cc commands create child controls which are graphical objects such as text, dropdown menus, or multimedia displays
• Layout commands control the sizing and alignment of child controls
• other commands apply to the most recently created child, or to the parent

wd commands are directed to the selected form. A form is selected when:

• it is created by pc
• it is selected by wd 'psel'
• an event handler for the form is executed

Commands to a form may be issued any time the form is selected, not merely when the form is created.

By convention the wd commands to create a form are collected into a single noun whose name is the uppercase form of the formname:

MYFORM =: 0 : 0
pc myform;
minwh 20 10;cc verbosemode checkbox;
cc filename edit;
pas 6 6;
)

The form is created, initialized, and displayed with the sequence

wd MYFORM
<initialize form controls here, for example with wd 'set filename text *startup.txt'>
wd 'pshow'

The form is not visible until the wd 'pshow' is executed.

If you conform to the naming convention, the program-flow analyzer lint will know what form-defined names are available to your event handlers.

Example

We next look at a simple example of creating a form to enter information. This example is in a script file included with the J system.

First, clear out any existing definitions with:

   clear''

Then open the script file:

   open '~addons/demos/qtdemo/name.ijs'
or
   open '~addons/ide/qt/demo/name.ijs' (earlier J versions)

You may find it helpful to print out the script file; to do so, with the script window in focus, select the menu item File/Print. The relevant definitions are as follows:

NAME=: 'Jemima Puddle Duck'

EDITNAME=: 0 : 0
pc editname;
minwh 70 10;cc name edit;
cc OK button;
cc Cancel button;
pas 6 6;pcenter;pshow;ptop;
)

NB. this creates and initializes the form:
editname=: 3 : 0
wd EDITNAME
wd 'set name *',NAME
wd 'pshow'
)

NB. this handles the Cancel button:
editname_Cancel_button=: wd bind 'pclose'

NB. this handles the OK button:
editname_OK_button=: 3 : 0

NAME=: name
wd 'pclose'
)

NB. run the form:
editname''

The script defines a global variable, NAME, and a form, EDITNAME, with an edit field and OK and Cancel buttons. The following verbs are also defined:

editname is used to create the form. It sends the form definition EDITNAME to the Window Driver to create the form, then sets the value of the global NAME into the name field.

editname_Cancel_button is used to handle a click on the Cancel button. It simply closes the form.

editname_OK_button is used to handle a click on the OK button. It redefines the global NAME with the current value of the name field, then closes the form.

Try this out by running the script (select menu option Run/Window):

Change the value of the name field, press OK, and check the value of the global, NAME.

Form Locales

A key point about forms is that they may be created and run in any locale, in fact this would typically be the case. Forms can be created as a class, then instantiated as an object when they are to be run. For a description, see the labs on Locales and Object Oriented Programming.

When a form is created, the current locale is recorded as the form locale. This locale is part of the event information, and allows an event to be handled by the form handler in the locale.

For example, this means a form can be run in its own locale, without conflicting in any way with definitions in other locales. You can design a form in the base locale, and run it without change in another locale.

To experiment with this, switch to the J session, and clear out existing definitions in the base locale:

   clear''

Check there are no definitions in the base locale:

   names''

Load the form into a locale myname:

   load_myname_ '~addons/demos/qtdemo/name.ijs'
or
   load_myname_ '~addons/ide/qt/demo/name.ijs' (earlier J versions)

The form is shown. Change the name and click OK to close the form and update the global, NAME. Note that there are still no definitions in the base locale:

   names''

However, there are definitions in the myname locale:

   names_myname_''
EDITNAME               NAME
editname               editname_Cancel_button
editname_OK_button     wdq

Read the value of the name defined:

   NAME_myname_
Squirrel Nutkin

Note that you would normally specify the locale into which a form should be loaded in the form script, either with a cocurrent or a coclass statement at the beginning, for example:

   cocurrent 'myform'