[OpendTect_Developers] Events and callbacks

[Bert Bril]

Hi,


I'm getting the impression that our callback system is not fully 
understood by some. The header file callback.h may be a bit too detailed 
to easily get an overview. So here goes.

When you want to communicate an event to unknown users of your class, 
then you may consider using a callback mechanism. Users of your class 
can ask to be notified when something happens. Basically, they give a 
function + object to be called.

The ingredients are:


1) The object to be notified. To keep the system simple we require one 
thing: be a CallBacker. Thus, you have to make sure that your class is 
in some way inheriting from the CallBacker class. This is an empty class 
with one 'dummy' virtual function.


2) The object offering the notifications. This object simply adds a 
member of type Notifier to its public members:

     Notifier<InterestingClass>	itHappened;

In the constructor of the class you'll have to initialize this member 
with this:

     , itHappened(this)

Later, when that actually happens, you simply trigger the Notifier:

     itHappened.trigger();


3) Asking for notifications. You use the Notifier from the class 
offering the notifications, and give it the object+function to call. 
Usually the object is 'this', the function is a specially made member 
function. The signature of these functions is:

     void function_name(CallBacker*);

Thus, you put in your class, usually in the instructor:

interesting_thing.notify( mCB(this,WatchingClass,handleTheHappening) );

Then your function looks somethign like:

void WatchingClass::handleTheHappening( CallBacker* cb )
{
     // cb is usually pointing to the InterestingClass:
     // mDynamicCastGet(InterestingClass,intclssptr,cb)
     // should result in a non-null intclssptr
}



One more note: the mechanism is used mostly in the context of user 
interfaces, but it's by no means restricted to that. For example, the 
SeisSingleTraceProc class uses it to allow exclusion and processing of 
traces it handles.


/Bert

-- 
-- Bert Bril / OpendTect developer at dGB
-- mailto:Bert.Bril at opendtect.org , http://opendtect.org