Adonthell  0.4
event_list.h
Go to the documentation of this file.
1 /*
2  Copyright (C) 2000/2001/2002/2003 Kai Sterker <kai.sterker@gmail.com>
3  Part of the Adonthell Project <http://adonthell.nongnu.org>
4 
5  Adonthell is free software; you can redistribute it and/or modify
6  it under the terms of the GNU General Public License as published by
7  the Free Software Foundation; either version 2 of the License, or
8  (at your option) any later version.
9 
10  Adonthell is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  GNU General Public License for more details.
14 
15  You should have received a copy of the GNU General Public License
16  along with Adonthell. If not, see <http://www.gnu.org/licenses/>.
17 */
18 
19 
20 /**
21  * @file event_list.h
22  * @author Kai Sterker <kai.sterker@gmail.com>
23  *
24  * @brief Declares the event_list class.
25  *
26  */
27 
28 
29 #ifndef EVENT_LIST_H__
30 #define EVENT_LIST_H__
31 
32 #include <vector>
33 #include "event.h"
34 
35 using std::string;
36 
37 #ifndef SWIG
38 /**
39  * Pointer to a function returning a newly allocated %event
40  */
41 typedef event* (*new_event)();
42 
43 #endif // SWIG
44 
45 /**
46  * Base class for objects that want to register events. It keeps track of
47  * all the events an object has registered with the event_handler and can
48  * automatically unregister them when the object is deallocated.
49  *
50  * It also provides the functionality to load and save the states of
51  * events in its list.
52  *
53  * Objects making use of events should use the %event_list instead of
54  * handling events themselves.
55  */
57 {
58 public:
59  /**
60  * Constructor - creates an empty, unpaused %event_list
61  */
62  event_list ();
63 
64  /**
65  * Destructor - unregisters and deletes all events owned by this list.
66  */
67  virtual ~event_list ();
68 
69  /**
70  * Unregisters and deletes all events owned by this list.
71  */
72  void clear ();
73 
74  /**
75  * @name List Operations
76  */
77  //@{
78  /**
79  * Adds an %event to this list. The %event will be
80  * registered with the %event_handler and the list will then
81  * take care of it's deletion.
82  *
83  * @param ev pointer to the %event to add.
84  */
85  void add_event (event* ev);
86 
87  /**
88  * Removes an %event from the list. This is usually called when an
89  * %event is destroyed.
90  *
91  * @param ev pointer to the %event to remove.
92  */
93  void remove_event (event* ev);
94 
95  /**
96  * Try to retrieve the %event with given id from the list.
97  *
98  * @return a pointer to the %event, or \b NULL if it's not in the list.
99  */
100  event *get_event (const string & id);
101  //@}
102 
103  /**
104  * @name Pausing / Resuming execution
105  */
106  //@{
107  /**
108  * Disable any events associated with this %event_list. This will
109  * effectively stop all actions of the %object the %event_list
110  * belongs to, e.g. a NPC.
111  */
112  void pause ();
113 
114  /**
115  * Re-enable the events associated with the %event_list, thus
116  * 'awaking' the %object to life again.
117  */
118  void resume ();
119 
120  /**
121  * Check whether the %event list is temporarily disabled or not.
122  * @return \b true if it is paused, \b false otherwise.
123  */
124  bool is_paused () const
125  {
126  return Paused;
127  }
128  //@}
129 
130 #ifndef SWIG
131  /**
132  * Register an %event for loading. Before the %event_list can load
133  * an %event from file, it needs a callback function that returns
134  * a new instance of the %event of the given type.
135  *
136  * @param type the type of the %event to register
137  * @param e a callback returning a new instance of an %event of the
138  * given type.
139  *
140  * @sa get_state ()
141  */
142  static void register_event (u_int8 type, new_event e);
143 #endif // SWIG
144 
145  /**
146  * @name Loading / Saving
147  */
148  //@{
149  /**
150  * Save the %event_list to a file.
151  *
152  * @param out file where to save the %event_list.
153  */
154  void put_state (ogzstream& out) const;
155 
156  /**
157  * Loads the %event_list from a file and registers all loaded events.
158  * @warning Before the %event_list can load an %event from file, it needs
159  * a callback function that returns a new instance of that %event.
160  *
161  * @param in file to load the %event_list from.
162  *
163  * @return \e true if the %event_list was loaded successfully, \e false
164  * otherwise.
165  * @sa register_event ()
166  */
167  bool get_state (igzstream& in);
168  //@}
169 
170 #ifndef SWIG
171 protected:
172  /**
173  * List of events.
174  */
175  mutable std::vector<event*> Events;
176 
177 private:
178  /**
179  * Whether this %event_list is paused or not. Events that are added
180  * to a paused list will be paused as well.
181  */
182  bool Paused;
183 
184  /**
185  * Array with callbacks that return a newly allocated instance of an %event.
186  * The event's type is the postion of the according callback in the array.
187  */
188  static new_event instanciate_event[MAX_EVENTS];
189 #endif // SWIG
190 };
191 
192 #ifndef SWIG
193 /**
194  * Registers an %event with the %event_list, allowing it to load this %event
195  * without knowing about it at compile time.
196  */
197 #define REGISTER_EVENT(type,evt)\
198  event_list::register_event (type, (new_event) &new_ ## evt);
199 
200 /**
201  * A function that returns a new instance of an %event.
202  */
203 #define NEW_EVENT(evt)\
204  event* new_ ## evt () { return (event*) new evt; }
205 
206 #endif // SWIG
207 #endif // EVENT_LIST_H__
event_list::clear
void clear()
Unregisters and deletes all events owned by this list.
Definition: event_list.cc:48
new_event
event *(* new_event)()
Pointer to a function returning a newly allocated event.
Definition: event_list.h:41
event_list::is_paused
bool is_paused() const
Check whether the event list is temporarily disabled or not.
Definition: event_list.h:124
igzstream
Class to read data from a Gzip compressed file.
Definition: fileops.h:135
event_list
Base class for objects that want to register events.
Definition: event_list.h:56
ogzstream
Class to write data from a Gzip compressed file.
Definition: fileops.h:227
event_list::add_event
void add_event(event *ev)
Adds an event to this list.
Definition: event_list.cc:62
u_int8
#define u_int8
8 bits long unsigned integer
Definition: types.h:35
event_list::get_state
bool get_state(igzstream &in)
Loads the event_list from a file and registers all loaded events.
Definition: event_list.cc:133
event_list::event_list
event_list()
Constructor - creates an empty, unpaused event_list.
Definition: event_list.cc:36
event_list::resume
void resume()
Re-enable the events associated with the event_list, thus 'awaking' the object to life again.
Definition: event_list.cc:106
event_list::Events
std::vector< event * > Events
List of events.
Definition: event_list.h:175
event_list::~event_list
virtual ~event_list()
Destructor - unregisters and deletes all events owned by this list.
Definition: event_list.cc:42
event_list::get_event
event * get_event(const string &id)
Try to retrieve the event with given id from the list.
Definition: event_list.cc:87
event.h
Declares the event class.
event
Base class for events.
Definition: event.h:75
event_list::remove_event
void remove_event(event *ev)
Removes an event from the list.
Definition: event_list.cc:75
event_list::register_event
static void register_event(u_int8 type, new_event e)
Register an event for loading.
Definition: event_list.cc:114
event_list::pause
void pause()
Disable any events associated with this event_list.
Definition: event_list.cc:98
event_list::put_state
void put_state(ogzstream &out) const
Save the event_list to a file.
Definition: event_list.cc:121