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