Open Callbacks at Meta-events

PML Customisation User Guide

Form and Gadget Callbacks : PML Open Callbacks : 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 behaviours. 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:


layout form !!Open
title 'Test Open Callbacks'
list .choose callback '!this.control(' multi width 15 height 8
exit
define method .open()
do !i from 1 to 10
!fields[!i] = 'list field $!i'
enddo
this.choose.dtext = !fields
endmethod
define method .Control( !object is GADGET, !action is STRING)
if ( !action eq 'SELECT' ) then
--find out all about our gadget object
!form = !object.owner()	$*get object’s owner
!type = !object.type()	$*get object type
!name = !object.name()	$*get object name
!field = !object.PickedField	$*get picked field number
!s = !object.DTEXT[!field]	$*get DTEXT
-- do something with the data
$p selected $!form$n.$!name $!type field $!field, Dtext{$!s}
elseif (!action eq 'UNSELECT' ) then
!n = !object.PickedField	$*get picked field number
$p unselected field $!n	$*do something with data
endif
endmethod

•

Note in the constructor method open() you have initialised 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.

•

Note the use of $* or -- for in-line comments

•

Note 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 our 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, etc) and its owning form:

!type = !object.type()

!form = !object.owner()

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