• Main Page
  • Related Pages
  • Classes
  • Files
  • File List
  • File Members

event.h

Go to the documentation of this file.
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__

Generated on Fri Mar 18 2011 for Adonthell by  doxygen 1.7.1