Events and Callbacks

Concepts

Windowing systems such as MacOS and Windows are event-driven, which means that your program has to be able to respond to events such as a key stroke or new data being available. An event (sometimes called a message) can arise from a number of sources. It can be directly triggered by a user action - for example, Mouse Down or Key Down. It might be indirectly triggered by a user action - for example, if the uses presses the mouse button over a button in a dialog, a Mouse Down event occurs, and this in turn causes a Clicked event for the button. Events can also be triggered by the system software - for example, to indicate that a window needs to be redrawn - or by another program or even your own program.

Much event handling is automatic, and you do not normally need to deal with it. For example, redrawing of windows is usually handled automatically by APL. For events which you do need to know about, such as a Click event in a button, you define an APL callback, which is an APL expression (usually a function) which will be run if the event occurs. You assign a character vector containing the expression or function name to the appropriate callback property of the object. This is a special property (whose name begins with 'on..') which creates the association between the event and your callback function or expression.

For example, this code creates a dialog with an OK button, and associates the APL function ENDDIALOG with the Click event for the button:

      DEMO←'⎕' ⎕NEW 'Dialog'
      DEMO.title←'Button Example'
      DEMO.OK.New 'Button'
      DEMO.OK.onClick←'ENDDIALOG'

The APL callback function is actually run during execution of the system function ⎕WE (wait for event).

How APLX handles events

When an event occurs, APLX looks to see if the event refers to a user-defined window, or to one of APL's own windows (such as a session or edit window). In the latter case, the event is handled internally and you do not normally need to be aware of it. If the window was user-defined, however, then your APL application might need to be informed of the event. For every event, there is a default system action (which may be to do nothing), and there might in addition be an APL callback function which you have defined for that event. Often, the default system action is to create another, higher-level event. At the lowest level, events take place in windows, but where appropriate are passed to a control (such as an Edit text or Check box) to produce a higher-level event.

When events are handled

APLX calls the operating system for the latest event at two main points in the code. These are:

(a) When APL is requesting input

(b) During execution, the APL interpreter many times a second to see if any events need to be handled.

The system handler for an event is invoked immediately the event is retrieved from the operating system. This means that events continue to be processed even if your application is busy (doing a long calculation, for example), which helps APLX applications appear responsive to window updates and user actions. In contrast, your APL callback functions are executed only when you call ⎕WE.

Where you have defined an APL callback for an event, the event is placed in a queue, and callbacks in the queue are run in turn when your program next calls ⎕WE. You can either call ⎕WE in an 'event loop' (with a long or infinite timeout value), in which case all processing takes place by ⎕WE looping internally and executing your callback functions as events happen, or you can call ⎕WE with a small or zero timeout value, in which case it will return almost immediately and you can continue with other APL processing. Where your program needs to carry out processing which will take a long time, it should call ⎕WE from time to time (preferably at least two or three times a second), bearing in mind that when it does so events may cause other callbacks to be invoked.

Note that, when APL is in desk-calculator mode (for example, if an untrapped APL error occurs in your program), your APL callback functions will not be run. When you next call ⎕WE, there may be quite a few callbacks queued up. You can flush these from the event queue by passing a left argument of 1 to ⎕WE.

Information about events

When your APL callback function runs, you can find out information about the event using the niladic system function ⎕EV. This returns the system clock, keyboard state and mouse position at the time of the event, a number which identifies the event type, and sometimes extra information associated with a particular type of event.