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)

Use this code event to manage the action state for actions defined for the record, by setting an action as active (setActionActive/ TRUE|FALSE) or hidden (setActionHidden/ TRUE|FALSE).

The predefined actions for a record include:

  • append
  • update
  • delete
  • query
  • firstrow
  • prevrow
  • nextrow
  • lastrow

The state of an action is determined by the relation setting (disable Add, disable Modify, disable Delete, disable Search).

This event is triggered after the program updates the state of these actions:
  • After navigating (DISPLAY ARRAY)
  • After deleting a row (INPUT ARRAY)
  • After UI synchronization following validation of a CRUD operation
 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.

This event is triggered at DISPLAY ARRAY dialog setup.

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 an INPUT (fields in a GRID container) dialog instance.
Note:

For an INPUT ARRAY (fields in a row in a table container) dialog instance, use the After Row event.

This event is called before the default CRUD validation that the BAM generates for an INSERT, UPDATE, or DELETE. This means the event occurs before:
  • prompting the user for confirmation with a (Yes/No/Cancel) dialog
  • processing the CRUD operation or in the case of failure displaying the SQL error and continuing the dialog.
 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 validation rules (for example, values the user needs to input to satisfy constraints) in the INPUT ARRAY (fields in a row in a table container) dialog instance.
Note:

For an INPUT (fields in a GRID container) dialog instance, use the After_Input event.

Use this event also for validation, for example, when the user deletes a row, or when the user inserts a new row.
This event is called before the default CRUD validation that the BAM generates for an INSERT, UPDATE, or DELETE. This means the event occurs before:
  • prompting the user for confirmation with a (Yes/No/Cancel) dialog
  • processing the CRUD operation or in the case of failure displaying the SQL error and continuing the dialog.
 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