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 field is a horizontally growable one line field,
its growth will be limited to max_growth columns.
If field is a vertically growable field,
its growth will be limited to max_growth rows.
To remove any growth limit, call set_max_field with
max_growth set to zero.
To query the current maximum, if specified, see dynamic_field_info
below.
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.
This procedure will work regardless of the
setting of the
O_STATIC
option.
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 successful this procedure will return E_OK,
and drows and dcols will contain
the actual number of rows and columns of field.
If a maximum growth has been specified (see set_max_field above)
for field,
max will contain the specified growth limit,
otherwise max will contain zero.
If field is
NULL,
drows,
dcols, and max are unchanged and
the following is returned:
E_BAD_ARGUMENT --
NULL field pointer
This procedure will work regardless of the
setting of the
O_STATIC
option.
Making a field dynamic by turning off the
O_STATIC
option will affect the field in the following ways:
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
Next topic:
Moving a field
Previous topic:
Obtaining field size and location information
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 27 April 2004