quick_guide

Quick Guide

Build and Installation

You can just drag the source code into your C++ project.

Or use cmake to build a dynamic or static library, just

$ cd <folder where you checkout the source>
$ mkdir build
$ cd build
$ cmake ../
$ make && sudo make install

By default, it will install header files to /usr/local/include, and library binary to /usr/local/lib.

Available cmake options:

• CMAKE_INSTALL_PREFIX: this is a built-in cmake option, which you can use to specify where to install the headers and library. Default is /usr/local.
• BUILD_UNIT_TEST: A bool option to compile the unit test code. Default is OFF.
• WITH_QT5: A bool option to compile test code to compare this project with Qt5 signal-slot. Default: OFF.

An example to use all these options:

$ cmake ../ -DCMAKE_INSTALL_PREFIX=/usr -DBUILD_UNIT_TEST=ON -DWITH_QT5=ON

Note: To compile test code to compare with boost::signals, you need to install boost signals dev package. To compile test code to compare with Qt signal slot, you need to install Qt5 package.

Declare Event

Use the template class CppEvent::Event<> to declare an event. In mose cases, you need to use it as a member variable in your class, you can put it in any area of public, protected, private as you want.

For example, suppose you are developing a GUI project, you may need a clicked event in a button class:

Example 1. Button class with 'clicked' event

class Button: public Widget
{
public:

    // ...

    // Event connection interface
    inline CppEvent::Event<>& clicked ()
    {return clicked_;}

private:

    // Event implementation
    CppEvent::Event<> clicked_;
};

Note: an event object is not copyable. e.g.

CppEvent::Event<> event1;
CppEvent::Event<> event2(event1);	// Error
CppEvent::Event<> event3;
event3 = event1;	// Error

Arguments

Events can have arbitrary number of arguments (based on variadic templates support in C++11). Types of arguments are specified as arguments for template class CppEvent::Event<>.

For example:

using namespace CppEvent;

Event<Widget* sender, bool toggled> event1;
Event<const String& str, size_t length> event2;

Connect Event

Events can be connected to event handlers. In libCppEvent, event handlers are member functions bound to the specific object. Internally libCppEvent implement delegate in a way inspired by Fast C++ Delegate: Boost.Function 'drop-in' replacement and multicast by JaeWook Choi.

Note: You cannot connect event to any member function. You can only connect an event to member functions of a CppEvent::Observer or subclass. This design makes sure when the Observer object is deleted, all event connection will be removed safely.

Connection is established by Connect() method of the CppEvent::Event<>. The method requires 3 arguments.

• A pointer to a CppEvent::Trackable object (the base class of CppEvent::Observer).
• A pointer to the member function of the receiver object.
• The position where to insert the connection. Default is -1, which means append this new connection.

Example 2. Connect a button to a label widget.

class Widget: public CppEvent::Observer;

class Label: public Widget
{
public:

    Dialog (Widget* parent);

    void OnUpdate ();
};

Button* btn = new Button;
Label* lbl = new Label;

btn->clicked().Connect(lbl, &Label::OnUpdate);

Multiple Connections

Note: If you call the Connect() multiple times, it will create the same number of connections.

btn->clicked().Connect(lbl, &Label::OnUpdate);  // 1
btn->clicked().Connect(lbl, &Label::OnUpdate);  // 2
btn->clicked().Connect(lbl, &Label::OnUpdate);  // 3
// now the btn's clicked event has 3 connections

This is because the Connect() does not check if the delegate already exists, to provide the multicast.

Insert Position

CppEvent::Event<> holds a list to store connections, the third argument of Connect() assigns where to insert the new connection:

• if >= 0, insert in order, so 0 will always push front the new connection.
• if < 0, insert in reverse order, so -1 (the default) will always push back the new connection.
• You can assign any number (in int) of the position, so a large positive number is the same as push back, a very negative is the same as push front.

Fire Event

After an event is connected to a member function, you can fire the event at the appropriate time in your application, with the same variadic arguments you decalre the event.

Example 3. Fire the button's clicked event.

class Button: public Widget
{
public:

    // ...

    // Event connection interface
    inline CppEvent::Event<>& clicked ()
    {return clicked_;}

protected:

  virtual void mouseDown (Input* input) override
  {
    // do sth...
    clicked_.Fire();  // now fire the event
  }

private:

    // Event implementation
    CppEvent::Event<> clicked_;
};

Disconnect Event

There're 2 methods for disconnecting from member function:

• DisconnectAll (T* obj, void (T::*method) (ParamTypes...))
• DisconnectOnce (T* obj, void (T::*method) (ParamTypes...), int start_pos = -1)

The first one will remove all connections match the delegate to the member function. The second one will start to search the connection list forward or backward from the start_pos, and remove only the first one found.

For example:

btn->clicked().Connect(lbl, &Label::OnUpdate);  // 1
btn->clicked().Connect(lbl, &Label::OnUpdate);  // 2
btn->clicked().Connect(lbl, &Label::OnUpdate);  // 3

btn->clicked().DisconnectOnce(lbl, &Label::OnUpdate); // This will remove the #3 connection.
btn->clicked().DisconnectAll(lbl, &Label::OnUpdate);  // This will remove the remaining #1,#2 connections.

Observer

You can disconnect the event when being invoked in an observer:

void Label::OnUpdate (Button* sender)
{
	sender->clicked().Disconnect(this, &Label::OnUpdate);
}

You can delete this when being invoked:

void Label::OnUpdate ()
{
	delete this;
}

You can remove all in-connections by CppEvent::Observer::RemoveAllInConnections().

Multicast

Note: CppEvent::Event<> supports multicast, when you fire an event, it will invoke all connected methods.

Button* btn = new Button;
Label* lbl1 = new Label;
Label* lbl2 = new Label;
Label* lbl3 = new Label;

btn->clicked().Connect(lbl1, &Label::OnUpdate);
btn->clicked().Connect(lbl2, &Label::OnUpdate);
btn->clicked().Connect(lbl3, &Label::OnUpdate);

Now when fire the clicked event, all three OnUpdate() member functions in different objects will be invoked in order.

Event Chaining

A CppEvent::Event<> object can be used as an event handler too, as it's also a trackable object.

Example 4. Event chaining

Button* btn1 = new Button;
Button* btn2 = new Button;

btn1->clicked().Connect(btn2->clicked());

Click btn1 will fire clicked() event in btn2.

You can disconnect the connection to another event by:

• DisconnectAll()
• DisconnectOnce()

Same as the member function situation above.

For example:

btn1->clicked().DisconnectOnce(btn2->clicked());
btn1->clicked().DisconnectAll(btn2->clicked());

Note: You can remove all connections to member functions and events with RemoveAllOutConnections().

Virtual Member Function

Member function which is connected to an event can be virtual and abstract (pure virtual).

Example 5. Connect event to a virtual method

class Widget: public CppEvent::Observer;

class AbstractDialog: public Widget
{
public:
  AbstractDialog (Widget* parent);

  virtual void OnUpdate () = 0; // pure virtual

};

class Dialog: public AbstractDialog
{
public:
    Dialog (Widget* parent);
    virtual void OnUpdate () = override;
};

AbstractDialog *dlg = new Dialog();
btn1->clicked().Connect(dlg, &AbstractDialog::OnUpdate);

Complex Example

Performance

Faster than boost::signal2 and Qt signal-slot.

Advice On Multi-thread Programming

Warning: libCppEvent does not provide any protection in multi-thread environment. You should take care of the racecondition in your code.

TBD

Use Delegate Only

You can also use CppEvent::Delegate<>.

TBD