3.7 Events and Event Handlers

Events occur in a variety of situations, such as user keystrokes, mouse button clicks, changes in display content, and changes in state. The event that occurred is passed to the corresponding event handler via the event queue. In the event handler, the behavior according to the content of the event such as changing the property of the object and executing the method can be defined in the user application.

The event handler is defined as a Function named “On” + event name . The CRS execution engine looks for a Function defined with such a name in the event propagation destination and propagates the event.

Example) Event handler that receives Touch events

Function OnTouch (e) {
    Title = "Hello!";
}

For example, when the keyboard focus is lost due to text input, write as follows to make the background red if there is no input.

Function OnLostFocus(e) {
    if (e.From instanceOf TextBox) {
        if (e.From.Value == "") {
            e.From.BgColor = $RED;
        } else {
            e.From.BgColor = $STD;
        }
    }
}

The event propagates upwards in the object tree with “//” ( Root object) as the vertex until it is caught by the event handler .

It disappears when it is caught by an event handler in the process of propagation or finally reaches the Root object.

By calling the PostEvent method in the event handler with no arguments, the event caught by the event handler can be returned to the event propagation flow again.

Event processing timing

Events always go through the event queue. Event storage in the event queue and event handler execution are asynchronous.

In other words, the timing when an event occurs and the timing when an event handler is executed do not exactly match, and vary depending on the state of the computer at the time of execution. For example, when three consecutive events occur, the execution timing of the event handler varies as follows depending on the computer status.

Case 1
The event handler is fired after the first event is queued .

Case 2
The event handler is fired after the second event is queued .

Case 3
The event handler is fired after all events have been queued for the event.

Events usually occur when something changes (for example, when you change the selected position of a list box). A continuous event means that the state is continuously changing. If you refer to the state that caused the event in the script in a continuous event as in the above case, the referenced result may differ depending on when the event handler is executed.

For example, in the case of changing the selected position of a list box, in case 1 , when you refer to the Value property that indicates the selected position of the list box, the value set by the first event is referenced . In case 3 , the selection position set in the third event is referenced . In the end, in every case, as many event handlers as there are events will be fired, but be especially careful that the current value of the object property may not always match the state when the event was triggered.

If you need to determine the more detailed situation when an event occurs, see the Event object passed to the event handler. For example, in the list box example above, the From property of the event object contains a reference to the ListItem object that was selected when the event was fired.

/ * This is a wrong example. Refers to the selected position when the event handler is executed, not when the event occurs * /

Function OnTouch (e) {
    print (" Selected position ", ListBox1.Value, " is \ n");
}

/ * This is a correct example. Refers to the selected position when an event occurs * /

Function OnTouch (e) {
    print (" Selected position ", e.From.Index, " \ n") ;
}

Depending on the type of event and the type of object that triggered the event, various incidental information is attached to the event object and passed to the event handler. In order to suppress the influence of execution timing as explained here in the execution of the event handler, be sure to refer to the additional information of the event object for processing.

Event order

Events are queued in the event queue in the same order as the action that caused the event. Also, the events stored in the event queue are retrieved in the same order and passed to the event handler. This order is always constant.

However, there is no guarantee that the actions that raise the event will always be in the same order. For example, the assumption that the LostFocus event is followed by another object’s GetFocus event is incorrect. Also, the process that assumes a specific order of occurrence is incorrect because it depends on the situation whether the event generated by the screen operation or the event issued by the CRS script comes first.

For example, the events that can occur when you click the Button object with the mouse are the GetFocus and Touch events. However, GetFocus does not occur when the Button has focus from the beginning. Also, when a user-defined event is issued in the OnGetFocus event handler, it is undefined whether the Touch event or the user-defined event is stored in the event queue first. This is because it is not possible to determine which is done first, the operation of releasing the mouse button, which causes the Touch event, or the process of executing the PostEvent method in the execution of the CRS script .

Event handlers should be considered to behave correctly no matter what order the events occur. If you need to depend on the order in which the events occur, verify that the factors that issue the events always occur in the same order. However, not all classes built into Biz / Browser guarantee the order of occurrence of multiple events, so only user-defined events issued by CRS scripts may be guaranteed the order of occurrence.