Method ActiveXObject():comDefaultHandler()

Default handler for processing COM/ActiveX events.

:comDefaultHandler( <nDISPID>, [<param1>, ... ] ) --> xReturn

<nDISPID> is a numeric value specifying the Dispatch ID (event code) of the event fired.

[<param1>, ... ]

Optional parameters passed by the object that generated the event identified by <nDISPID>. The number and values of the event parameters passed to this method vary depending on the event fired.

This method returns the value returned by the method handling the event passed. If :comDefaultHandler() cannot find a method for handling the event identified by parameter <nDISPID>, return is the object executing the method (self).

The method :comDefaultHandler() is the default event handler of an ActiveXObject instance. Whenever the ActiveX object connected fires an event to be processed by the Xbase++ application,:comDefaultHandler() is called with the event's dispatch ID (DISPID) and event parameters. The default event handling implemented in method :comDefaultHandler() performs the following actions:

Check whether the event generated is suspended. If so, the event is simply ignored. An application can suspend processing for COM/ActiveX events using method :suspendEvent().

Determine the human-readable name of the event generated using type library information of the COM/ActiveX component connected.

Check whether the ActiveXObject's class implements a method of the same name as the COM/ActiveX event. If so, this method is assumed to be an event callback method for the event generated. If such a method is found, :comDefaultHandler() calls it using the following call profile:

::HandlerMethod( nDISPID, [param1, ... ] )

Eval( ::HandlerBlock, nDISPID, [param1, ... ] )

Event callback code blocks can be used by an application to customize a component. When writing a class wrapping a COM/ActiveX component for usage by other developers, it is recommended to use callback methods for implementing the component or wrapper class' behaviour when a certain COM/ActiveX event is generated. This leaves the corresponding callback slot free for usage on the application-level.

Internally, a COM/ActiveX component uses a protocol defined by the Common Object Model (COM) to communicate with the ActiveXObject instance it is connected to. The internal notification mechanism is based on calls to the generic method :invoke(), which operates based on so-called dispatch ids (DISPIDs). A DISPID uniquely identifies a property or method defined by a COM/ActiveX component. When an event is fired by a COM/ActiveX component, it notifies the application by calling method :invoke() of an internal dispatch interface, passing it the dispatch identifier (DISPID) of the event in question. Instances of the ActiveXObject class pass on the event notification to the default event processor, :comDefaultHandler().

For further information on dispatch interfaces and dispatch ids, please see the documentation on AutomationObject()and AutomationObject:invoke().

The method :comDefaultHandler() is called automatically by the COM event sub-system. Xbase++ applications need not call this method directly. To invoke processing for a certain COM/ActiveX event, the method :fireEvent() should be used instead.

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Method ActiveXObject():comDefaultHandler() Foundation