ETI forms

Changing and fetching the fields on an existing form

Once you create a form with one set of fields using new_form, you can change the fields connected to it.

SYNOPSIS

   int set_form_fields (form, fields)
   FORM  form;
   FIELD  fields;
   
   FIELD  form_fields (form)
   FORM  form;

Like new_form, function set_form_fields takes as an argument a NULL-terminated, ordered array of FIELD pointers that define the fields on the form and determine the order in which the fields are visited during form driver processing.

When set_form_fields is called, the fields previously connected to the form are disconnected from it (but not freed) before the new fields are connected. Like any set of fields connected to a form, the new fields cannot be passed to other forms while they are connected to the given form. You must first disconnect them by calling free_form or again calling set_form_fields.

There are two ways to disconnect the fields associated with a form without connecting another set of fields to the form:

you can call free_form
you can call set_form_fields with fields set to NULL

The first method frees the space allocated for the form, whereas the second does not.

To change the fields associated with form to those referenced in array pointer newfields, you can write:

   FORM * form;
   FIELD ** newfields;
   
   set_form_fields (form, newfields);
   	/* associate new set of fields with form */

If function set_form_fields encounters an error, it returns one of the following:

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

Posting forms is discussed in ``Posting and unposting forms''.

The function form_fields returns the array of field pointers defining the form's fields. The function returns NULL if no fields are connected to the form or the form pointer is NULL.