Records dialog events

Reference topic for the records dialog code events set.

Table 1. Records dialog events
Event Use when ... Function
On Action States Update (Record)
The BAM provides predefined actions for "append", "update", "delete", "query", "firstrow", "prevrow", "nextrow", "lastrow". It manages the state (active and hidden) of these actions according to GUI front-end (mobile/desktop) and UI settings (canAdd, etc.). This event is called after the BAM has updated the state of these actions:
  • After navigating (DISPLAY ARRAY)
  • After deleting a row (INPUT ARRAY)
  • After UI synchronization following an internal action (for example, C_ACTION_REFRESH_CURRENT_ROW) to validate a CRUD operation.

If you have actions defined, use this event to set their state (setActionActive/ TRUE|FALSE, setActionHidden/ TRUE|FALSE).

OnActionStatesChange
On Fields Activation

Use this event to set an action that is active only for specific fields when they have the focus. For example, an action to open a zoom form might only apply to a specific field, such as a country field in an address.

OnFieldsActivation
Before Display

Use this event at dialog setup (DISPLAY ARRAY), to display messages to the user, initialize program variables, and set up the dialog instance; for example by deactivating actions the user is not allowed to execute.

 BeforeDisplay
After Display

Use this event when the user changes mode from display mode to input mode by pressing "New", "Modify", or "Search". You can code to display messages to the user, initialize program variables, and set up the dialog instance; for example by deactivating actions the user is not allowed to execute. This event is triggered in a DISPLAY ARRAY dialog.

 AfterDisplay
Before Input

Use this event to display messages to the user, initialize program variables, and set up the dialog instance. You can also use it to detect focus entering or leaving fields controlled by the dialog. This event is triggered at INPUT ARRAY dialog setup.

BeforeInput
After Input

Use this event to implement validation rules (for example, values the user needs to input to satisfy constraints) for several fields in the INPUT or INPUT ARRAY dialog instance.

 AfterInput
Before Construct

Use this event to display messages to the user, initialize form fields with default search criteria values, and set up the CONSTRUCT dialog instance. This event is triggered at CONSTRUCT dialog setup.

BeforeConstruct
After Construct

Use this event to check if the combination of different fields satisfies the criteria for the query. Use it to force the end user to enter all that is required in the CONSTRUCT query.

 AfterConstruct
Before Row
Use this event to find the current row in the DISPLAY ARRAY, or INPUT ARRAY dialog:
  • At setup (if there are rows)
  • Each time the user moves to another row
  • When a row is deleted
  • When the user tries to insert a row in a static array and the maximum number of rows allowed is reached
Use this event to display a message to the user.
Note: Do not use this event to detect focus entering or leaving the dialog; use the Before Input event instead.
 BeforeRow
After Row

Use this event to implement row validation and prevent the user from leaving the list or moving to another row. It can also be used in other situations, for example, when the user deletes a row, or when the user inserts a new row.

AfterRow
Before Insert Row

Use this event to check conditions for the insertion of rows. For example, if the user is not allowed insert rows, the row insertion can be canceled and a message displayed.

This event is triggered when a new row is inserted in a dialog. It is called before the new row is created and made the current one.

If the condition is known before the insert/append action occurs, disable the insert and/or append actions to prevent the user from creating new rows, with dlg.setActionActive(...)

 BeforeInsert
After Insert Row

Use this event in check if a database error would occur if a record was inserted in a database table. You can cancel the row insertion at this point. This event may be triggered to cancel the insert row operation.

 AfterInsert
Before Delete Row

Use this event to cancel the delete operation if the user is not allowed delete rows in the database, or if a database error occurs. This event is triggered before a delete row operation in an INPUT or INPUT ARRAY dialog instance.

BeforeDelete
After Delete Row
Use this event to display, for example, a message to the user about the current row or the number of rows left in the array.
Note: It is too late to cancel row deletion.
This event is triggered after a delete row operation in an INPUT or INPUT ARRAY dialog instance. It is executed after the Before Delete Row event and before the After Row event for the deleted row and the Before Row event for the new current row.
AfterDelete
On Action Append
Use this event to overwrite a predefined action to append a new row to the end of the INPUT ARRAY.
Note: Predefined actions are enabled and disabled automatically by the dialog depending on the context. For example, when a static array used by the INPUT ARRAY is full, the insert and append actions get disabled. Even when overwritten, the program will continue to enable and disable the actions automatically.
 OnActionAppend
On Action Insert

Use this event to overwrite a predefined action to insert a new row before current row in an INPUT ARRAY.

OnActionInsert
On Action Update

Use this event to overwrite a predefined action to update a row in an INPUT ARRAY.

OnActionUpdate
On Action Delete

Use this event to overwrite a predefined action to delete the current row in an INPUT ARRAY.

OnActionDelete
Before Field

Use this event to set action states, initialize field values, or display messages to the user before entering a field for input or query in an INPUT, INPUT ARRAY, or CONSTRUCT dialog.

Note: This event is called only on record fields where:
  • the source field has an outgoing relation to a zoom form.
  • the field has a descending or ascending lookup.
This event is triggered before the end user moves to the new field.
BeforeField
After Field

Use this event to implement field validation rules in an INPUT, INPUT ARRAY, or CONSTRUCT dialog. You can code to verify that a required field was not left blank, and to keep the focus on the same field so the user may enter a value.

Note: This event is called only on record fields where:
  • the source field has an outgoing relation to a zoom form.
  • the field has a descending or ascending lookup.
This event is triggered after the end user moves to a new field.
AfterField
On Change

Use this event to detect when a field which triggers a descending or ascending lookup has been changed by user input.

For example, you can verify that the field was not left blank. If so, display a message to the user.

This event is triggered after the end user moves to a new field.

OnChange