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