Input field modification flag

Each input field controlled by a dialog instruction has a modification flag.

The modification flag is used to execute form-level validation rules and trigger ON CHANGE blocks. The flag can also be queried to detect if a field was touched during the DIALOG instruction, for example with the FIELD_TOUCHED() operator or with ui.Dialog.getFieldTouched().

Both FIELD_TOUCHED() and ui.Dialog.getFieldTouched() accept a list of fields and/or the screen-record.* notation in order to check the modification flag of multiple fields in a unique function call. Use a single * star character, to reference all fields used by the dialog.

The modification flag is set to TRUE when the user enters data in a field, or when the program code executes a DISPLAY TO, DISPLAY BY NAME, CLEAR field-spec or CLEAR SCREEN ARRAY screen-array.* instruction. The modification flags can also be set by program to TRUE or reset to FALSE with the ui.Dialog.setFieldTouched() method, to emulate user input, or to reset the modification flags after data is saved in the database.

The modification flags of all fields are automatically reset to FALSE by the interactive instruction in the following cases:

• When the dialog instruction starts.
• In a DIALOG block, when entering a group of fields controlled by an INPUT or a CONSTRUCT sub-dialog.
• When moving to (or creating) a new row in an INPUT ARRAY.
• Within a DISPLAY ARRAY, the modification flags are always TRUE for all fields.

When using a DISPLAY ARRAY, the modification flags are set to TRUE for all fields. This behavior exists because of backward compatibility. Since values cannot be modified by the user, the modification flags are not relevant in this dialog. However, you must pay attention when implementing nested dialogs, because DISPLAY ARRAY will set the modification flags of the fields driven by the parent dialog, for example when executing a DISPLAY ARRAY from an INPUT ARRAY.

Query the modification flags with the ui.Dialog.getFieldTouched() method, typically in the context of AFTER INPUT, AFTER CONSTRUCT, AFTER INSERT or AFTER ROW control blocks.

When using a list driven by an INPUT ARRAY binding, a temporary row added at the end of the list will be automatically removed if all fields have the modification flag set to FALSE.

For typical EDIT fields, the modification flag is set when leaving the field. If you want to detect data modification earlier, it is recommended that you use the dialogtouched predefined action. However, this event is only an indicator that the user started to modify a field, the value will not be available in the program variables.