XForms: Review and Tutorial

The archive containing the XForms toolkit is currently named bxform-075.tgz, 075 being the version number. After you obtain the archive, change-dir to a sources directory (such as /usr/src) and extract the archive using tar xvzf bxform-075.tgz

The archive spills into a subdirectory xforms where you will find the Makefile. By default, a make install copies the library libforms.a and the header file forms.h to respectively /usr/lib and /usr/include. The designer, fdesign, goes in /usr/local/bin. If you want to use other paths, edit the file mkconfig.h before you make install.

If you want to see the demos, type make/and wait (this takes some time to complete). Then cd DEMOS and type ./demo.

Having introduced XForms, I want to show you the steps to create a real XForms program. For the sake of simplicity, I present a program that manages only two forms. One of the forms has an input object, in which a user can enter a filename. This form also has a quit button to terminate the program. The other form has a browser object, in which the contents of the file are displayed. Using the scroll bar in the browser, the user can view different parts of the file.

As for the behavior of the program, we'll decide that only the form with the input object and the quit button is initially on-screen. When the user enters a filename, the form with the browser containing the file's contents appears. When an empty filename is entered, the form with the browser disappears again.

First of all, we should decide on some names. The forms will be called respectively name_form and browser_form. Inside the name_form there will be two objects: one input object to allow the user to type a filename and one button to quit. Both objects will need callbacks to take the appropriate actions: the functions will be respectively input_cb() and exit_cb(). These objects can remain nameless, which means that the designer will not generate global variables to address them.

The browser_form needs only one object in it: a browser object. This object does not need a callback since the browser will not accept user interaction (except the movement of the scroll-bar, which is handled internally by the browser). However, we will need a global variable for this browser since the callback of the input object of the first form must be able to fill the browser with the contents of a given file. We will call the browser file_browser.

Now that we have decided on the names of forms and objects, we can design the forms. The XForms designer can be started with fdesign design &, telling it to save its output in the files design.fd (the design itself), design.c (generated C code) and design.h (generated header file). The ampersand starts fdesign in the background.

Once the designer comes up, click on the “New Form” button to start a new form and enter the form name name_form. You can rescale the window that appears to a suitable size. After this, put the required objects in the form: an input object and a button. These objects can be selected in the “Objects” menu of the designer. Once an object is placed in the form, you can resize or move it using the mouse. The “Align” button lets you define the stepsize in pixels by which the objects are scaled or moved. Pressing F1 activates an “Attributes” window, in which the object attributes (such as font, color, callback) can be defined.

As far as the name_form is concerned, you should create something that looks like the screen dumps in figures 1 and Figure 2. Figure 1 shows the designer window itself, the name form, and the attribute window of the input object. (Yes, I wrote the program around noon.) In this figure the input object is “active” as can be seen by the red box around it.

Figure 2 shows the quit button and its properties.

To define the browser form, click again on “New Form” to start a second form. Enter browser_form as the form name, and resize the form window to your liking. Then select a “browser” object from the Objects menu and add it to the form. The form, its browser object and the properties of the browser are shown in Figure 3.

Having defined the form, we can let fdesign generate its code. Click on the “Options” button and toggle the “Alt format” entry to light up the button in front of this menu entry. This instructs fdesign to generate simple code, instead of placing form and object variables into structs. For this application, simple code suffices. Then click on the “File” button, save the file, and exit fdesign.