Using Automation Events

To register your interest in a specific set of automation events, you must first define a reference to the set of automation events in which you are interested. When you have registered your interest, these event methods are then triggered in the same way as event methods for JADE controls.

To set up an automation event handler

1. Select the Add Reference command from the Properties menu in the Class Browser to create a property that is a reference to an event in the IDispatch class.

2. Use the Define Reference dialog that is then displayed to specify your event reference property, as you would for any other reference property. (For details, see "Adding a Reference Property", in Chapter 4 of the JADE Development Environment User’s Guide.)

   To summarize:

   1. In the Name text box, specify the name of the event reference that you want to define.

      The maximum length of the property name varies and it cannot be greater than the length of the longest method name of the event interface. The name cannot be the same as the name of any existing property or non-mapping method in the class, its superclasses, or subclasses.

   2. In the Type combo box, perform one of the following actions.

   • Select the required type in the Type list.

     The types that are listed are the subclasses of the IDispatch class that correspond to each ActiveX event dispInterface defined in the type library.

   • Specify the first character or the first few characters of the type in the text box and then select the required type from the Type list.

     The selected type is then displayed in the Type combo box.

   3. Check the Subschema Hidden check box if you want to specify that the event reference is available only in the local schema. This check box is unchecked by default; that is, the event reference is available in subschemas.

      Subschema-hidden event references that are not available for use in any subschemas cannot be referenced by subschema code and they are not displayed in subschema Class Browsers. For details, see "subschemaHidden Option" under "Controlling the Use of Elements in Other Schemas", in Chapter 1 of the JADE Development Environment User’s Guide.

   When you have defined an event reference and you then select it in the Properties List of the Class Browser, the Methods List is populated with disabled methods that correspond to the methods of the event interface.

3. To add an automation event method, from the Methods List select the disabled method name that corresponds to the event in which you are interested.

   The editor pane then displays the method template with a signature that matches that of the automation event method. As it also marks your new method as having the same signature as the selected event and checks it at compile time, you cannot change the signature of your event method.

4. Unlike control and form events, you must register interest in an event set. The events are not triggered until the event set has been registered by calling the ActiveXAutomation class beginNotifyAutomationEvent method, which has the following signature.

   beginNotifyAutomationEvent(receiver: Object; eventClassRefName: String);

   The receiver parameter specifies the object to which the event is sent (that is, that receives the message) and the eventClassRefName parameter specifies the name of the event reference property that you defined in the Define Event Reference dialog.

The methods defined by the event reference are then executed each time its corresponding automation event occurs. This event notification continues until the JADE automation object is deleted or until the endNotifyAutomationEvent method is called, which has the following signature.

endNotifyAutomationEvent(receiver: Object; eventClassRefName: String);