00001 /* 00002 $Id: time_event.h,v 1.8 2003/02/23 23:14:34 ksterker Exp $ 00003 00004 Copyright (C) 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 time_event.h 00017 * 00018 * @author Kai Sterker 00019 * @brief Declares the time_event class. 00020 */ 00021 00022 #ifndef TIME_EVENT_H__ 00023 #define TIME_EVENT_H__ 00024 00025 #include "event.h" 00026 00027 /** 00028 * The time %event executes the attached script or callback at a certain 00029 * point in %game-time. This point can either be relative to the current 00030 * time, or absolute in time. In any case, this point should be in the 00031 * future. Time %event with an alarm time in the past will be triggered 00032 * at once. 00033 */ 00034 class time_event : public event 00035 { 00036 public: 00037 /** 00038 * @name Initialization 00039 */ 00040 //@{ 00041 00042 /** 00043 * Create a new time %event. 00044 * 00045 * @param time The time when the %event should be raised. The string 00046 * specifies week, day, hour, minute and 1/10 minute in the format 00047 * "<number>w<number>d<number>h<number>m<number>t". If a number is 00048 * 0, it can be omitted. 00049 * @param absolute Decides whether the given time is relative from now 00050 * on, or an absolute time 00051 */ 00052 time_event (const string & time, bool absolute = false); 00053 00054 #ifndef SWIG 00055 /** 00056 * Standard constructor. 00057 */ 00058 time_event () : event () 00059 { 00060 Type = TIME_EVENT; 00061 Repeat = 1; 00062 } 00063 00064 /** 00065 * Create a new time %event. This constructor is primarily used for 00066 * raising time events. 00067 * 00068 * @param time The "alarm" time in %gametime minutes. 00069 */ 00070 time_event (const u_int32 & time) : event () 00071 { 00072 Type = TIME_EVENT; 00073 Time = time; 00074 Repeat = 1; 00075 } 00076 #endif // SWIG 00077 00078 /** 00079 * Set whether the %event should be raised at fixed intervals. 00080 * 00081 * @param interval The time between two occurences of the %event. 00082 * @param count The number of times the %event shall be repeated. 00083 * Specify -1 to repeat it an unlimited number of times. 00084 */ 00085 void set_repeat (const string & interval, s_int32 count = -1); 00086 //@} 00087 00088 /** 00089 * @name Event Handling 00090 */ 00091 //@{ 00092 00093 /** 00094 * Compare two time events for equality. 00095 * 00096 * @param evnt The time event to compare this to. 00097 * @return <b>True</b> if the two events equal, <b>false</b> otherwise. 00098 */ 00099 bool equals (const event * evnt) 00100 { 00101 time_event *e = (time_event *) evnt; 00102 return Time <= e->time (); 00103 } 00104 00105 /** 00106 * Executes the script associated with this time %event. If the 00107 * event repeats it is re-registered with the %event handler. 00108 * 00109 * @param evnt The %event that triggered this time %event. 00110 * 00111 * @return The number of times the %event needs to be repeated. 00112 */ 00113 s_int32 execute (const event * evnt); 00114 //@} 00115 00116 /** 00117 * @name Loading / Saving 00118 */ 00119 //@{ 00120 00121 /** 00122 * Saves the basic %event %data (such as the type or script data) 00123 * to a file. 00124 * 00125 * @param out file where to save the %event. 00126 */ 00127 void put_state (ogzstream& out) const; 00128 00129 /** 00130 * Loads the basic %event %date from a file. 00131 * 00132 * @param in file to load the %event from. 00133 * @return \e true if the %event could be loaded, \e false otherwise 00134 */ 00135 bool get_state (igzstream& in); 00136 00137 //@} 00138 00139 /** 00140 * @name Pausing / Resuming execution 00141 */ 00142 //@{ 00143 00144 /** 00145 * Disable the %event temporarily. As long as it in this state, the 00146 * event will neither be executed, nor will its repeat-count change. 00147 * 00148 * The alarm time of relative time events will be prolongued be the 00149 * time the event was paused. Absolute events will only be deferred 00150 * until they are resumed. 00151 */ 00152 void pause (); 00153 00154 /** 00155 * Re-enable an %event that has been paused. 00156 * 00157 * Absolute events that are past their alarm time are executed at once. 00158 */ 00159 void resume (); 00160 00161 //@} 00162 00163 /** 00164 * Get the event's "alarm" time, i.e. the time when it needs to be 00165 * executed. 00166 * 00167 * @return the "alarm" time in 1/10 %gametime minutes. 00168 */ 00169 u_int32 time () const 00170 { 00171 return Time; 00172 } 00173 00174 private: 00175 #ifndef SWIG 00176 // the time when the event shall be triggered 00177 u_int32 Time; 00178 00179 // time that lies between two occurances of the event 00180 u_int32 Interval; 00181 00182 // whether the alarm time is relative or absolute 00183 bool Absolute; 00184 #endif // SWIG 00185 }; 00186 00187 #endif // TIME_EVENT_H__