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.

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

setup 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

We have added three arguments, an output gadget, an input gadget and a message string variable. This has made the method very general. We 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, we could use it differently. We 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 we invoked the success() method as:

!this.success( !this.capture, ‘Hello world’, !this.message )

it would set the value ‘Hello world’ into the capture text input field and clear the contents of the message PARAGRAPH gadget. Not what you need here perhaps, but you can see how versatile methods can be!

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