Creating an event handler

An event handler is the code needed in your application to be notified that a COM event occurred. To create an event handler, you must do the following:

• Create a user-defined function in Dexterity to respond to the event.
• Create a callback object and add a method to the callback object for the event.
• Attach the event handler to the callback object.

User-defined function

You need to create a user-defined function for each event that you want to be notified of. The function will run each time the event occurs in the application you are integrating with. The parameters for the user-defined function must match those specified for the event. For example, the following is the description of the SheetSelectionChange event available for an Excel workbook.

Notice that this event returns two parameters, but no actual return value for the method. The first parameter is a reference to the worksheet for which the event occurred. The second parameter is range of cells selected in the worksheet.

The following user-defined function must be added to your Dexterity application to process this event. Notice that the parameters and return value correspond to those for the event. The parameters are in the same order as the event, and of the appropriate type. The event doesn’t have a return value, so the user-defined function indicates that nothing is returned. The additional code in the callback function retrieves the row and column of the new selection in the worksheet.

function returns nothing;

in reference worksheet;
in Excel.Range selection;

local long current_row;
local long current_column;

{Retrieve the current row and column}
current_row = selection.Row;
current_column = selection.Column;

'(L) Selection' of window Tool_Bar of form 'Main Menu' =  "Row:" + str(current_row) + " Column:" + str(current_column);

Callback object

To respond to a COM event from another application, you must create a callback object that contains the method or property necessary for the event. The name of the method or property in the callback must exactly match the name of the event.

Continuing the previous example, the following code creates the callback object to handle the SheetSelectionChange event. Notice in the DexObject_AddMethod() function that the name of the method added to the callback is the same as the name of the event. Also note that the COM_AttachEventHandler() function is used to associate the event for the active Excel worksheet with the corresponding callback object in the Dexterity-based application.

local Excel.Application app;
local reference callback_obj;
local long handler_id;

{Retrieve a reference to Excel.}
app = COM_GetObject("Excel.Application");

if app <> null then
	{Create the callback object to handle the event.}
	callback_obj = DexObject_Create();

	{Add the method for the SheetSelectionChange event.}
	DexObject_AddMethod(callback_obj, "SheetSelectionChange", function SelectionChangedEvent);

	{Attach the callback object.}
	handler_id = COM_AttachEventHandler(app.ActiveWorkbook, callback_obj);
	if handler_id = 0 then
		error "Could not attach event handler.";
	end if;
end if;

Once the callback object has been created and attached to the event, your application will begin receiving and processing events. Events will be processed until either application is shut down, or you detach the event handler with the COM_DetachEventHandler() function.

Responding to events

When an event occurs, the corresponding method will be called in the callback object within the Dexterity-based application. Often, it’s useful to be able to access the callback object from within the user-defined function that is run for the event. To access the properties or methods for the current callback object, use the this reference.

Troubleshooting

If the event handler isn’t processing events, check the following:

• Verify the name you used for the method in the callback exactly matches the event name. The name is case-sensitive.
• Be sure the parameter list and return value for the user-defined function match the parameter list and return value for the event. If the parameter types don’t match, the event handler can’t be attached to the callback object.

Documentation Feedback

---