Written for : EventChain rev.1
Document revision : 7
Written by : Cem Kalyoncu
Intended audience : C++ programmers
Completion : 70%, requires more sample usage
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.
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 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 to be supplied.
gge::EventChain<Button>
ClickEvent;
...
Button(...) : ...
ClickEvent("click"), ...
EventChain
Manual
Revision:
7