Implementing the close action

The close action is a predefined action dedicated to close graphical windows (for example, with the X cross button).

Purpose of the close action

In graphical applications, windows can be closed by the user, for example by pressing Alt+F4 or by clicking the X cross button in the upper-right corner of the window.

A predefined action named "close" is dedicated to this specific event.

When the end user closes a graphical window, the program gets a close action. It is then possible to execute user code in an ON ACTION close action handler, or leave the default behavior.

Note: The default action view (that is the button in the action frame) of the close action is hidden.

The close action in multiple dialogs

When executing a DIALOG instruction, the close action executes the ON ACTION close block, if defined. Otherwise, the close action is mapped to the cancel action if an ON ACTION cancel handler is defined.

If neither ON ACTION close, nor ON ACTION cancel are defined, nothing will happen if the user tries to close the window with the X cross button or an ALT+F4 keystroke.

The INT_FLAG register will not be set in the context of DIALOG.

The close action in singular dialogs

When an ON ACTION close handler is defined in an INPUT, INPUT ARRAY, CONSTRUCT, DISPLAY ARRAY or PROMPT interactive instruction, the handler code will be executed if the close action is fired.

If no explicit ON ACTION close handler is defined, the close action acts the same as the cancel predefined action. So by default when the user clicks the X cross button in a window, the interactive instruction stops and the INT_FLAG is set to 1.

If there is an explicit ON ACTION cancel block defined, INT_FLAG is set to 1 and the user code under ON ACTION cancel will be executed.

If the CANCEL=FALSE option is set, no cancel and no close action will be created, and you must write an ON ACTION close handler to proceed with the close action. In this case, the INT_FLAG register will not be set when the close action is invoked.

The close action in MENU dialogs

When an ON ACTION close handler is defined in a MENU statement, the handler code will be executed if the close action is fired.

If no explicit ON ACTION close action handler is defined, the code of the COMMAND KEY(INTERRUPT) or ON ACTION cancel will be executed, if defined.

If neither COMMAND KEY(INTERRUPT) nor ON ACTION cancel is defined:

If the MENU uses the default rendering (as buttons in current window action frame) or with the attribute STYLE="dialog", nothing happens and the program stays in the MENU instruction.
If the MENU is defined with the attribute STYLE="popup", there is no X cross button to click. However, the Escape key, or a click outside the popup menu will terminate the MENU dialog.

Regarding the INT_FLAG register, its value is unknown after a MENU instruction.

The close action on mobile devices

When displaying on Android™ and iOS mobile device, the 'close' action can be bound to the "Back button".

For more details, see The "Back" button on Android devices and The "Back" button on iOS devices.

Example

You typically implement a close action handler to open a confirmation dialog box as in the following example:

INPUT BY NAME cust_rec.*
  ...
  ON ACTION close
    IF msg_box_yn("Are you sure you want to close this window?") == "y" THEN
      EXIT INPUT
    END IF
  ...
END INPUT