Callbacks: Form Methods / PML Functions

Note:
Before you read this section, make sure that you understand User-defined methods, as described in Methods on User-Defined Object Types. Most callbacks require more than a single command, so invoking a method or function (or macro) is an essential requirement.

The advantage of using form methods as callbacks is that this keeps the whole form definition in a single file. Forms defined in early versions of PML 2 used PML functions as callbacks. This is still valid and is sometimes even essential as you may need to manage a group of forms, but mostly the callbacks on a form are specific to that form.

You should note that a method or function invocation is just a valid PML expression, but such a powerful expression that it is worthy of its own section in the manual.

You have already used a form method as a callback in the revised !Hello form in the Form Concepts section:

layout form !!hello

 title 'Display Your Message'

 paragraph .Message width 15 height 1

 text .capture 'Enter message' width 15 is STRING

 button .bye 'Goodbye' OK

exit

define method .hello()

 --default constructor - set gadget default values

 !this.message.val = 'Hello world'

 !this.capture.callback = '!this.message.val = !this.capture.val'

 !this.Okcall = '!this.success()'

endmethod

define method .success()

 !this.capture.val = ''

endmethod

The .success() method above could only deliver a fixed string 'Hello again' to the message PARAGRAPH gadget. The great advantage of methods is that you can pass variables as arguments to the method, so it can be used more generally, for example as the callback to several gadgets.

define method .success( !output is GADGET, !message is STRING, !input is GADGET )

!output.val = !message

!input.val = ''

endmethod

You have added three arguments, an output gadget, an input gadget and a message string variable. This has made the method very general. You can still use it as the Okcall callback:

!this.Okcall = |!this.success( !this.message, 'Hello again', !this.capture )|

When the OK button is pressed, the Okcall action will invoke the success() method, passing to it the message paragraph gadget as !output, the message text 'Hello again' as !message and the text input field gadget capture as !input. The method will do just what it did before.

However, you could use it differently. You could add another button gadget, Restart, to the form:

button .restore 'Restart' callback |!this.success( !this.message, 'Hello world', !this.capture )|

When clicked, the Restart button's callback will execute and set the message paragraph gadget to read 'Hello world' and clear the capture text field, thus restoring the form to its state when it was displayed for the very first time.

If you invoked the success() method as the following, it would set the value 'Hello world' into the capture text input field and clear the contents of the message PARAGRAPH gadget:

!this.success( !this.capture, 'Hello world', !this.message )

Note:
The arguments to methods can be any valid PML object types, built-in or User-defined.