Changes between Initial Version and Version 1 of EventManagement

Timestamp:

10/06/07 19:12:37 (17 years ago)

Author:

art

Comment:

--

EventManagement

@@ +1 @@
+= 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
+{{{
+#!cpp
+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:
+{{{
+#!cpp
+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:
+{{{
+#!cpp
+
+// 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. 
+{{{
+#!cpp 
+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 ;-)
+