quick_guide

Here is a straight-forward guide to show you how to use the code.

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.

Declaring Events

An event object for invocation is used by sender object to perform notifications, usually it's a member variable of template class CppEvent::Event<>.

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:

    Button(Widget* parent);

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

protected:

    virtual void mousePress (MouseParams const & params);

private:

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

void Button::mousePress(MouseParams const & params)
{
    clicked.Invoke();
}

Connecting Events

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

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

Connection is established by connect() method of the CppEvent::EventRef<>. It is a function that requires 2 arguments.

• A pointer to a CppEvent::Trackable object
• A pointer to the member of the receiver object

Example 2. Connect an 'OK' button to a dialog

class Widget: public CppEvent::Trackable;

class Dialog: public Widget
{
public:

    Dialog (Widget* parent);

    void OnShowText ();
};


Button* btn = new Button;

Dialog* dlg = new Dialog;

btn->clicked().connect(dlg, &Dialog::OnShowText);

Arguments

Events can have arguments. Types of arguments are specified as arguments for template class CppEvent::Event<> and CppEvent::EventRef<>.

Example 3. Event with arguments

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

private:
    CppEvent::Event<bool> toggled_;
};

Multicast

Event Chaining

A CppEvent::Event<> class 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.

Virtual Member Function

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

Example 5. Connect Event to a virtual method

class Widget: public CppEvent::Trackable;

class AbstractDialog: public Widget
{
public:
  AbstractDialog (Widget* parent)
  {
      ok_ = new Button;
      ok->clicked().connect(this, &AbstractDialog::OnShowText);
  }

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

private:

  Button* ok_;
};

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