CXllApp::SetComEventHandler

Sets the name of an add-in function to handle a specific COM event

void SetComEventHandler(
   int nEvent,
   const TCHAR* pszMacroName
);

Parameters

nEvent

An integer representing the event to be handled. See Remarks below for a list of values.

pszMacroName

The name of the macro function that will be called when the event occurs. The parameter should be set to NULL or an empty string to switch off event handling for this event.

Observer Event model

This mechanism is now deprecated. It still works, but developers should note that an event handler of this type will override the observer event model. Thus, for example, if SetComEventHandler() is called for the Calculate event, any Calculate event observers that have been registered will not receive events.

Existing add-ins that use SetComEventHandler to handle events, and does not use the event model need not be changed. However, if you are using any features that rely on the event model, you should convert to the event model. Features that rely on the event model include handles and asynchronous functions.

See Events in the User Guide for an introduction to the observer event model.

Note:
This method is deprecated.

Remarks

This function sets the name of an add-in function that will be called whenever the specified COM event occurs.

If it is set to the name of an add-in function with the appproriate signature, the function will be called. If the function name is set to an empty string then no special error handling will occur.

Note: COM event handlers installed through this mechanism will not be called unless the SinkEvents flag has been set to TRUE, using CXllApp::SetSinkEvents(TRUE).

Add-in functions for event handling

The table below describes the events and the signatures of the functions that handle them. You can find a set of example functions with the correct signatures in the ComEvents sample.

The following restrictions and notes also apply to event handler callback functions:

Macro functions

Event handler call-back functions must be marked as Macro functions in the XLL+ Function Wizard.

WorksheetName

The WorksheetName argument will always be in the form [Book1]Sheet1. You can split into it's constituent parts with the CXllApp::SplitSheetName() method.

BOOL Cancel

Some of these handlers are expected to return a BOOL result, which tells Excel whether to carry on processing the event. You should normally return FALSE, and only return TRUE if you wish to disable further standard event handling.

SetSinkEvents

The event handler will not be called unless COM event handling has been switched on using CXllApp::SetSinkEvents(TRUE).

For more details about these events, see Excel Help for the events of the Application object.

Requirements

Header: xllplus.h

See Also

CXllApp Class | CXllApp Methods | CXllApp::GetComEventHandler() | CXllApp::SetSinkEvents() | ComEvents sample