ETI forms

Creating and freeing forms

Once you have established a set of fields and their attributes, you are ready to create a form to contain them.

SYNOPSIS

   FORM  new_form (fields)
   FIELD  fields;
   
   int free_form (form)
   FORM  form;

The function new_form takes as an argument a NULL-terminated, ordered array of FIELD pointers that define the fields on the form. The order of the field pointers determines the order in which the fields are visited during form driver processing discussed below.

As with the comparable ETI menu function new_menu, function new_form does not copy the array of field pointers. Instead, it saves the pointer to the array. Be sure not to change the array of field pointers once it has been passed to new_form, until the form is freed by free_form or the field array replaced by set_form_fields described in the next section.

Fields passed to new_form are connected to the resulting form.

NOTE: Fields may be connected to only one form at a time.

To connect fields to another form, you must first disconnect them using free_form or set_form_fields. If fields is NULL, the form is created but no fields are connected to it.

Unlike menus, ETI forms are logically divided into pages. Two functions enable you to mark a field that is to start a new page and to return a Boolean value indicating whether a given field does so.

SYNOPSIS

   int set_new_page(field, bool)
   FIELD  field;
   int bool;            /* TRUE or FALSE */
   
   int new_page(field)
   FIELD  field;

The initial system default value of new_page is FALSE. This means that, unless specified with set_new_page, each field is assumed to continue the current page.

NOTE: In general, you should make the size of each form page smaller than the form's window size.

If function set_new_page executes successfully, it returns E_OK. If not, it returns one of the following:

E_SYSTEM_ERROR -: system error
E_CONNECTED -: field connected to form

``Creating a form'' shows how to create a simple two-page form.

   FIELD * f[7];
   FORM * form;
   
   /* create fields as described in section "Creating and Freeing Fields" above */
   

   f[0] = new_field (...); /* 1st field on page 1 */
   f[1] = new_field (...); /* 2nd field on page 1 */
   f[2] = new_field (...); /* 3rd field on page 1 */
   f[3] = new_field (...); /* 4th field on page 1 */
   

   f[4] = new_field (...); /* 1st field on page 2 */
   f[5] = new_field (...); /* 2nd field on page 2 */
   

   f[6] = (FIELD *) 0;  /* signal end of form  */
   

   set_new_page (f[4], TRUE); /* start new page with fifth field f[4] */
   

   form = new_form (f); /* create the form */

Creating a form

If successful, new_form returns a pointer to the new form. If there is no memory available for the form or one of the given fields is connected to another form, new_form returns NULL. Undefined results occur if the array of field pointers is not NULL-terminated.

The function free_form disconnects all fields and frees any space allocated for the form. Its argument is a form pointer previously obtained from new_form. The fields themselves are not automatically freed.

NOTE: You should free the fields comprising a form using free_field only after you free their form using free_form.

If successful, free_form returns E_OK. If not, it returns one of the following:

E_SYSTEM_ERROR -: system error
E_BAD_ARGUMENT -: NULL form pointer
E_POSTED -: form is posted

Posting forms is described below.

As with panel, item, menu, and field pointers, form pointers should not be used once they are freed. If they are, undefined results occur.