Adonthell 0.4
|
00001 /* 00002 $Id: event.h,v 1.34 2003/02/23 23:14:34 ksterker Exp $ 00003 00004 Copyright (C) 2000/2001/2002/2003 Kai Sterker <kaisterker@linuxgames.com> 00005 Part of the Adonthell Project http://adonthell.linuxgames.com 00006 00007 This program is free software; you can redistribute it and/or modify 00008 it under the terms of the GNU General Public License. 00009 This program is distributed in the hope that it will be useful, 00010 but WITHOUT ANY WARRANTY. 00011 00012 See the COPYING file for more details. 00013 */ 00014 00015 /** 00016 * @file event.h 00017 * @author Kai Sterker <kaisterker@linuxgames.com> 00018 * 00019 * @brief Declares the %event class. 00020 * 00021 */ 00022 00023 #ifndef EVENT_H__ 00024 #define EVENT_H__ 00025 00026 #include "callback.h" 00027 #include "py_object.h" 00028 #include "py_callback.h" 00029 00030 class event_list; 00031 00032 /** 00033 * Directory where %event scripts reside. 00034 */ 00035 #define EVENTS_DIR "game_events." 00036 00037 #ifndef SWIG 00038 /** 00039 * Available %event types. 00040 */ 00041 enum 00042 { 00043 ENTER_EVENT = 0, // Characters reach a new tile 00044 LEAVE_EVENT = 1, // Characters leave a tile 00045 TIME_EVENT = 2, // Certain point in gametime reached 00046 ACTION_EVENT = 3, // Character "acts" on a square 00047 MAX_EVENTS = 4 00048 }; 00049 00050 /** 00051 * Available 'actions', i.e. what happens when the event occurs 00052 */ 00053 enum 00054 { 00055 ACTION_NOTHING = 0, 00056 ACTION_SCRIPT = 1, 00057 ACTION_PYFUNC = 2, 00058 ACTION_CPPFUNC = 3 00059 }; 00060 #endif // SWIG 00061 00062 /** 00063 * Base class for events. You can create your own %event types that can 00064 * be handled by the event_list and event_handler by inheriting from 00065 * this class. 00066 * 00067 * Events are used to notify when certain things happen during the game. 00068 * They may either execute the "run" method of an exclusive %python script 00069 * or a simple %python callback defined elsewhere. 00070 */ 00071 class event 00072 { 00073 public: 00074 /** 00075 * Constructor. Needs to be called by any derived class! 00076 */ 00077 event (); 00078 00079 /** 00080 * Destructor. 00081 */ 00082 virtual ~event (); 00083 00084 /** 00085 * Cleanup. Clears script and its arguments. 00086 */ 00087 void clear (); 00088 00089 /** 00090 * @name Member access 00091 */ 00092 //@{ 00093 /** 00094 * Get the event's type. 00095 * 00096 * @return type of the %event 00097 */ 00098 u_int8 type () const 00099 { 00100 return Type; 00101 } 00102 00103 /** 00104 * Get the event's id. 00105 * 00106 * @return id of the %event. 00107 */ 00108 const string & id () const 00109 { 00110 return Id; 00111 } 00112 00113 /** 00114 * Assign an id to the %event, so it may be retrieved from an 00115 * event_list later on, without having a pointer to it. 00116 * 00117 * @param id a string to identify the %event. 00118 */ 00119 void set_id (const string & id) 00120 { 00121 Id = id; 00122 } 00123 00124 /** 00125 * Test whether the %event is registered with the %event handler. 00126 * 00127 * @return \c true if this is the case, \c false otherwise. 00128 */ 00129 bool registered () const 00130 { 00131 return Registered; 00132 } 00133 #ifndef SWIG 00134 /** 00135 * Set whether the %event is registered with the %event handler. 00136 * 00137 * @param reg Set to \c true if it is, to \c false otherwise. 00138 */ 00139 void set_registered (bool reg) 00140 { 00141 Registered = reg; 00142 } 00143 00144 /** 00145 * Tell the whether it is kept in an %event_list. 00146 * 00147 * @param list The %event_list this event has been added to. 00148 */ 00149 void set_list (event_list *list); 00150 #endif // SWIG 00151 /** 00152 * Return whether this event should be repeated. 00153 * 00154 * @return the number of times this event should be repeated or 00155 * -1 in case it should be repeated unlimited times. 00156 */ 00157 s_int32 repeat () const 00158 { 00159 return Repeat; 00160 } 00161 00162 /** 00163 * Set whether this event should be repeated. A number greater than 0 00164 * will execute the event that many times, a number less than 0 will 00165 * repeat the event forever. A number equal to 0 won't repeat the event. 00166 * 00167 * @param count How often the event should be repeated. 00168 */ 00169 void set_repeat (s_int32 count) 00170 { 00171 Repeat = count; 00172 } 00173 //@} 00174 00175 /** 00176 * @name Event Handling 00177 */ 00178 //@{ 00179 00180 /** 00181 * Execute the associated python script or callback. 00182 * 00183 * @param evnt The %event that triggered the execution. 00184 * 00185 * @return The number of times the %event needs to be repeated. 00186 */ 00187 virtual s_int32 execute (const event* evnt) = 0; 00188 00189 /** 00190 * Compare two events for equality. 00191 * 00192 * @param evnt pointer to the %event to compare with. 00193 * @return \e true if the events are equal, \e false otherwise. 00194 */ 00195 virtual bool equals (const event* evnt) = 0; 00196 00197 //@} 00198 00199 /** 00200 * Sets a script to be executed whenever the event occurs. 00201 * 00202 * @param filename filename of the script to set. 00203 * @param args The arguments to pass to the script's constructor 00204 */ 00205 void set_script (string filename, PyObject * args = NULL); 00206 00207 /** 00208 * Sets a python function/method to be executed whenever the 00209 * %event occurs. 00210 * 00211 * @warning the callback won't be saved with the %event. It 00212 * must be restored by the event's owner. 00213 * 00214 * @param callback The function or method to call. 00215 * @param args Additional arguments to pass to the callback. 00216 */ 00217 void set_callback (PyObject *callback, PyObject *args = NULL); 00218 00219 #ifndef SWIG 00220 /** 00221 * Sets a C function/C++ method to be executed whenever the 00222 * %event occurs. 00223 * 00224 * @warning the callback won't be saved with the %event. It 00225 * must be restored by the event's owner. 00226 * 00227 * @param callback The callback, a function with no arguments 00228 * returning void 00229 */ 00230 void set_callback (const Functor0 & callback); 00231 #endif // SWIG 00232 00233 /** 00234 * @name Pausing / Resuming execution 00235 */ 00236 //@{ 00237 00238 /** 00239 * Disable the %event temporarily. As long as it in this state, the 00240 * event will neither be executed, nor will its repeat-count change. 00241 * As long as the %event is paused, it will be removed from its 00242 * %event handler. 00243 */ 00244 virtual void pause (); 00245 00246 /** 00247 * Re-enable an %event that has been paused. Re-registers it with 00248 * its %event handler. 00249 */ 00250 virtual void resume (); 00251 00252 /** 00253 * Check whether the %event is temporarily disabled or not. 00254 * @return \b true if it is paused, \b false otherwise. 00255 */ 00256 bool is_paused () const 00257 { 00258 return Paused; 00259 } 00260 //@} 00261 00262 /** 00263 * @name Loading / Saving 00264 */ 00265 //@{ 00266 00267 /** 00268 * Saves the basic %event %data (such as the type or script data) 00269 * to a file. Call this method from the derived class. 00270 * 00271 * @param out file where to save the %event. 00272 */ 00273 virtual void put_state (ogzstream& out) const; 00274 00275 /** 00276 * Loads the basic %event %date from a file. Call this method from 00277 * the derived class. 00278 * 00279 * @param in file to load the %event from. 00280 * @return \e true if the %event could be loaded, \e false otherwise 00281 */ 00282 virtual bool get_state (igzstream& in); 00283 00284 //@} 00285 00286 protected: 00287 #ifndef SWIG 00288 /** 00289 * Decrease the event's repeat count and return the number of repeats 00290 * left. If the repeat-count reaches 0, the %event will be destroyed. 00291 * 00292 * @return the number of times this event should be repeated or 00293 * -1 in case it should be repeated unlimited times. 00294 */ 00295 s_int32 do_repeat (); 00296 00297 /** 00298 * @name Basic Event Data 00299 */ 00300 //@{ 00301 00302 /** 00303 * Event type - see enum above. 00304 */ 00305 u_int8 Type; 00306 00307 /** 00308 * (Optional) Id of the event 00309 */ 00310 string Id; 00311 00312 /** 00313 * What happens if the event occurs - see enum above. 00314 */ 00315 u_int8 Action; 00316 00317 /** 00318 * Whether the %event is registered with the %event handler. 00319 */ 00320 bool Registered; 00321 00322 /** 00323 * Whether the %event temporarily disabled or not. 00324 */ 00325 bool Paused; 00326 00327 /** 00328 * Defines how often the %event should be repeated. <b>0</b> means 00329 * never, <b>-1</b> means infinitely and <b>n</b> (n > 0) means 00330 * exactly n times. 00331 */ 00332 s_int32 Repeat; 00333 00334 /** 00335 * The Python script accociated with this %event. It is executed 00336 * whenever the %event gets triggered. 00337 */ 00338 py_object *Script; 00339 00340 /** 00341 * The arguments passed to the script. This needs to be a PyTuple 00342 * or NULL if there are no arguments. 00343 */ 00344 PyObject *Args; 00345 00346 /** 00347 * Python callback that may be executed instead of the script. 00348 */ 00349 py_callback *PyFunc; 00350 00351 /** 00352 * C++ callback that may be executed when the %event gets triggered. 00353 */ 00354 Functor0 Callback; 00355 00356 /** 00357 * The event_list this event is kept in. 00358 */ 00359 event_list *List; 00360 //@} 00361 #endif // SWIG 00362 }; 00363 00364 #endif // EVENT_H__