Manual

Event System

Event management presents a system providing your application with message basaed communication of your software modules. Instead of using callback functions it is often more reliable to use an event based messaging system. Also events helps you to decrease dependency of different software modules.

So how event system works. Similar to the Qt signal/slot implementation the engine offers you an actor/channel implementation. Here one register new event channels in the engine, by calling

Engine::sEventManager()->createChannel("new_channel");

Now any event actor connected to the channel can receive and send messages (Note: to send messages you not have to be an actor, only if you also like to receive them you have to be one). To create an event actor you simple derive a new class from engine's EventActor? class:

class Actor : public nrEngine::EventActor
{

   // Initialize actor
   Actor()
   {
       // connect Actor to the new_channel event channel
       connect("new_channel");
   }


   // React on events
   void OnEvent(const nrEngine::EventChannel& channel, SharedPtr<nrEngine::Event> event)
   {
      // Check whenever the received event is of the type...
      if (event->same_as<OnGUIEvent>())
      {
          // cast the event into the type we want to have        
          SharedPtr<OnGUIEvent> ev = event_shared_cast<OnGUIEvent>(event);

          // use new received event
          reactOnGuiEvent(ev);

          // just for example purpose we send an event to the messaging system
          emit(new OnReceivedGUIEvent());
      }
   }

};

In this example we assumed you have already the classes OnGUIEvent and OnReceivedGUIEvent declared in your application. An example declaration of such a classes could look like this:

// Class derived from Event can be send through the event system
class OnGUIEvent : public nrEngine::Event {

    // need to declare this here to create meta information about this event            
    META_Event(OnGUIEvent)
        
    public:

        // just get data from the event
        const std::string& getGUIName() { return _guiname; }
        void* getData() { return _data; }

        // create event and fill already with some data.                        
        OnGUIEvent(const std::string& u, nrEngine::Priority prior = nrEngine::Priority::IMMEDIATE) : 
                        nrEngine::Event(prior), _guiname(u) {}
                
    private:
        // data stored in the event
        std::string _guiname;
        void* _data;
};

As you can see it is pretty simple to create new event types. Even more through the META_Event macro each event type can be also checked by a simple string comparison, i.e.

if (event->getEventType() == "OnGUIEvent") reactOnGuiEvent(event); 

Future work

Currently there is no remote event support. Hence sending events through some physical communication channel (e.g. network) does not work. In that case a plugin must be implemented which can deliver event messages on both sides of the channel. In fact the implementation shouldn't be a big problem and can be expanded completely by a plugin ;-)

See: ManualPage