Manipulating field options
ETI provides several field options for controlling how data is entered and
displayed in a field.
The following functions let
you set or clear these options or read their settings.
SYNOPSIS
int set_field_opts (field, opts)
FIELD field;
OPTIONS opts;
OPTIONS field_opts (field)
FIELD field;
options:
O_VISIBLE
O_ACTIVE
O_PUBLIC
O_EDIT
O_WRAP
O_BLANK
O_AUTOSKIP
O_NULLOK
O_PASSOK
O_STATIC
Function set_field_opts turns off all options that do not appear in its
second argument.
By default, all options are on.
The field options and their effects are as follows:
O_VISIBLE-
determines field visibility.
If this option is on,
the field is
displayed.
If this option is off,
it is erased.
This option is useful for supporting pop-up fields,
fields visible or not depending on another field's value.
O_ACTIVE-
determines if a field is visited during form processing.
If inactivated, the field is ignored during form processing.
Inactive fields enable you to create field labels and
other static form symbols or
changeable
symbols that
are not affected during form processing.
Examples of fields that change value but are not affected during
form processing are row and column totals, as in a spreadsheet
program.
You can change field values
using calls to
set_field_buffer.
O_PUBLIC-
determines how feedback is presented to the user as data is entered.
The data in
public fields is displayed as entered, while
the data in
non-public fields is not displayed at all.
Further, in non-public fields,
the cursor does not actually move across the field,
but the forms subsystem internally maintains
the cursor position relative to the field data.
You can use non-public fields to implement password fields.
O_EDIT-
determines if field editing is permitted.
By default, this option is on and a field may be edited.
If the O_EDIT option is off,
the field may be visited but not changed.
Editing requests or attempts to enter data will fail.
(REQ_PREV_CHOICE and REQ_NEXT_CHOICE requests,
however, are honored, if they
are defined for the field's type.)
This is useful for creating fields for browsing such as
scrollable help messages.
O_WRAP-
determines if word wrapping occurs at the end of each line of the field.
If any character of the word does not fit on the line
as it is entered,
the entire word is
automatically moved to
the beginning of the next line,
if there is one.
If the O_WRAP option is off,
the word is split between the two lines.
O_BLANK-
determines if the whole field is automatically erased
when the end-user types a character in the first character position
of the field before any character position has been changed.
If the O_BLANK option is off,
this does not occur.
O_AUTOSKIP-
determines how the field responds when it becomes full.
Ordinarily, when a field is full, an automatic
request to move to the next field on the form is generated.
If, however, the O_AUTOSKIP option is off,
the end-user remains at the end of the field.
The O_AUTOSKIP option will be ignored if the option
O_STATIC is off and there is no maximum growth specified
for the 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 cause an REQ_NEXT_FIELD to be generated
from the last character position if the field has grown to its maximum size.
O_NULLOK-
determines how the field responds when
your end-user tries to leave a blank field.
By default,
this option is on -- when a field is blank,
a request to leave the field is honored without validating the field.
If, on the other hand, the O_NULLOK option is off,
the validation procedure is applied to
the blank field.
O_PASSOK-
When this option is on, the field is checked for validity only if
your end-user entered data into the field or edited it.
If it is off, the validity check occurs
whenever your user leaves the field,
whether or not the field was changed.
This is useful for fields whose validation function may change dynamically.
O_STATIC-
When this option is on, the field is fixed in size and any attempt
to add more data than the current field buffer will hold will fail.
If it is off, the field will grow dynamically to accommodate additional data
entered by the user.
See
``Dynamically growable fields''
for more information on dynamic fields.
Remember that options are Boolean values.
So to turn off option O_ACTIVE for field f0 and to turn it on
for field f1, you use the Boolean operators and write:
FIELD * f0, * f1;
set_field_opts (f0, field_opts (f0) & ~O_ACTIVE);
/* turn option off */
set_field_opts (f1, field_opts (f1) | O_ACTIVE);
/* turn option on */
NOTE:
Although you can change field option settings on posted forms,
you cannot change option settings for the current field.
ETI also provides the following two functions which let you turn a field option
on or off without using function field_opts.
SYNOPSIS
int field_opts_on (field, opts)
FIELD field;
OPTIONS opts;
int field_opts_off (field, opts)
FIELD field;
OPTIONS opts;
Unlike function set_field_opts, these functions leave unnamed option
settings intact.
As an example, the following code turns options
O_BLANK and O_AUTOSKIP off for
field f0 and on for field f1:
FIELD * f0, * f1;
field_opts_off (f0, O_BLANK | O_AUTOSKIP);
/* turn options off */
field_opts_on (f1, O_BLANK | O_AUTOSKIP);
/* turn options on */
If successful,
functions
set_field_opts, field_opts_on, and field_opts_off return
E_OK.
If not, they return the following:
E_SYSTEM_ERROR --
system error
E_CURRENT --
cannot change current field options
As usual, you can change the ETI default option settings by passing function
set_field_options, field_opts_on, or field_opts_off a
NULL
field pointer.
Calling field_opts with a
NULL
field pointer
returns the system default.
Next topic:
Creating and freeing forms
Previous topic:
Using the field user pointer to match items
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 27 April 2004