Understanding code event functions

When you implement a code event, a function shell is created for your code.

The function shell defines the input and return parameters, if any. You will use these parameters when you code for the event.

BAM-generated applications use a function reference mechanism to generate event function shells where you can add your code. The code event functions you implement are registered when the application starts. When the user triggers an event, a callback instruction is invoked.

Example: Function shell

PUBLIC FUNCTION dlgEvent_Before_EmptyDialog(dlg ui.DIALOG, uiMode SMALLINT, 
    dlgCtrlInstruction libdbappEvents.DlgCtrlInstruction_Type)
    RETURNS (libdbappEvents.DlgCtrlInstruction_Type)

    DISPLAY "dlgEvent_Before_EmptyDialog (Form scope) is raised"
    
    RETURN dlgCtrlInstruction
END FUNCTION

The example function manages an empty dialog in a form code event. The most common code events are those managing dialogs. As with most code events that manage a dialog or interactive instruction, three parameters are passed into the code event function, providing details regarding the dialog, the UI mode, and the control instruction. Each of these parameters are discussed next.

Note:

Code event function parameters may vary slightly in number and type depending on the actual code event.

Dialog

The first parameter, the dlg parameter represents the current dialog. A form will have one or more sub-dialogs (INPUT, INPUT ARRAY, DISPLAY ARRAY, MENU, or CONSTRUCT). The current dialog will reference one of the sub-dialogs.

UI Mode

The second parameter, uiMode represents the state in relation to user action in the dialog when the event was triggered. Various modes exist as shown in UI Modes. They are defined as constants in the libdbappFormUI file in the libdbapp library.

Table 1. UI modes
Description	Applies to ...	Constant	Value
Display	`DISPLAY ARRAY`	C_MODE_DISPLAY	1
Modify	`INPUT \ INPUT ARRAY`	C_MODE_MODIFY	2
Add	`INPUT \ INPUT ARRAY`	C_MODE_ADD	3
Search	`CONSTRUCT`	C_MODE_SEARCH	4
Empty	`MENU`	C_MODE_EMPTY	5
Exit form	The form	C_MODE_EXIT_FORM	6
Exit app	The app	C_MODE_EXIT_APP	7
Undefined	All (array, form, or app)	C_MODE_UNDEFINED	0

You may need to inspect the uiMode when writing a code event. For example, if you have code that you only want to execute when the dialog is in CONSTRUCT (search) mode, you would create a conditional statement that checked for C_MODE_SEARCH before running that code block.

Or if the mode was in C_MODE_MODIFY, for example, the dialog (INPUT ARRAY) then allows a user to modify data, you could code to deactivate actions the user is allowed or not allowed to execute, and to give the focus to a specific field.

Dialog control instruction

The third parameter, dlgCtrlInstruction is a libdbappEvents.DlgCtrlInstruction_Type, which is a parameter containing the current dialog instruction value.

This parameter represents the instruction that triggered the event, which can be one of those described in the table. They are defined as constants in the libdbappEvents file in the libdbapp library.

This parameter is associated with the return value of the function.

Tip:

If your code does not change the control instruction value, by default the dialog instruction is correctly set by the caller and in most cases, it is not necessary to change this value.

Table 2. Dialog control instructions
Description	Constant	Value
Accept dialog	`ACCEPT_DIALOG`	1
Continue dialog	`CONTINUE_DIALOG`	2
Exit dialog	`EXIT_DIALOG`	3
Continue menu	`CONTINUE_MENU`	4
Exit menu	`EXIT_MENU`	5
Cancel insert	`CANCEL_INSERT`	6

As an example, a BAM-generated application may need to check user permissions before performing an action. You code to determine whether the user has permission. If the user does not have the necessary permissions, your code should set the return dlgCtrlInstruction parameter to EXIT_DIALOG, otherwise the instruction is accepted.

The control instruction can be set to CONTINUE_DIALOG, if the data entered in a field is incorrect. A validation rule check is a common use of code events. A CALL dlg.nextField("field_01") instruction returns the user to the field to enter the correct value, while you may also code to display a message to the user about the required value.

Returning invalid values

Returning an invalid control instruction value is ignored with just a display of the error in the output. However, you can turn this into a runtime-like error by setting the "fglrun.mapAnyErrorToError=TRUE" entry in your FGLPROFILE file. This will cause a dialog to be displayed with a message before stopping the program. For more information, see the Default exception handling page in the Genero Business Development Language User Guide.

Dialog control instructions options will vary depending on the actual code event. For example, in an "After Display" event, it makes no sense to return EXIT_MENU because you are in a DISPLAY ARRAY and not a MENU. Refer to the functions in the following sections for more details of the dialog instructions available for different code events.