ETI forms

Creating and freeing fields

To create a form, you must first create its fields. The following functions enable you to create fields and later free them.

SYNOPSIS

   FIELD  new_field (rows, cols, firstrow, firstcol,
      nrow, nbuf)
   int rows, cols, firstrow, firstcol, nrow, nbuf;
   
   FIELD  dup_field (field, firstrow, firstcol)
   FIELD  field;
   int firstrow, firstcol;
   

   FIELD  link_field (field, firstrow, firstcol)
   FIELD  field;
   int firstrow, firstcol;
   

   int free_field (field)
   FIELD  field;

Unlike menu items which always occupy one row, the fields on a form may contain one or more rows. Function new_field creates and initializes a new field that is rows by cols large and starts at point (firstrow, firstcol) relative to the origin of the form subwindow. All current system defaults are assigned to the new field when it is created using new_field.

Variable nrow is the number of offscreen rows allocated for this field. Offscreen rows enable your program to display only part of a field at a given moment and let the user scroll through the rest. A zero value means that the entire field is always displayed, while a nonzero value means that the field is scrollable. A field can be created with nrow set to zero and allowed to grow and scroll if the field is made dynamic. See ``Dynamically growable fields'' for more detail.

Variable nbuf is the number of additional buffers allocated for this field. You can use it to support default field values, undo operations, or other similar operations requiring one or more auxiliary field buffers.

Variables rows and cols must be greater than zero, while firstrow, firstcol, nrow, and nbuf must be greater than or equal to zero.

Each field buffer is ((rows + nrow) * cols + 1) characters large. (The extra character position holds the NULL terminator.) All fields have one buffer (namely, field buffer 0) that maintains the field's value. This buffer reflects any changes your end-user may make to the field. See ``Setting and reading field buffers'' for more details.

To create a form field occupation one row high and 32 columns wide, starting at position 2,15 in the form subwindow, with no offscreen rows and no additional buffers, you can write:

   FIELD * occupation;
   
   occupation = new_field (1, 32, 2, 15, 0, 0);
   		/* create field */

Generally you create all the fields for a form at the same point in your program, as ``Code to produce a simple form'' demonstrated.

The function dup_field duplicates an existing field at the new location firstrow, firstcol. During initialization, dup_field copies nearly all the attributes of its field argument as well as its size and buffering information. However, certain attributes, such as being the first field on a page or having the field status set, are not duplicated in the newly created field. See ``Creating and freeing forms'' and ``Manipulating field options'' for details on these attributes.

Like dup_field, function link_field duplicates an existing field at a new location on the same form or another one. Unlike dup_field, however, link_field arranges that the two fields share the space allocated for the field buffers. All changes to the buffers of one field appear also in the buffers of the other. Besides enabling your user to enter data into two or more fields at once, this function is useful for propagating field values to later pages where only the first field is active (currently open to form processing). In this case, the inactive fields in effect become dynamic labels. See ``Manipulating field options''.

NOTE: Linked fields share only the space allocated for the field buffers-the attribute values of either field may be changed without affecting the other.

Consider field occupation in the previous example. To duplicate it at location 3,15 and link it at location 4,15, you write:

   FIELD * dup_occ, * link_occ;
   
   dup_occ = dup_field (occupation, 3, 15);
   link_occ = link_field (occupation, 4, 15);

Functions new_field, dup_field, and link_field return a NULL pointer, if there is no available memory for the FIELD structure or if they detect an invalid parameter.

Function free_field frees all space allocated for the given field. Its argument is a pointer previously obtained from new_field, dup_field, or link_field.

NOTE: To free a field, be sure that the field is not connected to a form.

As described in ``Creating and freeing forms'', you can disconnect fields from forms by using functions free_form or set_form_fields.

To free a form and all its fields, you write:

   FORM * form;
   
   /* get pointer to form's field pointer array using
      form_fields described in section below,
      "Changing and Fetching the Fields on an
      Existing Form" */
   

   FIELD ** f = form_fields (form);
   

   free_form (form);          /* free form */
   

   while (*f)
   	free_field (*f++);
   		/* free each field and increment pointer */

Notice that you free the form before its fields.

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

E_SYSTEM_ERROR -: system error
E_BAD_ARGUMENT -: NULL field pointer
E_CONNECTED -: connected field

Remember that the field pointer returned by new_field, dup_field, or link_field is passed to all field routines that record or examine the field's attributes. As with menu items, once a form field is freed, it must not be used again. Because the freed field pointer does not point to a genuine field, undefined results occur.