Method ActiveXObject():suspendEvent() Foundation

Suspends event processing for a COM/ActiveX event.

:suspendEvent( <cName> | <nDISPID> | NIL ) --> nSuspendCount
<cName> is a character string that specifies the name of the event processing is to be suspended for.
<nDISPID> is a numeric value that specifies the dispatch ID (DISPID) of the event processing is to be suspended for. This parameter may be used as an alternative to <cName>.
If the value NIL is passed to :suspendEvent(), event processing is suspended for all COM/ActiveX events subscribed by the ActiveX object.

This method returns a numeric value specifying the current suspend count of the COM/ActiveX event or events specified. Processing for an event is suspended as long as the event's suspend count is greater than zero. If neither <cName> nor <nDISPID> are specified or NIL is passed as a parameter, return is the highest suspend count of the events subscribed by the ActiveXObject.


The method :suspendEvent() can be used to temporarily suspend processing of a certain COM/ActiveX event. If NIL is passed instead of an event name or dispatch ID (DISPID), event processing is suspended for all events subscribed by the ActiveX object.

Each call to method :suspendEvent() increments a counter associated with the event or events specified. As long as an event's suspend counter contains a value greater than zero, no event processing is performed for the event by the ActiveXObject instance. To resume event processing, an application uses the method :resumeEvent(). Calling :resumeEvent() decrements the event's suspend counter, causing event processing to be resumed when the suspend counter reaches zero.

Calls to :suspendEvent() can be nested. However, each call to :suspendEvent() must be matched by a call to :resumeEvent(). Otherwise, the event remains in suspended state until the event's suspend counter reaches zero.

An Xbase++ application can use :suspendEvent() to prevent recursive calls of a specific event handler code block or method. Furthermore, suspending events may be required when the application cannot respond to COM/ActiveX events for any reason.


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.