trigger valueChanged
Interactive trigger for that determines what happens after a user changes the value of a field in a form component.
| Declaration: | VALC |
| Applies to: | Field in form components. |
| Activation: | Activated after the user changes a field value. It is not activated if the value of a field is changed in ProcScript. |
| Default behavior: | None |
| Behavior upon completion: | If $status is less
than zero, the user cannot leave the field. Note: Returning a negative value does not cause the original value of the field to be restored; the changed value remains in place. |
Description
The valueChanged trigger enables you to make optimum use of widgets. When it is activated by a widget such as a drop-down list, it can be used for such things as updating the contents of related fields on the screen.
Trigger Activation
The valueChanged trigger is activated as part of the current field processing. When the user leaves the field and the processing of the valueChanged completes successfully, declarative definitions are then verified; this can result in the activation of an error trigger. After the declarative definitions have been verified, the data validation triggers are activated as needed, starting with the loseFocus trigger.
The valueChanged trigger is activated after the user completes a change to the value of a field. When a field is modified for the first time, the startModification trigger of the field is activated. If the startModification trigger completes successfully, subsequent processing depends on the widget type defined for the field.
- For some widgets (such as drop-down lists, radio groups, list boxes, check boxes, and spin buttons), the valueChanged trigger is activated each time the user selects a value for the field. In other words, the widget activates the trigger. The valueChanged trigger is activated each time the user selects a value, regardless of whether the selection is the current value or a new value.
- For other widgets (such as, edit boxes and Unifields), the valueChanged trigger is activated only when the user tries to leave the field.
- User-defined widgets are free to activate this trigger.
The valueChanged trigger is also activated before the detail or help triggers, when either the ^DETAIL or ^HELP structure editor function is used.
The valueChanged trigger is not activated if you use ProcScript to change the value of a field. This is also true if the active path is changed by way of ProcScript statements such as $prompt, setocc, and so on.
Widget Activates the Trigger
If the widget activates the valueChanged trigger, the ProcScript in the trigger is processed with the following results:
- If ProcScript in the trigger returns a positive value (for success), the valueChanged trigger is not reactivated when leaving the field, unless the field is modified again.
- If ProcScript in the trigger returns a negative value (for failure), the valueChanged trigger is reactivated when leaving the field before any data validation processing occurs. Once the valueChanged trigger has failed, the data must be corrected before the field can be left.
Widget Does Not Activate the Trigger
If the widget does not activate the valueChanged trigger, the structure editor activates the valueChanged trigger as the field is left, before any data validation processing occurs. In this situation, the valueChanged trigger is activated when the user moves to another field, before declarative definitions are checked, and before the loseFocus trigger is activated.
