|
|
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;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.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;
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;Generally you create all the fields for a form at the same point in your program, as ``Code to produce a simple form'' demonstrated.occupation = new_field (1, 32, 2, 15, 0, 0); /* create field */
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''.
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.
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;Notice that you free the form before its fields./* 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 */
If successful, function free_field returns E_OK. If not, it returns one of the following: