The niladic system function ŒEVA is a synonym for ŒWARG. It is valid only inside a ŒWE callback function, run by APLX as the result of an event occurring in one of your windows or other objects. It is used to pass data associated with the event from an external control or server, or another APL task. This data comprises the arguments passed when the event was created in the external or system object.
The exact content of ŒEVA depends on the source of the event.
When you create Child tasks using the APL object under ŒWI, the Child and Parent tasks can each trigger events for the other task. ŒEVA is used to pass data associated with the event, as follows:
When the Child task is about to execute a command or expression, an onExecute event is triggered in the Parent's task object. When the callback function runs, ŒEVA contains the command or expression which the Child task is about to execute, as a simple character vector.
When an untrapped error occurs during function execution in the Child task, an onError event is triggered in the Parent's task object. When the callback function runs, ŒEVA contains the error message in the same form as ŒERM.
The Child and Parent tasks can each explicitly send an event to the other by using the Signal method. This takes any APLX array or overlay as an argument. When the onSignal callback in the receiving task runs, ŒEVA contains the array or overlay which the sending task specified.
ŒEVA allows your APL application to examine the arguments which an external caller (for example an OCX control or OLE server) has passed to APL as part of the underlying event-handling which occurs when an event is triggered. Typically, it is a simple or nested vector, with one element per argument passed by the control. If there are no arguments it is an empty vector. You can use the Events tab of the APLX Control Browser to see what events are associated with a control, and the parameters it passes.
For example, the Formula One spreadsheet-control allows you to specify a callback, to be triggered when the user clicks in a cell. The event name is onXClick, and the parameters are defined as:
void Click (long nRow, long nCol);
This means that it passes two integer parameters, which are the row and column of the cell in which the user has clicked. In your APLX callback function you can retrieve this information; ŒEVA will return a two-element vector with these two values.
When a .Net event for which you have defined an APL callback is triggered, ŒEVA contains a reference to the event argument object. This is an instance of the general .Net class System.EventArgs, or to a more specific descendant (such as System.Windows.Forms.MouseEventArgs), which provides information about the event. By examining the properties of this object, you can extract information about the event, such as the position of the mouse when the event was triggered.