COM events

You can add considerable power to your add-in if you catch COM events. These are events raised by Excel's COM interface at important moments in the life of a worksheet, a workbook and the Excel application.

Among the more useful events to trap are:

Event	Description
Calculate	Occurs just after Excel has finished calculating a worksheet.
WorkbookOpen	Occurs just after Excel has opened a workbook.
NewWorkbook	Occurs just after Excel has opened a workbook.
WorkbookBeforeClose	Occurs just before Excel closes a workbook.
WorkbookBeforeSave	Occurs just before Excel saves a workbook.

You can find a full list of COM events below.

Enabling COM events

Before any COM events will be trapped, you must enable COM events by calling CXllApp::SetSinkEvents(TRUE). You can then set handlers for any event, using CXllApp::SetComEventHandler, and passing the name of your event handler.

Event handlers

An event handler is an add-in function with the correct signature (i.e. list of arguments) for the event it is 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.

Event	Return value	Argument 1	Argument 2
NewWorkbook	(ignored)	const char* WorkbookName
SheetSelectionChange	(ignored)	const char* WorksheetName	const char* Range
SheetBeforeDoubleClick	BOOL Cancel	const char* WorksheetName	const char* Range
SheetBeforeRightClick	BOOL Cancel	const char* WorksheetName	const char* Range
SheetActivate	(ignored)	const char* WorksheetName
SheetDeactivate	(ignored)	const char* WorksheetName
SheetCalculate	(ignored)	const char* WorksheetName
SheetChange	(ignored)	const char* WorksheetName	const char* Range
WorkbookOpen	(ignored)	const char* WorkbookName
WorkbookActivate	(ignored)	const char* WorkbookName
WorkbookDeactivate	(ignored)	const char* WorkbookName
WorkbookBeforeClose	BOOL Cancel	const char* WorkbookName
WorkbookBeforeSave	BOOL Cancel	const char* WorkbookName	BOOL bSaveAsUI
WorkbookNewSheet	{ignored)	const char* WorkbookName	const char* WorksheetName

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).

Example

See the ComEvents sample for examples of handling all COM events.

Next: Using the Excel Formula Wizard >>