⎕WE Wait for Event

The ⎕WE system function takes a right argument, which is either a numeric scalar, or a character vector, or a scalar reference to a window. It can optionally also take a left argument.

If the right argument is a numeric scalar, it represents a timeout value in seconds. This timeout value represents (approximately) the maximum time that ⎕WE will wait if no events for which callbacks have been defined occur. The timer is reset when a callback runs. If the timeout value if negative, ⎕WE will never return (unless you interrupt it). If the timeout value is zero, ⎕WE will execute at most one callback and then return, so that if no callbacks are pending it will return immediately.

For example:

Sit in a loop executing callbacks. If none occur for 2.5 seconds, return:

    R ← ⎕WE 2.5

Sit in a loop executing callbacks. If none pending, wait forever:

    R ← ⎕WE ¯1

Quickly check for events; if a callback is pending, run it, else return immediately:

    R ← ⎕WE 0

If the right argument is a character vector, ⎕WE will interpret the character vector as the name of a window (an instance of one of the System Classes: Window, Form, Document or Dialog). Alternatively, the right argument can be a scalar reference to a window created using ⎕NEW. In either case, ⎕WE will not return as long as that window exists, is open, and is visible. (If the window is not open and visible when ⎕WE is called, or if the window name is invalid, it will return immediately). In the meanwhile it will execute callback functions as events occur. This means that execution of your program will wait until the window has been closed or hidden, and is thus very useful for making your program flow pause until a modal dialog has ended. You can also use this syntax of ⎕WE for your highest-level window, so that when the main window is closed control automatically returns to APL desk-calculator mode. For example, the function run by the latent expression of an APL workspace which uses user-interface objects might be something like this:

    ∇START;X;Main
[1] ⍝ Create top-level window and wait for events
[2]  Main←'⎕' ⎕NEW 'Window'      ⍝ Create the main window
[3]  CreateControls              ⍝ Create controls
[4]  X←1 ⎕WE Main                ⍝ Process events
    ∇

In this example, the function will not return until the main window has been closed.

The optional left argument to ⎕WE is a single 0 or 1. If it is 0 or omitted, ⎕WE will execute any callbacks which correspond to events which have accumulated since it was previously called. If the left argument is 1 (as in the example above), it will first flush any old events from the event queue. This is recommended for the top-level event loop, since it means that if you restart the program after an error, old stale events will not be waiting in the queue to be executed (possibly referring to objects which no longer exist).

The result of ⎕WE (if it returns at all) is usually an empty vector. However, it is possible for ⎕WE to return a result which is an event record for which no callback has been defined. This only occurs if you have explicitly set the eventmask for an object in such a way that it reports events for which there are no callbacks (this is described below). If ⎕WE does return an event record, it will be a length 9 integer vector which has the same form as ⎕EV.

Typically, therefore, your application will include a top-level event loop which (after initialisation) will call ⎕WE with an argument of ¯1 or a window name. Any callbacks invoked which might take a long time processing can call ⎕WE with an argument of 0 to ensure that events are handled promptly. Any modal dialogs you call will usually be processed by calling ⎕WE with a character right argument. Be careful, however, not to get caught in a recursive loop which will create a large )SI stack and fill your workspace.

To help in debugging, ⎕WE can be interrupted (using the Interrupt menu item, or the keyboard interrupt key Ctrl-Break or Command-Period, when the session window is active). Once you have fully debugged your application, you may wish to switch off interrupt handling using ⎕CONF so that the user does not accidentally interrupt it.