Adonthell  0.4
time_event.h
Go to the documentation of this file.
1 /*
2  Copyright (C) 2002/2003 Kai Sterker <kai.sterker@gmail.com>
3  Part of the Adonthell Project <http://adonthell.nongnu.org>
4 
5  Adonthell is free software; you can redistribute it and/or modify
6  it under the terms of the GNU General Public License as published by
7  the Free Software Foundation; either version 2 of the License, or
8  (at your option) any later version.
9 
10  Adonthell is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  GNU General Public License for more details.
14 
15  You should have received a copy of the GNU General Public License
16  along with Adonthell. If not, see <http://www.gnu.org/licenses/>.
17 */
18 
19 /**
20  * @file time_event.h
21  *
22  * @author Kai Sterker
23  * @brief Declares the time_event class.
24  */
25 
26 #ifndef TIME_EVENT_H__
27 #define TIME_EVENT_H__
28 
29 #include "event.h"
30 
31 /**
32  * The time %event executes the attached script or callback at a certain
33  * point in %game-time. This point can either be relative to the current
34  * time, or absolute in time. In any case, this point should be in the
35  * future. Time %event with an alarm time in the past will be triggered
36  * at once.
37  */
38 class time_event : public event
39 {
40 public:
41  /**
42  * @name Initialization
43  */
44  //@{
45 
46  /**
47  * Create a new time %event.
48  *
49  * @param time The time when the %event should be raised. The string
50  * specifies week, day, hour, minute and 1/10 minute in the format
51  * "<number>w<number>d<number>h<number>m<number>t". If a number is
52  * 0, it can be omitted.
53  * @param absolute Decides whether the given time is relative from now
54  * on, or an absolute time
55  */
56  time_event (const string & time, bool absolute = false);
57 
58 #ifndef SWIG
59  /**
60  * Standard constructor.
61  */
62  time_event () : event ()
63  {
64  Type = TIME_EVENT;
65  Repeat = 1;
66  }
67 
68  /**
69  * Create a new time %event. This constructor is primarily used for
70  * raising time events.
71  *
72  * @param time The "alarm" time in %gametime minutes.
73  */
74  time_event (const u_int32 & time) : event ()
75  {
76  Type = TIME_EVENT;
77  Time = time;
78  Repeat = 1;
79  }
80 #endif // SWIG
81 
82  /**
83  * Set whether the %event should be raised at fixed intervals.
84  *
85  * @param interval The time between two occurences of the %event.
86  * @param count The number of times the %event shall be repeated.
87  * Specify -1 to repeat it an unlimited number of times.
88  */
89  void set_repeat (const string & interval, s_int32 count = -1);
90  //@}
91 
92  /**
93  * @name Event Handling
94  */
95  //@{
96 
97  /**
98  * Compare two time events for equality.
99  *
100  * @param evnt The time event to compare this to.
101  * @return <b>True</b> if the two events equal, <b>false</b> otherwise.
102  */
103  bool equals (const event * evnt)
104  {
105  time_event *e = (time_event *) evnt;
106  return Time <= e->time ();
107  }
108 
109  /**
110  * Executes the script associated with this time %event. If the
111  * event repeats it is re-registered with the %event handler.
112  *
113  * @param evnt The %event that triggered this time %event.
114  *
115  * @return The number of times the %event needs to be repeated.
116  */
117  s_int32 execute (const event * evnt);
118  //@}
119 
120  /**
121  * @name Loading / Saving
122  */
123  //@{
124 
125  /**
126  * Saves the basic %event %data (such as the type or script data)
127  * to a file.
128  *
129  * @param out file where to save the %event.
130  */
131  void put_state (ogzstream& out) const;
132 
133  /**
134  * Loads the basic %event %date from a file.
135  *
136  * @param in file to load the %event from.
137  * @return \e true if the %event could be loaded, \e false otherwise
138  */
139  bool get_state (igzstream& in);
140 
141  //@}
142 
143  /**
144  * @name Pausing / Resuming execution
145  */
146  //@{
147 
148  /**
149  * Disable the %event temporarily. As long as it in this state, the
150  * event will neither be executed, nor will its repeat-count change.
151  *
152  * The alarm time of relative time events will be prolongued be the
153  * time the event was paused. Absolute events will only be deferred
154  * until they are resumed.
155  */
156  void pause ();
157 
158  /**
159  * Re-enable an %event that has been paused.
160  *
161  * Absolute events that are past their alarm time are executed at once.
162  */
163  void resume ();
164 
165  //@}
166 
167  /**
168  * Get the event's "alarm" time, i.e. the time when it needs to be
169  * executed.
170  *
171  * @return the "alarm" time in 1/10 %gametime minutes.
172  */
173  u_int32 time () const
174  {
175  return Time;
176  }
177 
178 private:
179 #ifndef SWIG
180  // the time when the event shall be triggered
181  u_int32 Time;
182 
183  // time that lies between two occurances of the event
184  u_int32 Interval;
185 
186  // whether the alarm time is relative or absolute
187  bool Absolute;
188 #endif // SWIG
189 };
190 
191 #endif // TIME_EVENT_H__
time_event
The time event executes the attached script or callback at a certain point in game-time.
Definition: time_event.h:38
igzstream
Class to read data from a Gzip compressed file.
Definition: fileops.h:135
u_int32
#define u_int32
32 bits long unsigned integer
Definition: types.h:41
time_event::get_state
bool get_state(igzstream &in)
Loads the basic event date from a file.
Definition: time_event.cc:111
event::Repeat
s_int32 Repeat
Defines how often the event should be repeated.
Definition: event.h:336
s_int32
#define s_int32
32 bits long signed integer
Definition: types.h:50
time_event::time_event
time_event()
Standard constructor.
Definition: time_event.h:62
ogzstream
Class to write data from a Gzip compressed file.
Definition: fileops.h:227
time_event::put_state
void put_state(ogzstream &out) const
Saves the basic event data (such as the type or script data) to a file.
Definition: time_event.cc:99
time_event::pause
void pause()
Disable the event temporarily.
Definition: time_event.cc:81
event.h
Declares the event class.
event::Type
u_int8 Type
Event type - see enum above.
Definition: event.h:309
event
Base class for events.
Definition: event.h:75
time_event::time
u_int32 time() const
Get the event's "alarm" time, i.e.
Definition: time_event.h:173
time_event::resume
void resume()
Re-enable an event that has been paused.
Definition: time_event.cc:90
time_event::time_event
time_event(const u_int32 &time)
Create a new time event.
Definition: time_event.h:74
time_event::equals
bool equals(const event *evnt)
Compare two time events for equality.
Definition: time_event.h:103
time_event::set_repeat
void set_repeat(const string &interval, s_int32 count=-1)
Set whether the event should be raised at fixed intervals.
Definition: time_event.cc:40
time_event::execute
s_int32 execute(const event *evnt)
Executes the script associated with this time event.
Definition: time_event.cc:47