Adonthell  0.4
event.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  * @file event.h
21  * @author Kai Sterker <kai.sterker@gmail.com>
22  *
23  * @brief Declares the %event class.
24  *
25  */
26 
27 #ifndef EVENT_H__
28 #define EVENT_H__
29 
30 #include "callback.h"
31 #include "py_object.h"
32 #include "py_callback.h"
33 
34 class event_list;
35 
36 /**
37  * Directory where %event scripts reside.
38  */
39 #define EVENTS_DIR "game_events."
40 
41 #ifndef SWIG
42 /**
43  * Available %event types.
44  */
45 enum
46 {
47  ENTER_EVENT = 0, // Characters reach a new tile
48  LEAVE_EVENT = 1, // Characters leave a tile
49  TIME_EVENT = 2, // Certain point in gametime reached
50  ACTION_EVENT = 3, // Character "acts" on a square
51  MAX_EVENTS = 4
52 };
53 
54 /**
55  * Available 'actions', i.e. what happens when the event occurs
56  */
57 enum
58 {
59  ACTION_NOTHING = 0,
60  ACTION_SCRIPT = 1,
61  ACTION_PYFUNC = 2,
62  ACTION_CPPFUNC = 3
63 };
64 #endif // SWIG
65 
66 /**
67  * Base class for events. You can create your own %event types that can
68  * be handled by the event_list and event_handler by inheriting from
69  * this class.
70  *
71  * Events are used to notify when certain things happen during the game.
72  * They may either execute the "run" method of an exclusive %python script
73  * or a simple %python callback defined elsewhere.
74  */
75 class event
76 {
77 public:
78  /**
79  * Constructor. Needs to be called by any derived class!
80  */
81  event ();
82 
83  /**
84  * Destructor.
85  */
86  virtual ~event ();
87 
88  /**
89  * Cleanup. Clears script and its arguments.
90  */
91  void clear ();
92 
93  /**
94  * @name Member access
95  */
96  //@{
97  /**
98  * Get the event's type.
99  *
100  * @return type of the %event
101  */
102  u_int8 type () const
103  {
104  return Type;
105  }
106 
107  /**
108  * Get the event's id.
109  *
110  * @return id of the %event.
111  */
112  const string & id () const
113  {
114  return Id;
115  }
116 
117  /**
118  * Assign an id to the %event, so it may be retrieved from an
119  * event_list later on, without having a pointer to it.
120  *
121  * @param id a string to identify the %event.
122  */
123  void set_id (const string & id)
124  {
125  Id = id;
126  }
127 
128  /**
129  * Test whether the %event is registered with the %event handler.
130  *
131  * @return \c true if this is the case, \c false otherwise.
132  */
133  bool registered () const
134  {
135  return Registered;
136  }
137 #ifndef SWIG
138  /**
139  * Set whether the %event is registered with the %event handler.
140  *
141  * @param reg Set to \c true if it is, to \c false otherwise.
142  */
143  void set_registered (bool reg)
144  {
145  Registered = reg;
146  }
147 
148  /**
149  * Tell the whether it is kept in an %event_list.
150  *
151  * @param list The %event_list this event has been added to.
152  */
153  void set_list (event_list *list);
154 #endif // SWIG
155  /**
156  * Return whether this event should be repeated.
157  *
158  * @return the number of times this event should be repeated or
159  * -1 in case it should be repeated unlimited times.
160  */
161  s_int32 repeat () const
162  {
163  return Repeat;
164  }
165 
166  /**
167  * Set whether this event should be repeated. A number greater than 0
168  * will execute the event that many times, a number less than 0 will
169  * repeat the event forever. A number equal to 0 won't repeat the event.
170  *
171  * @param count How often the event should be repeated.
172  */
173  void set_repeat (s_int32 count)
174  {
175  Repeat = count;
176  }
177  //@}
178 
179  /**
180  * @name Event Handling
181  */
182  //@{
183 
184  /**
185  * Execute the associated python script or callback.
186  *
187  * @param evnt The %event that triggered the execution.
188  *
189  * @return The number of times the %event needs to be repeated.
190  */
191  virtual s_int32 execute (const event* evnt) = 0;
192 
193  /**
194  * Compare two events for equality.
195  *
196  * @param evnt pointer to the %event to compare with.
197  * @return \e true if the events are equal, \e false otherwise.
198  */
199  virtual bool equals (const event* evnt) = 0;
200 
201  //@}
202 
203  /**
204  * Sets a script to be executed whenever the event occurs.
205  *
206  * @param filename filename of the script to set.
207  * @param args The arguments to pass to the script's constructor
208  */
209  void set_script (string filename, PyObject * args = NULL);
210 
211  /**
212  * Sets a python function/method to be executed whenever the
213  * %event occurs.
214  *
215  * @warning the callback won't be saved with the %event. It
216  * must be restored by the event's owner.
217  *
218  * @param callback The function or method to call.
219  * @param args Additional arguments to pass to the callback.
220  */
221  void set_callback (PyObject *callback, PyObject *args = NULL);
222 
223 #ifndef SWIG
224  /**
225  * Sets a C function/C++ method to be executed whenever the
226  * %event occurs.
227  *
228  * @warning the callback won't be saved with the %event. It
229  * must be restored by the event's owner.
230  *
231  * @param callback The callback, a function with no arguments
232  * returning void
233  */
234  void set_callback (const Functor0 & callback);
235 #endif // SWIG
236 
237  /**
238  * @name Pausing / Resuming execution
239  */
240  //@{
241 
242  /**
243  * Disable the %event temporarily. As long as it in this state, the
244  * event will neither be executed, nor will its repeat-count change.
245  * As long as the %event is paused, it will be removed from its
246  * %event handler.
247  */
248  virtual void pause ();
249 
250  /**
251  * Re-enable an %event that has been paused. Re-registers it with
252  * its %event handler.
253  */
254  virtual void resume ();
255 
256  /**
257  * Check whether the %event is temporarily disabled or not.
258  * @return \b true if it is paused, \b false otherwise.
259  */
260  bool is_paused () const
261  {
262  return Paused;
263  }
264  //@}
265 
266  /**
267  * @name Loading / Saving
268  */
269  //@{
270 
271  /**
272  * Saves the basic %event %data (such as the type or script data)
273  * to a file. Call this method from the derived class.
274  *
275  * @param out file where to save the %event.
276  */
277  virtual void put_state (ogzstream& out) const;
278 
279  /**
280  * Loads the basic %event %date from a file. Call this method from
281  * the derived class.
282  *
283  * @param in file to load the %event from.
284  * @return \e true if the %event could be loaded, \e false otherwise
285  */
286  virtual bool get_state (igzstream& in);
287 
288  //@}
289 
290 protected:
291 #ifndef SWIG
292  /**
293  * Decrease the event's repeat count and return the number of repeats
294  * left. If the repeat-count reaches 0, the %event will be destroyed.
295  *
296  * @return the number of times this event should be repeated or
297  * -1 in case it should be repeated unlimited times.
298  */
299  s_int32 do_repeat ();
300 
301  /**
302  * @name Basic Event Data
303  */
304  //@{
305 
306  /**
307  * Event type - see enum above.
308  */
310 
311  /**
312  * (Optional) Id of the event
313  */
314  string Id;
315 
316  /**
317  * What happens if the event occurs - see enum above.
318  */
320 
321  /**
322  * Whether the %event is registered with the %event handler.
323  */
325 
326  /**
327  * Whether the %event temporarily disabled or not.
328  */
329  bool Paused;
330 
331  /**
332  * Defines how often the %event should be repeated. <b>0</b> means
333  * never, <b>-1</b> means infinitely and <b>n</b> (n > 0) means
334  * exactly n times.
335  */
337 
338  /**
339  * The Python script accociated with this %event. It is executed
340  * whenever the %event gets triggered.
341  */
343 
344  /**
345  * The arguments passed to the script. This needs to be a PyTuple
346  * or NULL if there are no arguments.
347  */
348  PyObject *Args;
349 
350  /**
351  * Python callback that may be executed instead of the script.
352  */
354 
355  /**
356  * C++ callback that may be executed when the %event gets triggered.
357  */
358  Functor0 Callback;
359 
360  /**
361  * The event_list this event is kept in.
362  */
364  //@}
365 #endif // SWIG
366 };
367 
368 #endif // EVENT_H__
Class to write data from a Gzip compressed file.
Definition: fileops.h:227
const string & id() const
Get the event&#39;s id.
Definition: event.h:112
#define s_int32
32 bits long signed integer
Definition: types.h:50
Class to read data from a Gzip compressed file.
Definition: fileops.h:135
u_int8 Action
What happens if the event occurs - see enum above.
Definition: event.h:319
u_int8 type() const
Get the event&#39;s type.
Definition: event.h:102
PyObject * Args
The arguments passed to the script.
Definition: event.h:348
Python object class.
Definition: py_object.h:45
void set_callback(PyObject *callback, PyObject *args=NULL)
Sets a python function/method to be executed whenever the event occurs.
Definition: event.cc:118
virtual void pause()
Disable the event temporarily.
Definition: event.cc:227
void set_script(string filename, PyObject *args=NULL)
Sets a script to be executed whenever the event occurs.
Definition: event.cc:87
Base class for events.
Definition: event.h:75
Declares the py_callback class.
virtual void put_state(ogzstream &out) const
Saves the basic event data (such as the type or script data) to a file.
Definition: event.cc:141
s_int32 Repeat
Defines how often the event should be repeated.
Definition: event.h:336
#define u_int8
8 bits long unsigned integer
Definition: types.h:35
bool Registered
Whether the event is registered with the event handler.
Definition: event.h:324
virtual bool get_state(igzstream &in)
Loads the basic event date from a file.
Definition: event.cc:178
virtual ~event()
Destructor.
Definition: event.cc:44
bool Paused
Whether the event temporarily disabled or not.
Definition: event.h:329
void set_repeat(s_int32 count)
Set whether this event should be repeated.
Definition: event.h:173
s_int32 repeat() const
Return whether this event should be repeated.
Definition: event.h:161
u_int8 Type
Event type - see enum above.
Definition: event.h:309
void set_registered(bool reg)
Set whether the event is registered with the event handler.
Definition: event.h:143
virtual void resume()
Re-enable an event that has been paused.
Definition: event.cc:234
py_callback * PyFunc
Python callback that may be executed instead of the script.
Definition: event.h:353
virtual s_int32 execute(const event *evnt)=0
Execute the associated python script or callback.
py_object * Script
The Python script accociated with this event.
Definition: event.h:342
void set_list(event_list *list)
Tell the whether it is kept in an event_list.
Definition: event.cc:221
Functor0 Callback
C++ callback that may be executed when the event gets triggered.
Definition: event.h:358
Declares the py_object class.
s_int32 do_repeat()
Decrease the event&#39;s repeat count and return the number of repeats left.
Definition: event.cc:241
Stores the C++ <-> Python callback binding.
Definition: py_callback.h:41
string Id
(Optional) Id of the event
Definition: event.h:314
Base class for objects that want to register events.
Definition: event_list.h:56
void clear()
Cleanup.
Definition: event.cc:56
bool registered() const
Test whether the event is registered with the event handler.
Definition: event.h:133
event_list * List
The event_list this event is kept in.
Definition: event.h:363
bool is_paused() const
Check whether the event is temporarily disabled or not.
Definition: event.h:260
event()
Constructor.
Definition: event.cc:30
virtual bool equals(const event *evnt)=0
Compare two events for equality.
void set_id(const string &id)
Assign an id to the event, so it may be retrieved from an event_list later on, without having a point...
Definition: event.h:123