Quit/Close Callback

PML Customisation User Guide

Forms : Form Members : Quit/Close Callback

All Forms have a QUITCALL member that you can pass a standard callback string. This is executed whenever you press 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 you to terminate the application, and so the associated PML callback should prompt you for confirmation.

If you confirm the quit, then the callback should close down the application, and not return. If you decide not to quit, then the callback should return an error to indicate the decision to F&M.

Use return error…noalert if you want 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 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 you can prevent the default Cancel action by returning a PML error, but you must hide the form from their callback method (It is more efficient the use ‘!this.hide()’, rather than ‘hide !!myform‘ from your form methods).

Note:

F&M does not display an alert for the returned error, it is merely for communication. You do not need a QUIT callback if you 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.