Callbacks are the mechanism by which the calling script can be notified of actions performed by the user of the window. They are ordinary Lua functions.

The callback functions are given a single parameter of the control/window table receiving an event. The event ID is lodged in control.event and identifies what has caused the callback to be made and the control/window table identifies the control it applies to, or the window if it's a non-control specific event.

If a callback is not declared for a control, the callback in its parent is called, if that is not declared, the parents parent is called, this process is repeated until the window callback is reached, if that is not present, no callback is called.

The callbacks return an exit code, the codes are the same as the page() function, anything other than drWizardContinue causes the page() function to terminate with the exit code returned by the callback.

If no exit code is returned, drWizardContinue is assumed.

The callbacks are called using a protected call (see pcall in the Lua manual), so errors are caught by the page() function, allowing it to gracefully shut-down the window before propagating the error upwards.

The column fill callback returns its result (of an appropriate LType) as well as an exit code. E.g.: return result,exitcode (or just return result and an implied drWizardContinue). If no result is returned, a NIL value is used.

The event ID is one of:

drPage_WindowOpened

-

the window is open and has been shown

drPage_AllowWindowClose

-

the user has asked that the window be closed, callbacks should return drWizardContinue to allow it or anything else to dis-allow it (except drWizardError)

drPage_WindowClosing

-

the window is about to be closed

drPage_WindowTimer

-

the window timer time has elapsed

drPage_TabSelected

-

a new tab has been selected

drPage_ListSelected

-

a new list row or column has been selected

drPage_Changed

-

on a prompt: the value has been changed from its previous value

otherwise: the control's touched status has been changed

drPage_Pressed

-

a button has been clicked or a list row/column was double clicked

drPage_Popup

-

a button or a list row/column was right-clicked

drPage_FillColumn

-

notification that a calculated list column value is required

drPage_LoadFixedKey

-

notification that the fixed key elements in a list should be set

drPage_FilterRecord

-

notification that a record is about to be added to a list, return drWizardSkip to reject the record from the list

drPage_NoRecordsFound

-

notification that nothing passes the list filter

drPage_RecordsFound

-

notification that at least one record passes the list filter

drPage_AddSelection

-

notification that a multi-select list is about to add a selection to the selected list, callbacks should return drWizardContinue to allow it or anything else to dis-allow it (except drWizardError)

drPage_RemoveSelection

-

notification that a multi-select list is about to remove a selection from the selected list, callbacks should return drWizardContinue to allow it or anything else to dis-allow it (except drWizardError)

drPage_EmptySelections

-

notification that a multi-select list is about to clear all selections from the selected list, callbacks should return drWizardContinue to allow it or anything else to dis-allow it (except drWizardError)

The callback functions may manipulate the following properties of the window and its controls (via the prop() function, see later):

Properties (read/write):

window.title

window.hint

window.timer

window.showtabs

control.value

-

the current value of a prompt, when writing, the type of the new value must be the same as the original; also when writing, changing the value will trigger the drPage_Changed event on that control

control.hint

control.name

-

only valid on a tab and list control

control.text

control.hide

control.readonly

-

on drPage_Prompt controls this sets readonly, on other types it disables them

control.paged

-

only valid on a list control

control.touched(bool)

-

reading returns the touched status of the control, for a prompt this is true if the current value is different to its initial value, for other control types it just echoes the last write to the property

writing to touched will trigger the drPage_Changed event if the touched status changes as a result of that write

NB: writing to touched is not valid on a prompt control

key.key

-

only valid on a key of a list control, when writing, changes the key being browsed to that given

key.fixed

-

only valid on a key of a list control, when writing, changes the fixed field of the key

key.text

-

only valid on a key of a list control, when writing, changes the text on the key tab (if one is being shown)

Note: In the above, the prefix (window. control. and key.) is purely descriptive. The actual property name used in the prop() function should not include this prefix.

The following properties are also maintained and can be read from the callbacks:

Properties (read only):

window.type(int)

=

type of the control, on the window this will be drPage_Window

window.event(int)

=

the current event ID (see above)

window.control(table)

=

the control triggering the event, or nil if not a control event or it's a pre-defined control (e.g the close and 'vcr' buttons)

window.touched(int)

=

the number of prompts that have been ‘touched’ in the window

window.context(str)

=

the callback source context of the current event, this will be one of:

'callback'

the callback is coming from a control in the controls space or the window

'save'

the callback is coming from the VCR save button

'close'

the callback is coming from the VCR close button

'back'

the callback is coming from the VCR back button

'next'

the callback is coming from the VCR next button

'new'

the callback is coming from the VCR new button

'reset'

the callback is coming from the VCR reset button

'del'

the callback is coming from the VCR del button

control.orig(LType)

=

the original (un-touched) value of a prompt

control.old(LType)

=

the previous (before last change) value of a prompt

control.parent(table)

=

the control this one is contained within (listbutton-->list-->tab-->window-->nil, etc.)

control.window(table)

=

the overall window table (useful to get at global properties)

control.row(int)

=

during a FillColumn or ListSelected or Pressed or Popup event, the list row number active, the file buffer will be loaded during the callback, or empty as appropriate

control.column(int)

=

during a FillColumn event, the list column number being filled

during a ListSelected or Pressed or Popup event, the list column number selected

NB: The column number here is the ordinal position within the list table, which may be different to the visual order if the user has moved the columns about.

control.selected(RecNoQ)

=

the selection list actually being used (either auto created or given in the list control definition) when multi-select is enabled on a list

control.key(table)

=

the list key currently active

control.id(str)

=

the id of the control (useful in prop())

control.event(int)

=

the current event ID (see above)

The following properties are write-only:

Properties (write only):

window.reset(bool)

=

set true to reset all prompts to their initial value (or whatever value their source now contains) and clear all touched statii for all controls

NB: this does NOT trigger control changed events

control.reset(bool)

=

if on a prompt, set true to reset to its initial value (or whatever value its source now contains); on all control types, set true to clear the touched status

NB: this does NOT trigger a control changed event

control.select(bool)

=

set true to change the input focus to this control or:

if a button, press it
if a tab, show it
if a key, make its key active

control.refresh(bool)

=

set true to force a list to refresh