Object Events

This section describes some of the more commonly used events. The complete set of events can be found in the appendixes containing Object Events. Note that events are just properties of objects in the same way as, for example, the font is.

Button Events

On Click

This event is triggered when the button is clicked. The single argument is the button.

def eventFunc (button) :
    name = button.getName()
    RekallMain.messageBox ("You've clicked the '" + name + "' button!")
          

Item Events

On Set

This event is triggered when the value of the data control is set from the server database. The arguments are the control, the query row for which the control displays data, and the new value.

def eventFunc (ctrl, qrow, value) :
    if int(value) > 1000 :
        RekallMain.messageBox ("That's a very silly value!")
        ctrl.setValue (qrow, "0")
          

On Change

This event is triggered when the value of the data control is changed by the user. The arguments are the control, the query row for which the control displays data, and the new value.

def eventFunc (ctrl, qrow, value) :
    if int(value) > 0 :
        RekallMain.messageBox ("Don't set that checkbox!!")
        ctrl.setValue (qrow, "0")
          

There are two special cases. Firstly, this event is not available on fields, and secondly, on pixmaps, the value passed to the event function is undefined. If you need to process values from field controls, the field On Leave event, and the block Pre-Insert and Pre-Update events will probably suffice.

On Enter

This event is triggered when focus enters a control. The arguments are the control itself and the current query row number.

def eventFunc (ctrl, qrow) :
    if ctrl.getValue (qrow) == "" :
        ctrl.setValue (qrow, "42.00")
          

On Leave

This event is triggered when focus leaves a control. The arguments are the control itself and the current query row number. If the function returns a false result then focus remains in the control.

def eventFunc (ctrl, qrow) :
    if (ctrl.getValue(qrow) == None) or (ctrl.getValue(qrow) == "") :
        phone = RekallMain.promptBox \
                (   "Telephone",
                    "",
                    "Really no phone?")
        if phone != "" :
           ctrl.setValue (qrow, phone)
    return 1
          

Block Events

On Action

This event is called immediately before an action such as Next Record is called, the two arguments being the block and the action. If the event function returns false then the action is aborted. Action codes are defined in the RekallMain module; note that these values are also used as arguments to the block doAction method. The complete set is listed below.

Code Value Meaning
actNull 0 No action
actFirst 1 Go to first record
actPrevious 2 Go to previous record
actNext 3 Go to next record
actLast 4 Go to last record
actAdd 5 Add a new record
actSave 6 Save record
actDelete 7 Delete record
actQuery 8 Start a query (search)
actExecute 9 Execute a query (search)
actCancel 10 Cancel query
actInsert 11 Insert a new record
actReset 14 Reset changes to row
actGotoQRow 15 Go to row by query number
actSyncAll 16 Save all updated rows

On UnCurrent

The On UnCurrent event is invoked when focus leaves a row in a block (ie., the focus moves to a control in a different row or in a different block); the arguments are the block and the query row number of the row being left.

Note that this event is not invoked when a row is deleted.

On Current

The On Current event is invoked when focus arrives in a row in the block (ie., the focus moves to a control in a different new row or block); the arguments are the block and the query row number of the row being entered.

The example below is taken from the Client form in the RekallDemo database. This has a combobox which can be used to navigate between records; the code here updates the combobox whenever the current record changes.

def eventFunc (block, qrow) :
    Orders.onBlockCurrent (block, qrow)
    selector = block.getNamedCtrl ("selector")
    if qrow >= block.getNumRows() :
           selector.setCurrentItem (qrow, 0)
    else : selector.setCurrentItem (qrow, qrow + 1)
          

On Display

The event is invoked whan a row is displayed, and is called with the block and the query row number as arguments. An example of using this event was shown earlier.

Pre Insert

This event is invoked immediately before a row which has been inserted into a form is actually committed to the server database; the arguments are the block and the query row number of the row. If the event function returns false then the insert is aborted (but the row remains inserted in the form).

def eventFunc (block, qrow) :
    Orders.ordersPreCommit (block, qrow, RekallMain.actInsert)
    return 1
          

Note that the Pre Insert event is different to the On Action event when called with the actInsert action. The latter is when the user opens up a new row (by right-clicking in a rowmark and selecting Insert); at this stage Rekall simply makes space for a new row of data to be entered.

Pre Update

This event is invoked immediately before a row which has been changed in a form is actually committed to the server database; the arguments are the block and the query row number of the row. If the event function returns false then the update is aborted (but the row remains changed in the form).

def eventFunc (block, qrow) :
    Orders.ordersPreCommit (block, qrow, RekallMain.actSave)
    return 1
          

Pre Delete

This event is invoked immediately before a row which has been marked as deleted in a form is actually deleted from the server database; the arguments are the block and the query row number of the row. If the event function returns false then the update is aborted (but the row remains marked as deleted in the form).

Note that if the block autosync option is set, then a row will be deleted immediately after it is marked for deletion.

def eventFunc (block, qrow) :
    if not RekallMain.queryBox ("Are you sure?") :
        return 0
    Orders.ordersPreCommit (block, qrow, RekallMain.actDelete)
    return 1
          

Post Query

The Post Query event is triggered immediately after an SQL select query has been executed but before the data is displayed. The single argument is the block; any value returned is ignored.

The example below updates a combobox control to have on entry for each record retrieved from the server database See the Client form in the RekallDemo database.

def eventFunc (block) :
    selector = block.getNamedCtrl("selector")
    list = []
    for rowno in (range(block.getNumRows())) :
        list.append (block.getRowValue("Company", rowno))
    selector.setValues (list)
          

Post Sync

This event is invoked immediately after the data displayed in a form has been synchronized with the server database (ie., after an SQL insert, update, or delete). The arguments are the block, the current query row number, the synchronisation operation just performed, and the primary key value for the row which was operated on. Values for the operation are defined in the RekallMain module, and are listed above under the On Action event.

The example below is just the same as the Port Query example above, and keeps the combobox up to date when records are added, deleted or altered.

def eventFunc (block, qrow, act, value) :
    selector = block.getNamedCtrl("selector")
    list = []
    for rowno in (range(block.getNumRows())) :
        list.append (block.getRowValue("Company", rowno))
    selector.setValues (list)
          

Form Events

On Load

This event is executed when a form is loaded for execution. At the point of execution, the form is ready for display, but no server database queries have been issued. The single argument is the form,

def eventFunc (form) :
    RekallMain.messageBox ("Hello and Welcome") ;
          

On UnLoad

This event is executed immediately before a form closes. The single argument is the form.

def eventFunc (form) :
    RekallMain.messageBox ("Toodle-pip, old chap!") ;
          

On Close

This event is executed if a form is about to be closed. If there is an event function and the function returns zero then the form is not closed. Beware: if this routine always returns zero then the form cannot be closed except by switching to design view ( And even this is not possible in the runtime version of Rekall, since all design functionality is removed. You have been warned! )

def eventFunc (form) :
    return RekallMain.queryBox ("Really close?") ;