Dynamically growable fields

A dynamically growable field within a form will allow a user to add more data to a field than was specified when the field was originally created. Recall, when a field is created, a buffer is allocated based on the size of the field. With dynamically growable fields, if a user enters more data than the original buffer can hold, the buffer will grow as the user enters more data into the field. The application developer can specify the maximum growth of a field or allow a field to grow without bound.

A field can be made dynamically growable by turning off the O_STATIC field option. See ``Manipulating field options'' for more information on changing field options.

Recall the library routine new_field; a new field created with rows set to one and nrow set to zero will be defined to be a one line field. A new field created with rows + nrow greater than one will be defined to be a multiline field.

A one line field with O_STATIC turned off will contain a single fixed row, but the number of columns can increase if the user enters more data than the initial field will hold. The number of columns displayed will remain fixed and the additional data will scroll horizontally.

A multiline field with O_STATIC turned off will contain a fixed number of columns, but the number of rows can increase if the user enters more data than the initial field will hold. The number of rows displayed will remain fixed and the additional data will scroll vertically.

It may be desirable to allow a field to grow, but within bounds. The following function can be used to limit the growth of a dynamic field either horizontally or vertically.

SYNOPSIS

   int set_max_field(field, max_growth)
   FIELD	field;
   int	max_growth;

If successful this procedure will return E_OK, otherwise the following is returned:

E_BAD_ARGUMENT -

NULL field pointer or field size is already greater than max_growth or max_growth is less than zero.

In order to allow the user to query the current size of the buffer, the following function is provided.

SYNOPSIS

   int dynamic_field_info(field, drows, dcols, max)
   FIELD	  field;
   int	  drows, dcols, max;

If field is NULL, drows, dcols, and max are unchanged and the following is returned:

E_BAD_ARGUMENT -

NULL field pointer

Making a field dynamic by turning off the O_STATIC option will affect the field in the following ways:

1. If parameter nbuf in the original new_field library call is greater than zero, all additional buffers will grow simultaneously with buffer 0. Recall, buffer 0 is used by the system to store data entered by the user, nbuf can be used to request the allocation of additional buffers available to the application. The field buffers will grow in chunks of size buf_size = ((rows + nrow) * cols), the size of the original buffer minus one.

If a field is dynamic, the remainder of the forms library is affected in the following way.

1. The field option O_AUTOSKIP will be ignored if the option O_STATIC is off and there is no maximum growth specified for the field. Currently, O_AUTOSKIP generates an automatic REQ_NEXT_FIELD form driver request when the user types in the last character position of a field. On a growable field with no maximum growth specified, there is no ``last'' character position. If a maximum growth is specified, the O_AUTOSKIP option will work as normal if the field has grown to its maximum size.

2. The field justification will be ignored if the option O_STATIC is off. Currently, set_field_just can be used to JUSTIFY_LEFT, JUSTIFY_RIGHT, JUSTIFY_CENTER the contents of a one line field. A growable one line field will, by definition, grow and scroll horizontally and may contain more data than can be justified. The return from field_just will be unchanged.

3. The overloaded form driver request REQ_NEW_LINE will operate the same way regardless of the O_NL_OVERLOAD form option if the field option O_STATIC is off and there is no maximum growth specified for the field. Currently, if the form option O_NL_OVERLOAD is on, REQ_NEW_LINE implicitly generates a REQ_NEXT_FIELD if called from the last line of a field. If a field can grow without bound, there is no last line, so REQ_NEW_LINE will never implicitly generate a REQ_NEXT_FIELD. If a maximum growth limit is specified and the O_NL_OVERLOAD form option is on, REQ_NEW_LINE will only implicitly generate REQ_NEXT_FIELD if the field has grown to its maximum size and the user is on the last line.

4. The library call dup_field will work as described in ``Creating and freeing fields''; it will duplicate the field, including the current buffer size and contents of the field being duplicated. Any specified maximum growth will also be duplicated.

5. The library call link_field will work as described in ``Creating and freeing fields''; it will duplicate all field attributes and share buffers with the field being linked. If the O_STATIC field option is subsequently changed by a field sharing buffers, how the system reacts to an attempt to enter more data into the field than the buffer will currently hold will depend on the setting of the option in the current field.

6. The library call field_info will work as described in ``Obtaining field size and location information''; the variable nrow will contain the value of the original call to new_field. The user should use dynamic_field_info, described above, to query the current size of the buffer.