⎕EVA Event Arguments

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.

Use for APL Multi-Tasking (not available in Server Editions)

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.

Use for OCX/ActiveX controls and OLE Automation (Windows only)

⎕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.

Use in .Net programming (Windows only)

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.