EventChain Manual

Written for..................................: EventChain rev.1

Document revision.....................: 9
Written by..................................: Cem Kalyoncu
Intended audience......................: C++ programmers
Completion.................................: 70%, requires more sample usage

EventChain Manual...........................................................................................................................1
Introduction......................................................................................................................................1
Event Handling................................................................................................................................2
Creating Event Objects....................................................................................................................3

Introduction
EventChain is a library that allows programmers to create event objects and/or handle events
raised by those objects. Event chaining (or bubbling) mechanism works similar to languages that
have built-in event mechanism (like C#, Visual Basic and JavaScript). Objects that generate events
create event objects. Then any code needs to handle these events register their handling functions.
Whenever object raises the event (calling a specific function) all these registered event handlers are
called.

EvenChain system is designed to suit different requirements. Using C++ template system, any
type definition (class or built-in) can be used as parameter (multiple parameter passing is done
using structures). Our system supports both class and namespace functions as event handlers.
Moreover, different handler parameters are supported (see other sections for details). EventChain
also supports a single event handler to handle more than one event. To ease the use of this system,
we have allowed a single object of type Any to be supplied while registering a handler. Any class is
supplied with the system and can hold any type for parameter passing. If you do not include
“Any.h” in your project before including “EventChain.h”, EventChain will use void* instead.
Boost::Any will be supported soon.

Rest of this document is organized in two sections. First section describes how to handle events,
while second section describes how to create event objects. Readers are assumed to know how to
use C++ and template classes.

EventChain Manual Page: 1 / 3 Revision: 9

Event Handling
To handle events, you need to have event handler function. This function can either be non-
static class method or namespace function. Following is the list of supported function definitions,
functionname is the name of the function, parametertype is the type of parameters that are supplied
from the event source, objecttype is the type of caller object.

void functionname()
void functionname(parametertype params)
void functionname(objecttype &object)
void functionname(Any data)
void functionname(parametertype params, objecttype &object)
void functionname(parametertype params, objecttype &object, Any data)
void functionname(parametertype params, objecttype &object, Any data,
string eventname)

To register your handler function you should call Register function of the event object. Register
function has two alternatives, first one is used for namespace functions and the other one is used for
class methods. The samples in the following code registers a namespace function and a class
function. Objects that you wish to pass register function can either be references or pointers. If you
wish you can pass any data you want by converting you data to Any object. Any class creates the
copy of the given object, therefore, if you require an object to be changed, you should use its
pointer. These usage is also demonstrated. If no data is supplied NULL is used instead.

MyEvent.Register(&functionname); // Registers a namespace function

MyEvent.Register(my, &MyClass::functionname); //Registers a class method

MyEvent.Register( &functionname, Any(5) );

MyEvent.Register( my, &MyClass:functionname, Any(&anotherclass) );

The following is an example of this usage.

void canvas1_mousedown(mouse_event_params p, Canvas &canvas) {

cout<<"Mouse pressed at: ("<<p.x<<", "<<p.y<<")"<<endl;
}

...

canvas1.mouseDownEvent.Register(&canvas1_mousedown);

More examples will be added to this document in the next revision.

EventChain Manual Page: 2 / 3 Revision: 9

Creating Event Objects
EventChain class requires two template parameters. First parameter is the type of class
exporting the event. If you are exporting from a non-object context, you can use gge::Empty class
supplied in the library. Second template parameter is the type of the parameter that will be supplied
to the event handler. If your event requires more than one parameter to be supplied you may used
structures. If your event does not require a parameter, you may skip this template parameter, which
will default to empty_event_params structure. Following creates click event for a button. Notice
that the EventChain object requires event name and caller object to be supplied.

gge::EventChain<Button> ClickEvent;
...
Button(...) : ... ClickEvent("click", this), ...

EventChain Manual Page: 3 / 3 Revision: 9