Events

This is a comprehensive guide to SIMPOL events, I will outline the various event types, what’s required to use them in your programs and give a few examples of when these may come in handy.

Some of these events come up multiple times in varying libraries the grouping here is arbritary, simply search for the event name

  1. What are events in SIMPOL?
    a. Event Handling 101
    b. Eventhandler functions
  2. General Events
    a. OnClick
    b. OnChange
    c. OnGotFocus
    d. OnLostFocus
    e. OnMouse
    f. OnDoubleClick
    g. OnFill
    h. OnScroll
    i. OnSelect
    k. OnSelectionChange
    j. OnSize
  3. Glrid Specific Events
    a. OnCellChange
    b. OnCellLeftClick
    c. OnCellLeftDblClick
    d. OnCellRightClick
    e. OnCellRightDblClick
    f. OnCellSelect
    g. OnColWidthChange
    h. OnLabelClick
    i. OnLabelLeftDblClick
    j. OnLabelRightClick
    k. OnLabelRightDblClick
    l. OnRowHeightChange
  4. Datagrid Events
    a. OnRecordDelete
    b. OnRecordNew
    c. OnRecordSave
  5. Form Events
    a. OnChangeRecord
    b. OnDelete
    c. OnDiscard
    d. OnKey
    e. OnKeyLostFocus
    f. OnNewRecord
    g. OnSave
  6. Record Events
    a. OnDeleteRecord
    b. OnSaveRecord

What are events in SIMPOL

Before diving in depth on SIMPOL’s event handling it may be useful to know what an event is, according to the ever trustworthy Wikipedia:

an event is an action or occurrence recognized by software, often originating asynchronously from the external environment, that may be handled by the software…

Event (computing) – Wikipedia 2019 (link)

Events are used throughout SIMPOL programs to provide functionality based on a user’s input, whether that be a mouse click, switching records, or closing the entire program. You may have already come across events before in previous tutorials, for for example in our Advanced I/O Tutorial we added several button onclick functions

SIMPOL has a lot of events that can be handled, and each control uses a unique subset of them. The exact events that any control has are all listed in that controls respective Properties table in the Language Reference Manual.

Event Handling 101

To use an events we have to declare an event handling function to which that input is passed: if you’re using a form created in Superbase NG Personal this is done in the events panel of any controls properties (see below)

Alternatively if you are creating the form in the IDE all you have to do is set that controls event function to the function you wish to handle the request. This sounds complicated but for the above example the following code is required

formcontrolvariable.onclick.function =@ okbtn_oc

Alternatively using the member operator (!) we can from the form select the button and assign the function that way:

formvariable!bOK.onclick.function =@ okbtn_oc

NOTE: This is also how you would assign a reference to the object (typically this will be an appwindow object or a form object)

Once this is done all you have to do is declare the event handler function you have named, that’s what the next section is for

Handling Functions

The main purpose of this page is to show you exactly which variables are needed when declaring an eventhandler, this list of variables can vary from the standard control variable plus the optional reference to upwards of 4 or 5 additional variables for some

Declaring event handling functions is the same as declaring any other function: function keyword, a list variables in brackets, the main code and then end function. Just make sure that the function name and control type match up with the control declaration


General

These are all purposes general events that are utilised in a wide range of controls. For all events the reference is only passed if it has been provided. (You do however have to declare it every time)

OnClick

An event triggered when the user clicks a dialogstdbutton, bitmapbutton, button, or tool. And the relevant dataform1 equivalents for button and bitmapbutton

The event handling function will require the following parameters:

type(wxformcontrol) me[, type(*) reference]

OnChange

This event is called by the checkbox, edittext, and option controls

The event handling function will require the following parameters:

type(wxformcontrol) me[, type(*) reference]

OnGotFocus

This event is called by the bitmapbutton, button, checkbox, combo, datagrid, edittext, grid, list, option, scrollbar controls

The event handling function will require the following parameters:

type(wxformcontrol) me[, type(*) reference])

OnLostFocus

This event is called by the bitmapbutton, button, checkbox, combo, edittext, both grids, list, option, scrollbar controls

The event handling function will require the following parameters:

type(wxformcontrol) me[, type(*) reference])

OnMouse

This event is called by all wxcontrols, the event handling function for an onmouse event will require the following parameters:

type(wxformcontrol) me, integer etype, integer keys, integer x, integer y, type(*) reference

The reference is only passed if it is provided by the user, this will normally be the window or form that the control is in

etype is the bit (defined by onmousemask) showing what sort of event it is. There’s a whole seperate page explaining mousemasks here)

keys is a collection of bits showing key positions

Key TypeBit Value
shift down0x00010000
ctrl down0x00020000
alt down0x00040000
meta down0x00080000

OnDoubleClick

An event that is triggered when a list control receives a double-click. The event handling function requires the following parameters:

wxformlist me[, type(*) reference]

Applies to both dataform1list and wxformlist

OnFill

list

OnScroll

An event that is triggered every time the scroll position changes. The event handling function requires the following parameters:

wxformscrollbar me, string scrolltype[, type(*) reference]

This applies to both wxformscrollbar and dataform1scrollbar. The scrolltype variable can be one of the following:

  • "top"
  • "bottom"
  • "thumbdrop"
  • "thumbdrag"
  • "pageup"
  • "pagedown"
  • "lineup"
  • "linedown"

OnSelect

This is a widely used event, not only used in the traditional GUI library but also in other such as the filtergui, printform1, and mrulib. It is however also used by wxmenuitem and dataform1

type(wxformcontrol) me[, type(*) reference]

OnSelectionChange

An event that is triggered when the selection is changed. This event is found in both wxformcombo and wxformlist (and there dataform1 equivalents). The event handling function will require the following parameters:

