Quit/Close Callback

Software Customisation Guide

Forms : Form Members : Quit/Close Callback

All Forms have a QUITCALL member that the user can pass a standard callback string. This is executed whenever the user presses the Quit/Close icon (X) on the title bar of forms and the main application window.

If an open callback is used then it is called with the FORM object as its first parameter and ‘QUIT’ as its action string.

QUITCALL for MAIN Forms

For forms of type MAIN, the QUITCALL callback is executed, if present. This permits the user to terminate the application, and so the associated PML callback should prompt the user for confirmation.

If the user confirms the quit, then the callback should close down the application, and not return. If the user decides not to quit, then the callback should return an error to indicate the decision to F&M.

Use return error…noalert if the user wants to avoid displaying an error alert. If the form has no QUIT callback, then the QUIT event will be ignored.

The following example shows a (global) PML function, that the user could be use from all forms of type MAIN:

define function !!quitMain( )

-- Sharable method Quit the application

!str = !!Alert.Confirm('Are you sure you want to quit the application?')

if( !str eq 'YES' ) then

-- execute application termination command, which should not return

finish

else

return error 3 |user chose not to QUIT| noalert

endif

endfunction

This would be called from the form definition function body or from its constructor method as shown below:

Layout form !!myApplication MAIN

. . .

quitCall ‘!!quitMain( )’

. . .

exit

define method .myApplication( )

-- Constructor

!this.quitCall = ‘!!quitMain( )’

. . .

endmethod

QUITCALL for Other Forms

Essentially, if no QUIT callback is present, then the form is cancelled (hidden with reset of gadget values). If a QUIT callback is provided then the user can prevent the default Cancel action by returning a PML error, but the user must hide the form from their callback method (It is more efficient the use ‘!this.hide()’, rather than ‘hide !!myform‘ from the users form methods).

Note:

F&M does not display an alert for the returned error, it is merely for communication. The user does not need a QUIT callback if they just want to allow the form to be hidden. For DOCUMENT forms (MDI children) only, the callback must not display an alert as this will cause some gadgets to malfunction afterwards.