| Applies To: | ActiveXControl | OLEServer |
Description
This method is used to register an event that may be generated by an ActiveXControl or OLEServer object.
A host application that wishes to attach a callback function to an event in a Dyalog APL ActiveXControl or OLEServer, needs to know the name of the event and the number and data types of any parameters that the event may supply. It also needs to know the data type (if any) of the result that the callback function may be expected to pass back to the control.
An ActiveXControl or OLEServer generates an event in the host application using 4 ⎕NQ. The right argument is a vector whose first 2 elements are character vectors containing the names of the ActiveXControl or OLEServer and the event respectively. The parameters for the event are passed as additional elements in the argument.
Another way to think about it is that when you generate an event using 4 ⎕NQ, you are effectively calling a function, of your specification, in the host application. To enable the host application to accept the function call, it needs to know the number of parameters that you will supply and their data types.
A further consideration is that if you specify that the data type of a parameter is a pointer (for example, 'VT_PTR TO I4') this will allow a callback function to modify the parameter in-situ. If so, the result returned by 4 ⎕NQ will be the modified values of any such parameters; this is a similar mechanism to ⎕NA.
The argument to SetEventInfo is a 1, 2, 3 or 4-element array as follows:
| [1] | Event name | character vector |
| [2] | Event info | nested array (see below) |
| [3] | Help ID | integer |
| [4] | DISPID | integer. See DISPID (Dispatch ID) |
Event info
Event info, specifies an optional help string which describes what the event does, the data type of the result (if any) and the names and data types of its arguments.
If the event is fully described, each element of Event Info is a 2-element vector of character vectors. The first element contains the help string and the COM data type of the result that the callback function in the host application is expected to supply. Subsequent elements contain the name and COM data type of each of the parameters supplied by the event.
However, both the help string and the names of the parameters are optional and may be omitted. If so, one or more elements of Event Info may be a simple character vector.
Help ID
This is an integer value that identifies the help context id for the event within the help file associated with the HelpFile property of the ActiveXControl object. The value ¯1 means that no help is provided. APL stores this information in the registry from where it may be retrieved by the host application.
Example
The example Dual ActiveXControl, that is fully described elsewhere, generates a ChangeValue1 event. This event occurs when the user moves the thumb in a TrackBar that is internal to an instance of the ActiveXControl.
The external ChangeValue1 event is fired by an internal APL callback function (called ChangeValue) that is attached to ThumbDrag and Scroll events on the TrackBar object. The internal callback function is :
[0] ChangeValue MSG [1] ⍝ Callback for ThumbDrag and Scroll [2] Value1←4 ⎕NQ'' 'ChangeValue1'(⊃¯1↑MSG) [3] CalcValue2 [4] 'V1'⎕WS'Text'(⍕Value1) [5] 'V2'⎕WS'Text'(⍕Value2)
Note that ChangeValue[2] generates the external ChangeValue1 event by invoking 4 ⎕NQ, passing it the new value provided by the TrackBar. However, the host application is permitted to modify that value, returning it in the result of 4 ⎕NQ. This result, rather than the TrackBar value itself, is then used to update other (Label) controls in the object.
The following statements were used to declare the ChangeValue1 event The event provides a single parameter named Value1 that may be modified in-situ by a callback function in the host application. The callback is not, otherwise, expected to return a result.
INFO←⊂'Occurs when the value of the control is changed' 'VT_VOID'
INFO,←⊂'Value1' 'VT_PTR TO VT_I4'
F.Dual.SetEventInfo 'ChangeValue1' INFO
If the host application was Visual Basic, a suitable callback function might be:
Private Sub Dual1_ChangeValue1(Value1 As Long) Value1=2*(Value1\2) End Sub
This callback function receives the proposed new value of the control as the parameter Value1, and modifies it, forcing it to be an even number.