Open Callbacks at Meta-events

There are a very large number of possible events, and most of them are very low level and have to be serviced very quickly to produce a usable GUI. It would be inappropriate to allow the (interpreted) PML AppWare access to them all.

However, the application software defines a set of meta-events for forms and gadgets. When a meta-event occurs, the application software checks for user-defined callbacks and executes them. Hence callbacks are the AppWare’s way of providing actions to be carried out at these meta-events.

Callbacks provide a simple yet versatile mechanism for the AppWare to create and manage the GUI. Sometimes there is more than one meta-event associated with a gadget. In this case, the simple assigned callback is insufficient to fully exploit the gadget's possible behaviors. To overcome this shortcoming you can use open callbacks to allow the AppWare to be informed whenever a meta-event is encountered.

Open callbacks can be used wherever callbacks can be used. They always involve methods or PML Functions with a fixed argument list as follows:

define method .Control( !object is FormsAndMenusObject, !action is STRING)

• !object is a Forms and Menus object, for example, a form, gadget or menu.

• !action is the meta-event that occurred on the object and represents the action to be carried out by the method.

The open callback is a string of the form:

'!this.MethodName('

Note:
The open bracket '(', no arguments and no closing bracket. The callback is to an open method or function.

You might assign an open callback to a multi-choice list gadget as follows:

Notes:
That in the constructor method open(), you have initialized the list so that field n will display list field n. DTEXT is a shorthand for display-text, that is the text displayed in the list field.

Control is the method which manages interaction with the list. Note the open callback defined in list choose.

The use of $* or -- for in-line comments.

The use of the printing command $p to print information to the system Request channel. $!form replaces the variable !form with its current value as a string - this only works for PML simple in-built scalars types REAL, STRING, BOOLEAN. $n in $!form$n.$!name is a separator needed to separate $!form from the following '.' which would otherwise be thought of as part of the variable name.

When a list field is clicked, the list's callback will be examined and if it is an open method or function, then the Forms and Menus software will supply the arguments required to complete the function.

Thus in this case the actual callback string executed will be:

|!this.control( !!Open.choose, 'SELECT' )|

Inside the control() method you branch on the value of !action and access the data of !object (in this case, our list). Finally you perform the application's resultant action - in this case, just printing out all you know about the operator interaction using the $p command, which for a selection of an un-highlighted list field will write:

Selected OPEN.CHOOSE LIST field 5, Dtext{list field 5}

Notice that the same method could be used to manage several or even all gadgets on our form since the variable !object is a reference to a gadget object and is supplied as !!Open.choose, the full name of the gadget including its form. This allows us to find everything about that object from its in-built methods, including its gadget type (LIST, TOGGLE, and so on) and its owning form:

!type = !object.type()

!form = !object.owner()

All the built-in members and methods of forms and gadget types are listed in the Software Customization Reference Manual.