wxformcombo me[, type(*) reference]

OnSize

This event is triggered by wxformsizebox and wxwindow whenever the user changes the size of either. The event handling functions requires the following parameters:

type(wxformcontrol) me[, type(*) reference]

OnStateChange

This event is triggered when the user changes the state of a wxwindow, for example by minimzing or maximising the window

wxwindow me[, type (*) reference]

OnVisibilityChange

An event triggered when the user changes the visibility of a wxdialog or a wxwindow by, for example ‘closing’ the window or dialog

type(wxformcontrol) me[, type(*) reference]

Grid Events

These are all grid specific, these will apply to both wxformgrid and dataform1datagrid unless otherwise specified

oncellchange

Triggered when the user changes the content of a cell. The event handling function requires the following parameters:

wxformgrid me, integer row, integer col[, type(*) reference])

The reference is only passed if it has been provided

oncellleftclick

Triggered when the user left clicks on a cell. The event handling function requires the following parameters:

wxformgrid me, integer row, integer col[, type(*) reference]

The reference is only passed if it has been provided

oncellleftdblclick

Triggered when the user double left clicks on a cell. The event handling function requires the following parameters:

wxformgrid me, integer row, integer col[, type(*) reference])

The reference is only passed if it has been provided

oncellrightclick

Triggered when the user right clicks on a cell. The event handling function requires the following parameters:

wxformgrid me, integer row, integer col[, type(*) reference])

The reference is only passed if it has been provided

oncellrightdblclick

Triggered when the user double right clicks on a cell. The event handling function requires the following parameters:

wxformgrid me, integer row, integer col[, type(*) reference])

The reference is only passed if it has been provided

oncellselect

This event is triggered when the user selects a cell. The event handling function requires the following parameters:

wxformgrid me, integer row, integer col[, type(*) reference])

The reference is only passed if it has been provided

oncolwidthchange

This event is triggered when the user resizes a column. The event handling function requires the following parameters:

wxformgrid me, integer col[, type(*) reference])

The reference is only passed if it has been provided

ongotfocus

See above

onlabelclick

This event is triggered when the user clicks on a row or column label or the corner field. The event handling function requires the following parameters:

wxformgrid me, integer row, integer col[, type(*) reference])

The reference is only passed if it has been provided.

If row is equal to -1 and col is equal to -1 the user clicked the corner label, otherwise if row is equal to -1, they clicked on the column label. If col is equal to -1 they clicked a row label

onlabelleftdblclick

This event is triggered when the user double left clicks on a label. The event handling function requires the following parameters:

wxformgrid me, integer row, integer col[, type(*) reference])

The reference is only passed if it has been provided. The same rules for row and col count apply here as for onlabelclick

onlabelrightclick

This event is triggered when the user right clicks on a label. The event handling function requires the following parameters:

wxformgrid me, integer row, integer col[, type(*) reference])

The reference is only passed if it has been provided. The same rules for row and col count apply here as for onlabelclick

onlabelrightdblclick

This event is triggered when the user double right clicks on a label. The event handling function requires the following parameters:

wxformgrid me, integer row, integer col[, type(*) reference])

The reference is only passed if it has been provided. The same rules for row and col count apply here as for onlabelclick

onlostfocus

See above

onrowheightchange

This event is triggered when the user resizes a row. The event handling function requires the following parameters:

wxformgrid me, integer row[, type(*) reference])

The reference is only passed if it has been provided.

Dataform1datagrid specific events

The following events are all specific to the dataform1datagrid.

onrecorddelete

This event is triggered when a record gets deleted, I believe this is the same as ondeleterecord and the event handling function will require the following paramters:

type(wxformcontrol) me [, type(*) reference])

onrecordnew

This event is triggered when a new record is created, the event handling function requires the following parameters

type(wxformcontrol) me [, type(*) reference])

onrecordsave

This event will be triggered when a record is saved, I believe this is the same as onsaverecord and the event handling function will require the following parameters:

type(wxformcontrol) me [, type(*) reference])

Form Specific Events

All of these are dataform1 exclusive events as wxform uses only the OnMouse event

OnChangeRecord

This is an event that is called whenever you attempt to change a record, most notably it is called by both the modifyrecord() and newrecord() functions when a form is being explicitly locked. The parameters the event handling function requires are:

dataform1 me[, type (*) reference] 

OnDelete

This event is called not only by dataform1 but it can also be found in recordview and tableview.This event is called whenever you delete a record. The event handling function will take the following parameters:

dataform1 me[, type (*) reference]

OnDiscard

This is an event called when you discard a record in the form (make a new record but never save it). The event handling function will take the following parameters:

dataform1 me[, type (*) reference]

OnKey

This is an event that is rather special as unlike every other event this one is set using functions rather than by reference (a more detailed explanation can be found here)

OnKeyLostFocus

See above

OnNewRecord

This event is also sdhiahfaiugnlznflak is the event called if you create a new record on a form. The event handling function will take the following parameters

dataform1 me[, type (*) reference]

OnSave

This event is called not only by dataform1 but it can also be found in printform1, recordview, and tableview. This event is called whenever you save a record on the form. The event handling function will take the following parameters:

dataform1 me[, type(*) reference]

Record Events

OnDeleteRecord

This event is used by dataform1table, dataform1record and appwindow. It is functionally the same as onrecorddelete() and ondelete() so it is called when you delete a record. The parameters the event handler requires are:

dataform1 me[, type (*) reference]

OnSaveRecord

This event is also used by both dataform1record and dataform1table. This event is functionally the same as onrecordsave() and onsave() and is called when you save a record. The parameters the event handler requires are:

dataform1 me[, type (*) reference]