eventManager.h

Engine/source/util/messaging/eventManager.h

More...

Classes:

Detailed Description

  1
  2//-----------------------------------------------------------------------------
  3// Copyright (c) 2012 GarageGames, LLC
  4//
  5// Permission is hereby granted, free of charge, to any person obtaining a copy
  6// of this software and associated documentation files (the "Software"), to
  7// deal in the Software without restriction, including without limitation the
  8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  9// sell copies of the Software, and to permit persons to whom the Software is
 10// furnished to do so, subject to the following conditions:
 11//
 12// The above copyright notice and this permission notice shall be included in
 13// all copies or substantial portions of the Software.
 14//
 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 21// IN THE SOFTWARE.
 22//-----------------------------------------------------------------------------
 23
 24#ifndef _EVENTMANAGER_H_
 25#define _EVENTMANAGER_H_
 26
 27#ifndef _CONSOLE_H_
 28#include "console/console.h"
 29#endif
 30
 31#ifndef _DISPATCHER_H_
 32#include "util/messaging/dispatcher.h"
 33#endif
 34
 35#ifndef _TSIMPLEHASHTABLE_H
 36#include "core/tSimpleHashTable.h"
 37#endif
 38
 39
 40//-----------------------------------------------------------------------------
 41/// Listener class used by the EventManager to dispatch messages to specific
 42/// callbacks.
 43//-----------------------------------------------------------------------------
 44class EventManagerListener : public Dispatcher::IMessageListener
 45{
 46   friend class EventManager;
 47
 48   /// Stores subscription information for a subscriber.
 49   struct Subscriber
 50   {
 51      SimObjectPtr< SimObject> listener;       ///< The listener object.
 52      StringTableEntry callback; ///< The callback to execute when the event is triggered.
 53      StringTableEntry event;    ///< The event being listened for.
 54     U32 callDepth;
 55     bool removeFlag;
 56   };
 57
 58   /// Subscriber table hashed by event name.
 59   SimpleHashTable< Vector<Subscriber> > mSubscribers;
 60
 61public:
 62   // Ensure that the subscriber map doesn't use case-sensitive string comparisons.
 63   EventManagerListener(): mSubscribers(64, false) {}
 64
 65   /// Called by the EventManager queue when an event is triggered. Calls all listeners subscribed to the triggered event.
 66   virtual bool onMessageReceived( StringTableEntry queue, const char* event, const char* data );
 67   virtual bool onMessageObjectReceived( StringTableEntry queue, Message *msg ) { return true; };
 68};
 69
 70/// @addtogroup msgsys Message System
 71// @{
 72
 73//-----------------------------------------------------------------------------
 74/// The EventManager class is a wrapper for the standard messaging system. It
 75/// provides functionality for management of event queues, events, and
 76/// subscriptions.
 77/// 
 78/// Creating an EventManager is as simple as calling <tt>new EventManager</tt>
 79/// and specifying a queue name.
 80/// 
 81/// Example Usage:
 82/// 
 83/// @code
 84/// // Create the EventManager.
 85/// $MyEventManager = new EventManager() { queue = "MyEventManager"; };
 86/// 
 87/// // Create an event.
 88/// $MyEventManager.registerEvent( "SomeCoolEvent" );
 89/// 
 90/// // Create a listener and subscribe.
 91/// $MyListener = new ScriptMsgListener() { class = MyListener; };
 92/// $MyEventManager.subscribe( $MyListener, "SomeCoolEvent" );
 93/// 
 94/// function MyListener::onSomeCoolEvent( %this, %data )
 95/// {
 96///    echo( "onSomeCoolEvent Triggered" );
 97/// }
 98/// 
 99/// // Trigger the event.
100/// $MyEventManager.postEvent( "SomeCoolEvent", "Data" );
101/// @endcode
102//-----------------------------------------------------------------------------
103class EventManager : public SimObject
104{
105   typedef SimObject Parent;
106
107private:
108   /// The name of the message queue.
109   StringTableEntry mQueue;
110   /// Registered events.
111   Vector<StringTableEntry> mEvents;
112
113   /// The event listener. Listens for all events and dispatches them to the appropriate subscribers.
114   EventManagerListener mListener;
115
116   /// List of all EventManagers.
117   static Vector<EventManager*> smEventManagers;
118
119   /// Sets the message queue.
120   static bool _setMessageQueue( void *obj, const char *index, const char *data )
121   {
122      static_cast<EventManager*>( obj )->setMessageQueue( data );
123      return false;
124   };
125
126public:
127   DECLARE_CONOBJECT( EventManager );
128
129   EventManager();
130   virtual ~EventManager();
131
132   static void initPersistFields();
133
134   /// @name Properties
135   /// @{
136
137   StringTableEntry getMessageQueue() const { return mQueue; }
138
139   void setMessageQueue( const char* queue );
140
141   /// @}
142
143   /// @name Event Management
144   /// @{
145
146   /// Checks if an event is registered.
147   bool isRegisteredEvent( const char* eventName );
148   /// Registers an event.
149   bool registerEvent( const char* eventName );
150   /// Removes an event.
151   void unregisterEvent( const char* eventName );
152   /// Removes all events.
153   void unregisterAllEvents();
154
155   /// Triggers an event.
156   bool postEvent( const char* eventName, const char* data );
157   /// Adds a subscription to an event.
158   bool subscribe( SimObject *callbackObj, const char* event, const char* callback = NULL );
159   /// Remove a subscriber from an event.
160   void remove( SimObject *cbObj, const char* event );
161   void removeAll( SimObject *cbObj );
162
163   /// @}
164
165   /// @name Debug Output
166   /// @{
167
168   /// Prints all registered events to the console.
169   void dumpEvents();
170   /// Prints all subscribers to the console.
171   void dumpSubscribers();
172   /// Prints subscribers to a specific event to the console.
173   void dumpSubscribers( const char* event );
174
175   /// @}
176
177   /// @name Event Manager Tracking
178   /// @{
179
180   /// Adds an EventManager.
181   static void addEventManager( EventManager* em ) { smEventManagers.push_back( em ); };
182
183   /// Removes an EventManager.
184   static void removeEventManager( EventManager* em )
185   {
186      for( Vector<EventManager*>::iterator iter = smEventManagers.begin(); iter != smEventManagers.end(); iter++ )
187      {
188         if( *iter == em )
189         {
190            smEventManagers.erase_fast( iter );
191            break;
192         }
193      }
194   };
195
196   /// Retrieves an EventManager.
197   static EventManager* getEventManager( const char* name )
198   {
199      StringTableEntry queue = StringTable->insert( name );
200      for( Vector<EventManager*>::iterator iter = smEventManagers.begin(); iter != smEventManagers.end(); iter++ )
201      {
202         if( ( *iter )->mQueue == queue )
203            return *iter;
204      }
205      return NULL;
206   };
207
208   /// Prints all the EventManagers to the console.
209   static void printEventManagers()
210   {
211      for( Vector<EventManager*>::iterator iter = smEventManagers.begin(); iter != smEventManagers.end(); iter++ )
212         ( *iter )->dumpSubscribers();
213   }
214  
215
216   /// @}
217};
218
219// @}
220
221#endif // _EVENTMANAGER_H_
222