NEXT FIELD instruction

Understanding the NEXT FIELD instruction

The NEXT FIELD field-name instruction gives the focus to the specified field and forces the dialog to stay in that field.

This instruction can be used to control field input, in BEFORE FIELD, ON CHANGE or AFTER FIELD blocks, it can also force a DISPLAY ARRAY or INPUT ARRAY to stay in the current row when NEXT FIELD is used in the AFTER ROW block.

If it exists, the BEFORE FIELD block of the corresponding field is executed.

In editable dialogs, the purpose of the NEXT FIELD instruction is to give the focus to an editable field. Make sure that the field specified in NEXT FIELD is active, or use NEXT FIELD CURRENT. Non-editable fields are fields defined with the NOENTRY attribute, fields disabled at runtime with DIALOG.setFieldActive(), or fields using a widget that does not allow input, such as a LABEL.

In a DISPLAY ARRAY using the FOCUSONFIELD attribute, NEXT FIELD can be used in conjunction with DIALOG.setCurrentRow(), to set the focus to a specific cell in the list.

Instead of the NEXT FIELD instruction, you can use the DIALOG.nextField("field-name") method to register a field, for example when the name is not known at compile time. However, this method only registers the field. It does not stop code execution, like the NEXT FIELD instruction does. You must execute a CONTINUE DIALOG to get the same behavior as NEXT FIELD.

Form field identification with NEXT FIELD

With the NEXT FIELD instruction, fields are identified by the form field name specification, not the program variable name used by the dialog.

Form fields are bound to program variables with the binding clause of the dialog instruction (INPUT variable-list FROM field-list, INPUT BY NAME variable-list, CONSTRUCT BY NAME sql ON column-list,CONSTRUCT sql ON column-list FROM field-list, INPUT ARRAY array-name FROM screen-array.*).

The field name specification can be any of the following:

field-name
table-name.field-name
screen-record-name.field-name
FORMONLY.field-name

Here are some examples:

"cust_name"
"customer.cust_name"
"cust_screen_record.cust_name"
"item_screen_array.item_label"
"formonly.total"

When no field name prefix is used, the first form field matching that simple field name is used.

When using a prefix in the field name specification, it must match the field prefix assigned by the dialog field binding method used at the beginning of the interactive statement: When no screen-record has been explicitly specified in the field binding clause (for example, when using INPUT BY NAME variable-list), the field prefix must be the database table name or FORMONLY, as defined in the form file, or any valid screen-record using that field. When the FROM clause of the dialog specifies an explicit screen-record (for example, in INPUT variable-list FROM screen-record.* / field-list-with-screen-record-prefix or INPUT ARRAY array-name FROM screen-array.*), the field prefix must be the screen-record name used in the FROM clause.

Abstract field identification is supported with the CURRENT, NEXT and PREVIOUS keywords. These keywords represent the current, next and previous fields respectively. When using FIELD ORDER FORM, the NEXT and PREVIOUS options follow the tabbing order defined by the form. Otherwise, they follow the order defined by the input binding list (with the FROM or BY NAME clause).

In a procedural dialog, if the focus is in the first field of an INPUT or CONSTRUCT sub-dialog, NEXT FIELD PREVIOUS will jump out of the current sub-dialog and set the focus to the previous sub-dialog. If the focus is in the last field of an INPUT or CONSTRUCT sub-dialog, NEXT FIELD NEXT will jump out of the current sub-dialog and set the focus to the next sub-dialog. NEXT FIELD NEXT or NEXT FIELD PREVIOUS also jumps to another sub-dialog when the focus is in a DISPLAY ARRAY sub-dialog. However, when using an INPUT ARRAY sub-dialog, NEXT FIELD NEXT from within the last column will loop to the first column of the current row, and NEXT FIELD PREVIOUS from within the first column will jump to the last column of the current row - the focus stays in the current INPUT ARRAY sub-dialog. When another sub-dialog gets the focus because of a NEXT FIELD NEXT/PREVIOUS, the newly-selected field depends on the sub-dialog type, following the tabbing order as if the end-user had pressed the tab or Shift-Tab key combination.

NEXT FIELD to a non-editable INPUT / INPUT ARRAY / CONSTRUCT field

Non-editable fields are fields defined with the NOENTRY attribute, fields disabled with ui.Dialog.setFieldActive("field-name", FALSE), or fields using a widget that does not allow input, such as a LABEL.

If a NEXT FIELD instruction specifies a non-editable field, the BEFORE FIELD block of that field is executed. Then the dialog tries to give the focus to that field. Since the field cannot get the focus, the dialog will perform the last pressed navigation key (Tab, Shift-Tab, Left, Right, Up, Down, Accept) and execute the related control blocks, including the AFTER FIELD block of the non-editable field. If no last key is identified, the dialog considers Tab as fallback and moves to the next editable field as defined by the FIELD ORDER mode used by the dialog. Doing a NEXT FIELD to a non-editable field can lead to infinite loops in the dialog; Use NEXT FIELD CURRENT instead.

When selecting a non-editable field with NEXT FIELD NEXT, the runtime system will re-select the current field since it is the next editable field in the dialog. As a result the end user sees no change.

NEXT FIELD in procedural DIALOG blocks

In a procedural dialog block, the NEXT FIELD field-name instruction gives the focus to the specified field controlled by INPUT, INPUT ARRAY or CONSTRUCT, or to a read-only list when using DISPLAY ARRAY.

When using a DISPLAY ARRAY sub-dialog, it is possible to give the focus to the list, by specifying the name of the first column as argument for NEXT FIELD.

If the target field specified in the NEXT FIELD instruction is inside the current sub-dialog, neither AFTER FIELD nor AFTER ROW will be invoked for the field or list you are leaving. However, the BEFORE FIELD control blocks of the destination field (or the BEFORE ROW in case of read-only list) will be executed.

If the target field specified in the NEXT FIELD instruction is outside the current sub-dialog, the AFTER FIELD, AFTER INSERT, AFTER ROW, and AFTER INPUT, AFTER DISPLAY, AFTER /CONSTRUCT control blocks will be invoked for the field or list you are leaving. Form-level validation rules will also be checked, as if the user had selected the new sub-dialog himself. This guarantees the current sub-dialog is left in a consistent state. The BEFORE INPUT, BEFORE DISPLAY, BEFORE CONSTRUCT, BEFORE ROW and the BEFORE FIELD control blocks of the destination field / list will then be executed.

NEXT FIELD in record list control blocks

When using NEXT FIELD in AFTER ROW or in ON ROW CHANGE of a DISPLAY ARRAY or INPUT ARRAY, the dialog will stay in the current row and give control back to the user. This behavior allows you to implement data input rules:

  AFTER ROW
    IF NOT int_flag AND arr_count()<=arr_curr() THEN
       IF arr[arr_curr()].it_count * arr[arr_curr()].it_value > maxval THEN
          ERROR "Amount of line exceeds max value."
          NEXT FIELD item_count
       END IF
    END IF