Spinning Topp Logo BlackTopp Studios
inc
eventpublisher.h
1 // © Copyright 2010 - 2016 BlackTopp Studios Inc.
2 /* This file is part of The Mezzanine Engine.
3 
4  The Mezzanine Engine is free software: you can redistribute it and/or modify
5  it under the terms of the GNU General Public License as published by
6  the Free Software Foundation, either version 3 of the License, or
7  (at your option) any later version.
8 
9  The Mezzanine Engine is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY; without even the implied warranty of
11  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12  GNU General Public License for more details.
13 
14  You should have received a copy of the GNU General Public License
15  along with The Mezzanine Engine. If not, see <http://www.gnu.org/licenses/>.
16 */
17 /* The original authors have included a copy of the license specified above in the
18  'Docs' folder. See 'gpl.txt'
19 */
20 /* We welcome the use of the Mezzanine engine to anyone, including companies who wish to
21  Build professional software and charge for their product.
22 
23  However there are some practical restrictions, so if your project involves
24  any of the following you should contact us and we will try to work something
25  out:
26  - DRM or Copy Protection of any kind(except Copyrights)
27  - Software Patents You Do Not Wish to Freely License
28  - Any Kind of Linking to Non-GPL licensed Works
29  - Are Currently In Violation of Another Copyright Holder's GPL License
30  - If You want to change our code and not add a few hundred MB of stuff to
31  your distribution
32 
33  These and other limitations could cause serious legal problems if you ignore
34  them, so it is best to simply contact us or the Free Software Foundation, if
35  you have any questions.
36 
37  Joseph Toppi - toppij@gmail.com
38  John Blackwood - makoenergy02@gmail.com
39 */
40 #ifndef _eventpublisher_h
41 #define _eventpublisher_h
42 
43 #include "event.h"
44 #include "exception.h"
45 
46 namespace Mezzanine
47 {
48  class Event;
49  ///////////////////////////////////////////////////////////////////////////////
50  /// @class EventPublisher
51  /// @headerfile eventpublisher.h
52  /// @brief This is the base class for any class that generates and publishes events to subscribers.
53  /// @details
54  ///////////////////////////////////////
56  {
57  public:
58  /// @brief Basic container type for @ref Event storage by this class.
59  typedef std::map<String,Event*> EventContainer;
60  /// @brief Iterator type for @ref Event instances stored by this class.
61  typedef EventContainer::iterator EventIterator;
62  /// @brief Const Iterator type for @ref Event instances stored by this class.
63  typedef EventContainer::const_iterator ConstEventIterator;
64  protected:
65  /// @internal
66  /// @brief A container storing all the Events published by this class by name.
67  EventContainer Events;
68  /// @internal
69  /// @brief Stores whether or not events will actually be fired when requested.
71 
72  /// @internal
73  /// @brief Creates a new event this Publisher can fire.
74  /// @note If the event already exists, this will return the created event instead.
75  /// @param EventName The name to be given to the new event.
76  /// @return Returns a pointer to the created or existing event.
77  Event* AddEvent(const String& EventName);
78  /// @internal
79  /// @brief Fires an event.
80  /// @param Args The arguments/event specific data related to this event.
81  void FireEvent(EventArgumentsPtr Args);
82  /// @internal
83  /// @brief Removes an existing event in this Publisher.
84  /// @param EventName The name of the event to be removed.
85  void RemoveEvent(const String& EventName);
86  /// @internal
87  /// @brief Removes all events in this Publisher.
88  void RemoveAllEvents();
89  public:
90  /// @brief Class constructor.
92  /// @brief Class destructor.
93  virtual ~EventPublisher();
94 
95  ///////////////////////////////////////////////////////////////////////////////
96  // Utility
97 
98  /// @brief Sets whether or not event firings by this publisher will be suppressed.
99  /// @param Mute True to prevent events from firing, false for normal operation.
100  void SetMuteEvents(const Boole Mute);
101  /// @brief Gets whether or not event firings by this publisher will be suppressed.
102  /// @return Returns true if events are being supressed, false if this publisher is operating normally.
103  Boole GetMuteEvents() const;
104 
105  /// @brief Gets an event in this publisher.
106  /// @param EventName The name of the event to retrieve.
107  /// @return Returns a pointer to the requested event.
108  Event* GetEvent(const String& EventName) const;
109  /// @brief Gets an event in this publisher.
110  /// @exception This version differs from the non-except version in that if it fails to find the event specified
111  /// it will throw a "II_IDENTITY_NOT_FOUND_EXCEPTION".
112  /// @param EventName The name of the event to retrieve.
113  /// @return Returns a pointer to the requested event.
114  Event* GetEventExcept(const String& EventName) const;
115 
116  ///////////////////////////////////////////////////////////////////////////////
117  // Subscribe Methods
118 
119  /// @brief Adds a subscriber to this event.
120  /// @param EventName The name of the event to subscribe to.
121  /// @param Sub The custom event subscriber.
122  /// @return Returns a pointer to the created Subscriber slot for the provided subscriber.
123  EventSubscriberSlot* Subscribe(const String& EventName, EventSubscriber* Sub);
124  /// @brief Subscribes a functor object to this event.
125  /// @param EventName The name of the event to subscribe to.
126  /// @param Funct The functor to call when the event is fired.
127  /// @param CleanUpAfter Whether or not to delete the functor when this subscriber is no longer subscribed to any events.
128  /// @return Returns a pointer to the created Subscriber slot for the provided subscriber.
129  EventSubscriberSlot* Subscribe(const String& EventName, FunctorEventSubscriber* Funct, Boole CleanUpAfter);
130  /// @brief Subscribes a C-style function to this event.
131  /// @param EventName The name of the event to subscribe to.
132  /// @param CFunct The C-style function to call when the event is fired.
133  /// @return Returns a pointer to the created Subscriber slot for the provided subscriber.
134  EventSubscriberSlot* Subscribe(const String& EventName, CFunctionSubscriberSlot::SubscriberFunction* CFunct);
135  /// @brief Subscribes a script to this event.
136  /// @param EventName The name of the event to subscribe to.
137  /// @param SubScript The subscribed script to execute when the event is fired.
138  /// @return Returns a pointer to the created Subscriber slot for the provided subscriber.
139  EventSubscriberSlot* Subscribe(const String& EventName, Scripting::iScript* SubScript);
140 
141  ///////////////////////////////////////////////////////////////////////////////
142  // Unsubscribe Methods
143 
144  /// @brief Unsubscribes a single subscriber all events in this publisher.
145  /// @param Subscriber The EventSubscriberSlot (and the subscriber it is holding) to be removed.
146  void Unsubscribe(EventSubscriber* Subscriber);
147  /// @brief Unsubscribes a single subscriber all events in this publisher.
148  /// @param Funct The functor to be removed.
149  void Unsubscribe(FunctorEventSubscriber* Funct);
150  /// @brief Unsubscribes a single subscriber from all events in this publisher.
151  /// @param CFunct The function to be removed.
152  void Unsubscribe(CFunctionSubscriberSlot::SubscriberFunction* CFunct);
153  /// @brief Unsubscribes a single subscriber from all events in this publisher.
154  /// @param SubScript The Script to be removed.
155  void Unsubscribe(Scripting::iScript* SubScript);
156  /// @brief Unsubscribes a single subscriber from all events in this publisher.
157  /// @param SubSlot The EventSubscriberSlot (and the subscriber it is holding) to be removed.
158  void Unsubscribe(EventSubscriberSlot* SubSlot);
159  /// @brief Unsubscribes all subscribers from all events in this publisher.
160  /// @return Returns the number of subscribers removed.
161  Whole UnsubscribeAll();
162 
163  /// @brief Unsubscribes a single subscriber from the named event.
164  /// @param EventName The name of the event to unsubscribe from.
165  /// @param Subscriber The EventSubscriberSlot (and the subscriber it is holding) to be removed.
166  void Unsubscribe(const String& EventName, EventSubscriber* Subscriber);
167  /// @brief Unsubscribes a single subscriber from the named event.
168  /// @param EventName The name of the event to unsubscribe from.
169  /// @param Funct The functor to be removed.
170  void Unsubscribe(const String& EventName, FunctorEventSubscriber* Funct);
171  /// @brief Unsubscribes a single subscriber from the named event.
172  /// @param EventName The name of the event to unsubscribe from.
173  /// @param CFunct The function to be removed.
174  void Unsubscribe(const String& EventName, CFunctionSubscriberSlot::SubscriberFunction* CFunct);
175  /// @brief Unsubscribes a single subscriber from the named event.
176  /// @param EventName The name of the event to unsubscribe from.
177  /// @param SubScript The Script to be removed.
178  void Unsubscribe(const String& EventName, Scripting::iScript* SubScript);
179  /// @brief Unsubscribes a single subscriber from the named event.
180  /// @param EventName The name of the event to unsubscribe from.
181  /// @param SubSlot The EventSubscriberSlot (and the subscriber it is holding) to be removed.
182  void Unsubscribe(const String& EventName, EventSubscriberSlot* SubSlot);
183  /// @brief Unsubscribes all subscribers from the named Event.
184  /// @param EventName The name of the event to unsubscribe from.
185  /// @return Returns the number of subscribers removed.
186  Whole UnsubscribeAll(const String& EventName);
187  };//EventPublisher
188 }//Mezzanine
189 
190 #endif
Basic class definition for functors used by a FunctorSubscriberSlot.
bool Boole
Generally acts a single bit, true or false.
Definition: datatypes.h:173
This class represents a given event that can be subscribed to and/or fired.
Definition: event.h:52
EventContainer Events
A container storing all the Events published by this class by name.
This is a base class for all classes that subscribe to events.
A simple reference counting pointer.
Definition: countedptr.h:70
EventContainer::const_iterator ConstEventIterator
Const Iterator type for Event instances stored by this class.
This implements the exception hiearchy for Mezzanine.
This is the base class for any class that generates and publishes events to subscribers.
The interface for a script.
Definition: script.h:70
void( SubscriberFunction)(EventArgumentsPtr Args)
This is a convenience typedef for a c-style method that accepts EventArguments.
This class represents a slot in an event that can be subscribed to via subscribers, functors, or methods.
Boole MuteEvents
Stores whether or not events will actually be fired when requested.
std::map< String, Event * > EventContainer
Basic container type for Event storage by this class.
#define MEZZ_LIB
Some platforms require special decorations to denote what is exported/imported in a share library...
The bulk of the engine components go in this namspace.
Definition: actor.cpp:56
EventContainer::iterator EventIterator
Iterator type for Event instances stored by this class.
unsigned long Whole
Whole is an unsigned integer, it will be at least 32bits in size.
Definition: datatypes.h:151
std::string String
A datatype used to a series of characters.
Definition: datatypes.h:159