DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
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.
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