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