XForms: Review and Tutorial

We can rely on fdesign to generate the code for the definition of all forms and objects. That leaves us with two tasks: the initialization code and the callback code.

The initialization code is shown in listing 1. This code defines the main() function in which XForms is initialized, the forms are created, the first form is put on-screen, and the main XForms loop is entered. You can see the call to create_the_forms(); the code of this function is generated by fdesign in the file design.c.

/* xviewfile.c -- main function of xviewfile */
#include \<>forms.h
#include "design.h"
void main (int argc, char **argv)
{
    /* initialize XForms, parse arguments */
    fl_initialize (argv [0], "XViewfile", 0, 0, &argc, argv);
    /* create the forms (fdesign-generated function) */
    create_the_forms ();
    /* show the name input form */
    fl_show_form (name_form, FL_PLACE_MOUSE, FL_FULLBORDER, "Enter a name");
    /* enter XForms loop */
    fl_do_forms ();
    /* not reached... */
}

Now for the second task, the callback code. The callback functions are shown in listing 2. The names of the callback functions were already mentioned in the design specifications; it is therefore important that the exact names are used when writing the functions.

Each callback activated by an object is passed two arguments. The first argument is a pointer to a FL_OBJECT. This argument points by definition to the object which invoked the callback. We will see how this argument is used in the input_cb() function. The second argument is a long int—a value which can be set to any number when defining the callback in the designer. For example, you could have two different objects invoking the same callback function but providing different numeric arguments; inside the function you could distinguish by inspecting the second argument. We won't use this approach in this application.

The callback activated by the quit button is called exit_cb(). This is the easy one—all it does is exit(0). The callback for the input object, input_cb(), needs to perform more tasks. First, the name which was typed by the user must be retrieved. This is done by XForms' function fl_get_input(). Then, we must decide what to do with the input. As specified by the program description above, an empty name should lead to the removal of the browser window from the screen. A non-empty name should be interpreted as a request to view a file.

To accomplish this, input_cb() uses a static int variable to flag whether the browser form is yet on-screen. When a non-empty name is entered and when the browser form is not yet on the screen, fl_show_form() is called to show the browser. Similarly, when an empty name is entered and when the browser form is on-screen, fl_hide_form() is called to remove the browser form. (Instead of using an extra static int, you could also inspect the field int visible, which is part of the FL_FORM struct. I leave such optimizations to the reader.)

The browser itself is manipulated with browser-specific functions fl_clear_browser() and fl_load_browser().

/* callbacks.c --contains the callback routines */
#include <\<>forms.h>
#include "design.h"
void exit_cb (FL_OBJECT *obj, long data)
{
    exit (0);
}
void input_cb (FL_OBJECT *obj, long data)
{
    char const
        *name;                              /* entered filename */
    static int
        browser_on_screen = 0;              /* is browser on-screen yet ? */
    /* determine the entered name */
    name = fl_get_input (obj);
    if (name && *name)                      /* a name was entered */
    {
        if (! browser_on_screen)            /* make sure browser is there */
        {
            fl_show_form (browser_form, FL_PLACE_CENTER,
                          FL_FULLBORDER, name);
            browser_on_screen = 1;
        }
        fl_clear_browser (file_browser);    /* clear previous contents */
        fl_load_browser (file_browser,      /* load in file */
                         name);
    }
    else                                    /* empty input was given */
    {
        if (browser_on_screen)              /* remove browser from screen */
        {
            fl_hide_form (browser_form);
            browser_on_screen = 0;
        }
    }
}

Finally, no program is complete without an automatic maintenance description in a Makefile. Here is an example:

# Makefile -- makefile for xviewfile.
# Used objects:
OBJ = xviewfile.o callbacks.o design.o
# Compilation flags:
CFLAGS = -c -O2 -Wall
# How to make the program:
xviewfile: $(OBJ)
        $(CC) -o xviewfile $(OBJ) -lforms -lX11 -lm
-s
# How to clean up the mess.
clean:
        rm -f $(OBJ)