|
|
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;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.int free_form (form) FORM form;
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.
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 */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.int new_page(field) FIELD field;
If function set_new_page executes successfully, it returns E_OK. If not, it returns one of the following:
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.
If successful, free_form returns E_OK. If not, it returns one of the following:
As with panel, item, menu, and field pointers, form pointers should not be used once they are freed. If they are, undefined results occur.