| Usage / DIALOG control instructions | |
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.
Use the NEXT FIELD instruction to control field input dynamically, in BEFORE FIELD, ON CHANGE or AFTER FIELD blocks, or to control row validation in an AFTER ROW block. NEXT FIELD can also be used to give the focus to a specific field of the form to point the user to that field. With DISPLAY ARRAY, it is possible to give the focus to the list by specifying the name of the first column in 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/DISPLAY/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/DISPLAY/CONSTRUCT, BEFORE ROW and the BEFORE FIELD control blocks of the destination field / list will then be executed.
Abstract field identification is supported with the CURRENT, NEXT and PREVIOUS keywords, which 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, as when the end-user presses the tab/shift-tab keys. Otherwise, NEXT FIELD NEXT/PREVIOUS follow the order defined by the binding list. 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 lastfield 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.
When using NEXT FIELD in AFTER ROW or in ON ROW CHANGE, 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[arr_curr()].it_count * arr[arr_curr()].it_value > maxval THEN
ERROR "Amount of line exceeds max value."
NEXT FIELD item_count
END IF
The purpose of the NEXT FIELD instruction is 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.
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.
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.
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 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:
Here are some examples:
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 according to the 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) used 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.