Events

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: event handlers will not be called during leaks processing. That is because leaks detection happens AFTER finalizing application. See Configuring project for leaks detection for more info.

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 event handler. 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.

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;
 
// Some your routine to add a message to application 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
  
  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.

That's almost all for events and 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;
 
// Your handler for OnExceptionNotify event
procedure MyHandler(const ACustom: Pointer; AExceptionInfo: TEurekaExceptionInfo; 

  var AHandle: Boolean; var ACallNextHandler: Boolean);
begin
  // The same as exception filter for EMyException which changes dialog to "EurekaLog" style
  if AExceptionInfo.ExceptionClass = 'EMyException' then
    AExceptionInfo.Options.ExceptionDialogType := edtEurekaLog;
end;
 
initialization
  
  RegisterEventExceptionNotify(nil, MyHandler);
 
end.

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

To summarize:

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: