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.