ETI forms

A sample form application program

``Code to produce a simple form'' shows the ETI program necessary for producing the form in ``Sample form display''.

   #include <form.h>
   #include <string.h>

FIELD * make_label (frow, fcol, label) int frow; /* first row */ int fcol; /* first column */ char * label; /* label */ { FIELD * f = new_field (1, strlen (label), frow, fcol, 0, 0);

if (f) { set_field_buffer (f, 0, label); set_field_opts (f, field_opts(f) & ~O_ACTIVE); } return f; }

FIELD * make_field (frow, fcol, cols) int frow; /* first row */ int fcol; /* first column */ int cols; /* number of columns */ { FIELD * f = new_field (1, cols, frow, fcol, 0, 0);

if (f) set_field_back (f, A_UNDERLINE); return f; }

main () { FORM * form; FIELD * f[6]; int i = 0; /* ETI initialization */ initscr (); nonl (); raw (); noecho (); wclear (stdscr); /* create fields */ f[0] = make_label (0, 7, "Sample Form"); f[1] = make_label (2, 0, "Field 1:"); f[2] = make_field (2, 9, 16); f[3] = make_label (3, 0, "Field 2:"); f[4] = make_field (3, 9, 16); f[5] = (FIELD *) 0; /* create and display form */ form = new_form (f); post_form (form); wrefresh (stdscr); sleep (5); /* erase form and free both form and fields */ unpost_form (form); wrefresh (stdscr); free_form (form);

while (f[i]) free_field (f[i++]); /* ETI termination */ endwin (); exit (0); }

Code to produce a simple form

In this example, all text within the form is associated with a field. Fields may be active or inactive: active fields are affected by form processing, inactive fields are not. The underlined fields are active, whereas the label fields Sample Form, Field 1:, and Field 2: are inactive.

Turn now to the program itself. This example starts with two #include files. Every form program must include the header file form.h, which contains important definitions of form objects. This particular program uses the C string library function strlen, so it includes the header file string.h, whose definitions the string library function needs. See string(3C) for details.

Next, there are two programmer-defined functions make_label and make_field, which we will discuss in a moment. Consider procedure main. It declares three objects:

The first five functions initialize low-level ETI (curses) for high-level ETI form functions. Function initscr initializes the screen, nonl ensures that a carriage return on using wgetch will not automatically generate a newline, raw passes input characters uninterpreted to your program, noecho disables echoing of your user's input (the form functions provide echoing where appropriate), and wclear(stdscr) clears the standard screen.

The statements that create the form's fields and labels in this example make calls to the programmer-defined functions make_label and make_field. You can do without these programmer-defined functions, but you may find them convenient. Both of them use the ETI function new_field. They take three arguments, which correspond to three of the six arguments of new_field.

The first argument of new_field is the number of rows of the field. In this example, it is always one. The last two arguments are often 0 as they are here; they will be explained in the next section. The second argument of new_field is the number of columns in the field. This number is determined from the third parameter in main's calls to make_label and make_field. For the label fields, the calls to make_label pass the string that is to constitute the field so that strlen can be used to count the length or number of columns of the string. For the fields to be edited by the end-user (had this example permitted entering data into the fields), calls to make_field simply pass the number of columns directly.

The third and fourth arguments to new_field correspond to the first and second arguments to make_label and make_field. They are the starting position (firstrow, firstcol) of the label or field in the form subwindow. (In this example, the default subwindow stdscr is used.) The last assignment to f[5] terminates the array with the NULL field pointer.

Once the function make_label creates the field for the label, it places the label in the field using function set_field_buffer. The second argument to this function is 0 because the value of a field is stored in buffer 0. Finally, function make_label calls set_field_opts, which turns off the O_ACTIVE option for the field. This means that the field is ignored during form driver processing.

On the other hand, once the function make_field creates the field proper, it sets the field's background attribute to A_UNDERLINE. This has the effect of underlining the field so that it is visible.

After you create the fields for a form, you create the form itself using new_form. This function takes the pointer to the array of field pointers and connects the fields to the form. The pointer returned is stored in variable form -- it will be passed to subsequent form manipulation routines. To display the form, function post_form posts it on the default subwindow stdscr, while wrefresh(stdscr) actually displays this subwindow on the terminal screen. The display remains for 5 seconds, as determined by sleep.

At this point, most forms would accept and process user input. To illustrate a very simple form, this program does not accept user input.

To erase the form, you first unpost it using unpost_form. This erases it from the form subwindow. The call to wrefresh actually erases the form from the display screen. Function free_form disconnects the form from its array of field pointers f.

The while loop, starting with the first field in the field pointer array, frees each field referenced in the array. The effect is to deallocate the space for each field.

We have met the last two lines of the program before. Function endwin terminates low-level ETI, while exit(0) terminates the program.

There are many ETI form routines not listed in ``Code to produce a simple form''. These routines enable you to tailor your form programs to suit local needs and preferences. The following sections explain how to use all ETI form routines. Each routine is illustrated with one or more code fragments. Many of these are drawn from two larger form application programs listed at the end of this topic. By reviewing the code fragments, you will come to understand the larger programs.

Next topic: Creating and freeing fields
Previous topic: What a typical form application program does

© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 27 April 2004