Adonthell 0.4

event_list.h

Go to the documentation of this file.
00001 /*
00002    $Id: event_list.h,v 1.7 2003/02/10 20:01:13 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 /**
00017  * @file   event_list.h
00018  * @author Kai Sterker <kaisterker@linuxgames.com>
00019  * 
00020  * @brief  Declares the event_list class.
00021  * 
00022  */
00023  
00024 
00025 #ifndef EVENT_LIST_H__
00026 #define EVENT_LIST_H__
00027 
00028 #include <vector>
00029 #include "event.h"
00030 
00031 using std::string;
00032 
00033 #ifndef SWIG
00034 /**
00035  * Pointer to a function returning a newly allocated %event
00036  */
00037 typedef event* (*new_event)();
00038 
00039 #endif // SWIG
00040 
00041 /**
00042  * Base class for objects that want to register events. It keeps track of
00043  * all the events an object has registered with the event_handler and can
00044  * automatically unregister them when the object is deallocated.
00045  *
00046  * It also provides the functionality to load and save the states of 
00047  * events in its list.
00048  *
00049  * Objects making use of events should use the %event_list instead of
00050  * handling events themselves.
00051  */ 
00052 class event_list
00053 {
00054 public:
00055     /**
00056      * Constructor - creates an empty, unpaused %event_list
00057      */
00058     event_list ();
00059     
00060     /**
00061      * Destructor - unregisters and deletes all events owned by this list.
00062      */ 
00063     virtual ~event_list ();
00064 
00065     /**
00066      * Unregisters and deletes all events owned by this list.
00067      */ 
00068     void clear ();
00069 
00070     /**
00071      * @name List Operations
00072      */
00073     //@{
00074     /** 
00075      * Adds an %event to this list. The %event will be
00076      * registered with the %event_handler and the list will then
00077      * take care of it's deletion.
00078      * 
00079      * @param ev pointer to the %event to add.
00080      */
00081     void add_event (event* ev);
00082 
00083     /**
00084      * Removes an %event from the list. This is usually called when an
00085      * %event is destroyed.
00086      *
00087      * @param ev pointer to the %event to remove.
00088      */
00089     void remove_event (event* ev);
00090     
00091     /**
00092      * Try to retrieve the %event with given id from the list.
00093      *
00094      * @return a pointer to the %event, or \b NULL if it's not in the list.
00095      */
00096     event *get_event (const string & id);
00097     //@}
00098     
00099     /**
00100      * @name Pausing / Resuming execution
00101      */
00102     //@{
00103     /**
00104      * Disable any events associated with this %event_list. This will
00105      * effectively stop all actions of the %object the %event_list
00106      * belongs to, e.g. a NPC.
00107      */
00108     void pause ();
00109     
00110     /**
00111      * Re-enable the events associated with the %event_list, thus
00112      * 'awaking' the %object to life again. 
00113      */
00114     void resume ();
00115 
00116     /**
00117      * Check whether the %event list is temporarily disabled or not.
00118      * @return \b true if it is paused, \b false otherwise.                     
00119      */
00120     bool is_paused () const
00121     {
00122         return Paused;
00123     }
00124     //@}
00125     
00126 #ifndef SWIG    
00127     /**
00128      * Register an %event for loading. Before the %event_list can load
00129      * an %event from file, it needs a callback function that returns
00130      * a new instance of the %event of the given type.
00131      *
00132      * @param type the type of the %event to register
00133      * @param e a callback returning a new instance of an %event of the 
00134      *      given type.
00135      *
00136      * @sa get_state ()
00137      */
00138     static void register_event (u_int8 type, new_event e);
00139 #endif // SWIG
00140 
00141     /**
00142      * @name Loading / Saving
00143      */
00144     //@{
00145     /** 
00146      * Save the %event_list to a file.
00147      * 
00148      * @param out file where to save the %event_list.
00149      */ 
00150     void put_state (ogzstream& out) const;
00151     
00152     /** 
00153      * Loads the %event_list from a file and registers all loaded events.
00154      * @warning Before the %event_list can load an %event from file, it needs
00155      *     a callback function that returns a new instance of that %event.
00156      * 
00157      * @param in file to load the %event_list from.
00158      * 
00159      * @return \e true if the %event_list was loaded successfully, \e false
00160      *     otherwise.
00161      * @sa register_event ()
00162      */
00163     bool get_state (igzstream& in);
00164     //@}
00165 
00166 #ifndef SWIG
00167 protected:
00168     /**
00169      * List of events.
00170      */ 
00171     mutable std::vector<event*> Events;
00172 
00173 private:
00174     /**
00175      * Whether this %event_list is paused or not. Events that are added
00176      * to a paused list will be paused as well.
00177      */
00178     bool Paused;
00179 
00180     /**
00181      * Array with callbacks that return a newly allocated instance of an %event.
00182      * The event's type is the postion of the according callback in the array.
00183      */
00184     static new_event instanciate_event[MAX_EVENTS];
00185 #endif // SWIG
00186 };
00187 
00188 #ifndef SWIG
00189 /**
00190  * Registers an %event with the %event_list, allowing it to load this %event
00191  * without knowing about it at compile time.
00192  */
00193 #define REGISTER_EVENT(type,evt)\
00194     event_list::register_event (type, (new_event) &new_ ## evt);
00195 
00196 /**
00197  * A function that returns a new instance of an %event.
00198  */
00199 #define NEW_EVENT(evt)\
00200     event* new_ ## evt () { return (event*) new evt; }
00201 
00202 #endif // SWIG
00203 #endif // EVENT_LIST_H__