ETI forms

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.