>>  <<  Ndx  Usr  Pri  Phr  Dic  Rel  Voc  !:  wd  Help  Primer

Graphical user interface

These days almost no programming task is complete until it is packaged in a graphical user interface (GUI).

Let's add a GUI to your centigrade and fahrenheit verbs.

There are many steps in building a form and an application. The exact steps you should follow are contained in the series of indented, bulleted items. General discussion and background information is provided in text between these bulleted items.

Run your cf.ijs script and make sure that centigrade and fahrenheit work.

The first step in creating a GUI is to create a form definition. A form definition is stored in a script file just as are all your other definitions.

Create a new script file, save it as a permanent file in the user directory, and start the form editor. The form editor is covered in more detail in the J Online Documentation available on the help menu and you should refer to that if you have problems with the following steps, or want more information at this time.

You should now have the Form Edit dialog box on the screen.

You should now have two new windows on the screen, one in the upper left corner and one in the center of the screen that look something like:

 
 

The small form in the corner is the new form you are editing. The Design dialog allows you to customize the form and is in the middle of the screen. The script file cfgui.ijs has had text added to it that defines the form.

Create a static control in your form with the text centigrade. A static control is used to label other controls.

New controls are created in the upper left corner of the form. You can drag a control with the mouse. To drag a control, point at it with the mouse, hold down the left mouse button and move it.

Create an edit control with an id of cid for the centigrade value. The id is very important as it is used as the name of the noun used for the control as well as being used in commands to indicate which control they affect.

Create a static control with the text Fahrenheit and an edit control with an id of fid.

Experiment a bit with moving the controls around. Grab edges or corners to resize them. If you make a mistake you can select a control with the mouse and press the Delete key to delete it and then recreate it.

Your form should now look something like the following:

The form design is finished. Let's exit the form editor and try running the form.

The form definition is now in the cfgui.ijs script. Let's take a look at what the form editor put into the script. The numbers giving screen coordinate will be different, but your script should look something like:

NB. base form 

CFGUI=: 0 : 0
pc cfgui;
xywh 12 18 40 10;cc ccstatic static;cn "centigrade:";
xywh 56 16 40 14;cc cid edit ws_border es_autohscroll;
xywh 12 40 40 10;cc ccstatic static;cn "Fahrenheit:";
xywh 56 36 40 14;cc fid edit ws_border es_autohscroll;
pas 6 6;pcenter;
rem form end;
)

cfgui_run=: 3 : 0
wd CFGUI
NB. initialize form here
wd 'pshow;'
)

cfgui_close=: 3 : 0
wd'pclose'
)

All interactions with forms are done with the wd (Window Driver) verb. The wd argument is always a string that starts with a command. A string can contain multiple commands separated by semicolons.

The noun CFGUI is defined by the conjunction : in a manner similar to how verbs are defined. The left argument of 0 creates a noun. It is defined as the lines of characters up to the line which contains only the ). It contains the commands that will create the form. Don't worry about the details now, but most of it should make some sense. Commands are followed by parameters and multiple commands on a line are separated by ;. The pc command is a parent create (a form is referred to as a parent). The next line has an xywh command that sets a rectangular area on the form and is followed by a cc command (create child) that creates one of the controls you put on the form.

After the definition of CFGUI you will see that the editor has created a verb called cfgui_run. This verb ignores its argument. It executes the wd verb with CFGUI as an argument. This creates the form, but doesn't show it. The final wd with the argument 'pshow;' will show the parent (form).

At this point the cfgui.ijs script has not been run so the definitions are just text in the script file and have not been defined. After you run the script you are ready to run your application.

When you execute cfgui_run 0 you should see your form in the middle of the screen. Typing into the controls and pressing Enter has no effect because you have no code connected to the events yet.

You can close the form manually by executing the wd command reset that closes all forms.

When you type a value in the centigrade edit control and press Enter you cause an event. An event is identified by the form and the control in which it occurs and the type of the event. An Enter in an edit control is a button event (pressing enter in an edit field is analogous to pressing a button control). So, the event of interest here is for form cfgui, control cid, and is a button event.

When an event occurs, a verb called the event handler is executed. The name of the verb that is executed is determined by the event. The name of an event handler is made up of three parts: formid_controlid_event. So, the event handler of interest has the name cfgui_cid_button.

The event handler cfgui_cid_button should convert the value from the cid edit control to Fahrenheit and then display that result in the fid edit control.

The form editor can automatically create a skeleton of this event handler for you. In the form editor, hold down the Ctrl key and click a control, and you will be switched to editing in the script at the definition of the verb that handles the event for that control.

You closed the form editor, so the first thing is to restart the form editor. Select the cfgui.ijs script and start the form editor with Edit|Form Edit.

Your form should again appear open for editing in the corner of your screen.

You should be positioned at the skeleton definition of cfgui_cid_button in the cfgui.ijs script. You need to define that verb. When the event handler is executed the noun cid will automatically have the value of the contents of the edit field. It will be a string and you need to convert that to a number with the ". primitive.

t =. 0 ". cid

The next thing is to convert that centigrade value to Fahrenheit. 

t =. fahrenheit t

The noun t is the number you want to display in the fid edit control. The number must be converted to a string before it can be shown in an edit field. Use ": (format) for this.

t =. ": t

Finally, write the text string to the fid edit field. 

wd 'set fid ' , t

The wd argument has a command of set, the id of the control to set, and t contains the data to set. The * indicates all the following data is the text to set in the control.

Add these sentences to the definition in the cfgui.ijs script. 

cfgui_cid_button=: 3 : 0
t =. 0 ". cid
t =. fahrenheit t
t =. ": t
wd 'set fid *', t
)

Be careful to type this correctly into your script.

You return to the form editor by holding down the Ctrl key and clicking the script window.

At this point the cfgui.ijs script has not been run so the changes are just text in the script file.

You should see your form in the middle of the screen. Type a number into the centigrade field and press Enter. The Fahrenheit value should display in its field.

If you type into the Fahrenheit field and press Enter nothing happens. This is because you have not provided a handler for that event. If an event handler verb is not defined, the event is ignored. Let's define the event handler for Enter in the Fahrenheit field now. Start the form editor and hold down the Ctrl key and click the fid control to get to the definition of the verb for that event. The definition for cfgui_fid_button is similar to that of cfgui_cid_button.

cfgui_fid_button=: 3 : 0
t =. 0 ". fid
t =. centigrade t
wd'set fid *', ": t
)

Now when you type a value in the Fahrenheit field and press Enter it will be converted and display in the centigrade field.

Finally, add a close button so that the form will be able to close itself. The event handler will be as follows:

cfgui_close_button=: 3 : 0
wd 'pclose'
)

The wd command pclose (parent close) closes the form.

When you tire of doing conversions you can press the Close button to close your form.

Congratulations! you have written a GUI application in J. It is simple and has rough edges, but you are over the high hurdles.

>>  <<  Ndx  Usr  Pri  Phr  Dic  Rel  Voc  !:  wd  Help  Primer