EurekaLog's event is similar to standard Delphi/C++ Builder events, such as OnClick for TButton. Event handler is callback procedure or method, which you regiter for some event. EurekaLog will call your event handler (i.e. your code) each time this event occurs. There are many events available. Most commonly used are OnExceptionNotify and OnExceptionAction.

Important Note: NEVER assume thread in which your event handler will run. Your event handler may be called from a background thread even in single-threaded application. For example, a stack overflow exception will force all event handlers to run from a background service thread. Conclusion: always use proper synchronization when accessing global entities from your event handlers.

Note: each event handler is declared as both method or procedure. You can use either option, there is no difference between method and procedure, so you can use whatever you want.

There are two ways of registering your code as an event handler.

Registering event handler with EurekaLog component

The most simple way is to use TEurekaLogEvents component. This component is similar to standard TApplicationEvents component. Just drop it on the form and assign handlers by using "Events" page in Object Inspector:

TEurekaLogEvents component on the form and one event hanlder assigned

While this is very simple way, you should be aware that your event handlers will be registered as long as host form lives. Thus, your event handler will not be invoked for events during initialization/finalization of your application. For this reason:

Note: registering event handler via component will create/use event handler as method of the object (i.e. form), not as callback procedure.

Registering event handler with code

Second method to register event handler is to call RegisterEventName function, where Name is a name of event. For example, you may use such code:

unit Unit1;
 
interface
 
...
 
implementation
 
uses
  EEvents; // for RegisterEventExceptionNotify
 
// Some your routine to add a message to an application's log
procedure AddToLog(const AMessage: String);
begin
  ...
end;
 
// Your handler for OnExceptionNotify event
procedure MyHandler(const ACustom: Pointer; 

  AExceptionInfo: TEurekaExceptionInfo; 

  var AHandle: Boolean; 

  var ACallNextHandler: Boolean);
begin
  if AExceptionInfo.ExceptionClass = 'EMyException' then
  begin
    AddToLog(AExceptionInfo.CallStack.ToString);
    AHandle := False;
  end;
end;
 
initialization
  // Ask EurekaLog to call our code
  RegisterEventExceptionNotify(nil, MyHandler);
end.

This sample event handler will log call stack of each exception of EMyException type, and it will disable EurekaLog's processing for these exceptions.

As you can see - you need to write all code by yourself (i.e. handler registration and procedure header/prototype). All events are declared in EEvents unit.

Note: you may unregister registered event handler by using UnregisterEventName function, but it's not required. See examples when it is required.

Important note: event handlers will not be called during leaks processing. That is because leaks detection happens AFTER finalizing application. See How to register event handler for leaks for more info.

Samples

That's almost all basics for events and event handlers (see also: understanding event handlers), but we must discuss one more important thing. Once exception is raised, EurekaLog options are captured from CurrentEurekaLogOptions function. Each exception is accompanied by TEurekaExceptionInfo class, which contains property and options for each exception. Further changes in CurrentEurekaLogOptions will not affect already raised exceptions. Threfore, your changes of CurrentEurekaLogOptions inside any event handler for exceptions will have no effect for current exception. It will affect only future exceptions. To change options of current exceptions - use Options property of TEurekaExceptionInfo class. For example:

unit Unit1;
 
interface
 
...
 
implementation
 
uses
  EEvents, // for RegisterEventExceptionAction
  ETypes;  // for atShowingExceptionInfo
 
// Our event handler which will be called when dialog is shown
procedure ChangeTexts(const ACustom: Pointer; AExceptionInfo: TEurekaExceptionInfo;
  const AEurekaAction: TEurekaActionType; const AAdditionalInfo: string;
  var AExecute, ACallNextHandler: Boolean);
begin

  // Is dialog about to be shown?
  if AEurekaAction = atShowingExceptionInfo then

    // Alter text in the dialog:
    AExceptionInfo.Options.CustomizedTexts[mtMSDialog_ErrorMsgCaption] :=  // Correct!
    CurrentEurekaLogOptions.CustomizedTexts[mtMSDialog_ErrorMsgCaption] := // Incorrect!
      '%0:s has encountered a problem: ' + AExceptionInfo.BugIDStr + '. We are sorry for the inconvenience.';
end;
 
initialization
  // Ask EurekaLog to call our event handler
  RegisterEventExceptionAction(nil, ChangeTexts);
end.

This sample code will alter header text of the MS Classic dialogs.

The similar concern is applied for many other objects in EurekaLog. Such as dialogs, send engines, log report builders, call stack classes, etc. They all have Options property, which is captured from their "parent" or CurrentEurekaLogOptions if there is no "parent".

Summary

Event handlers offer you unlimited ability for customizing EurekaLog, but only within certain points of interest (i.e. events). You can't alter whole processing logic by using only event handlers.

Important note: ensure that features specified by your code will be available at run-time. For example, if your application uses MS Classic-styled exception dialog by default and you want to switch to EurekaLog-styled dialog with your code - then be sure to include code for EurekaLog dialog into your application. The same is true for send engines. Hooks and debug information providers are registered on startup and could not be customized at run-time.

See also: