1 | /* |
2 | This file is part of the kcal library. |
3 | |
4 | Copyright (c) 2001-2003 Cornelius Schumacher <schumacher@kde.org> |
5 | |
6 | This library is free software; you can redistribute it and/or |
7 | modify it under the terms of the GNU Library General Public |
8 | License as published by the Free Software Foundation; either |
9 | version 2 of the License, or (at your option) any later version. |
10 | |
11 | This library is distributed in the hope that it will be useful, |
12 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | Library General Public License for more details. |
15 | |
16 | You should have received a copy of the GNU Library General Public License |
17 | along with this library; see the file COPYING.LIB. If not, write to |
18 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | Boston, MA 02110-1301, USA. |
20 | */ |
21 | /** |
22 | @file |
23 | This file is part of the API for handling calendar data and |
24 | defines the Period class. |
25 | |
26 | @brief |
27 | Represents a period of time. |
28 | |
29 | @author Cornelius Schumacher \<schumacher@kde.org\> |
30 | */ |
31 | |
32 | #ifndef KCAL_PERIOD_H |
33 | #define KCAL_PERIOD_H |
34 | |
35 | #include "kcal_export.h" |
36 | #include "duration.h" |
37 | |
38 | #include <kdatetime.h> |
39 | #include <QtCore/QList> |
40 | |
41 | namespace KCal { |
42 | |
43 | /** |
44 | The period can be defined by either a start time and an end time or |
45 | by a start time and a duration. |
46 | */ |
47 | class KCAL_DEPRECATED_EXPORT Period |
48 | { |
49 | public: |
50 | /** |
51 | List of periods. |
52 | */ |
53 | typedef QList<Period> List; |
54 | |
55 | /** |
56 | Constructs a period without a duration. |
57 | */ |
58 | Period(); |
59 | |
60 | /** |
61 | Constructs a period from @p start to @p end. |
62 | |
63 | @param start the time the period begins. |
64 | @param end the time the period ends. |
65 | */ |
66 | Period( const KDateTime &start, const KDateTime &end ); |
67 | |
68 | /** |
69 | Constructs a period from @p start and lasting @p duration. |
70 | |
71 | @param start the time when the period starts. |
72 | @param duration how long the period lasts. |
73 | */ |
74 | Period( const KDateTime &start, const Duration &duration ); |
75 | |
76 | /** |
77 | Constructs a period by copying another period object |
78 | |
79 | @param period the period to copy |
80 | */ |
81 | |
82 | Period( const Period &period ); |
83 | |
84 | /** |
85 | Destroys a period. |
86 | */ |
87 | ~Period(); |
88 | |
89 | /** |
90 | Returns true if the start of this period is earlier than the start of |
91 | the @p other one. |
92 | |
93 | @param other is the other period to compare. |
94 | */ |
95 | bool operator<( const Period &other ) const; |
96 | |
97 | /** |
98 | Returns true if the start of this period is later than the start of |
99 | the @p other one. |
100 | |
101 | @param other the other period to compare |
102 | */ |
103 | bool operator>( const Period &other ) const { return other.operator<( *this ); } |
104 | |
105 | /** |
106 | Returns true if this period is equal to the @p other one. |
107 | Even if their start and end times are the same, two periods are |
108 | considered not equal if one is defined in terms of a duration and the |
109 | other in terms of a start and end time. |
110 | |
111 | @param other the other period to compare |
112 | */ |
113 | bool operator==( const Period &other ) const; |
114 | |
115 | /** |
116 | Returns true if this period is not equal to the @p other one. |
117 | |
118 | @param other the other period to compare |
119 | @see operator==() |
120 | */ |
121 | bool operator!=( const Period &other ) const { return !operator==( other ); } |
122 | |
123 | /** |
124 | Sets this period equal to the @p other one. |
125 | |
126 | @param other is the other period to compare. |
127 | */ |
128 | Period &operator=( const Period &other ); |
129 | |
130 | /** |
131 | Returns when this period starts. |
132 | */ |
133 | KDateTime start() const; |
134 | |
135 | /** |
136 | Returns when this period ends. |
137 | */ |
138 | KDateTime end() const; |
139 | |
140 | /** |
141 | Returns the duration of the period. |
142 | |
143 | If the period is defined in terms of a start and end time, the duration |
144 | is computed from these. In this case, if the time of day in @p start and |
145 | @p end is equal, and their time specifications (i.e. time zone etc.) are |
146 | the same, the duration will be set in terms of days. Otherwise, the |
147 | duration will be set in terms of seconds. |
148 | |
149 | If the period is defined in terms of a duration, that duration is |
150 | returned unchanged. |
151 | */ |
152 | Duration duration() const; |
153 | |
154 | /** |
155 | Returns the duration of the period. |
156 | |
157 | If the period is defined in terms of a start and end time, the duration |
158 | is first computed from these. |
159 | |
160 | If @p type is Days, and the duration is not an exact number of days, |
161 | the duration will be rounded down to the nearest whole number of days. |
162 | |
163 | @param type the unit of time to use (seconds or days) |
164 | */ |
165 | Duration duration( Duration::Type type ) const; |
166 | |
167 | /** |
168 | Returns true if this period has a set duration, false |
169 | if it just has a start and an end. |
170 | */ |
171 | bool hasDuration() const; |
172 | |
173 | /** |
174 | Shift the times of the period so that they appear at the same clock |
175 | time as before but in a new time zone. The shift is done from a viewing |
176 | time zone rather than from the actual period time zone. |
177 | |
178 | For example, shifting a period whose start time is 09:00 America/New York, |
179 | using an old viewing time zone (@p oldSpec) of Europe/London, to a new |
180 | time zone (@p newSpec) of Europe/Paris, will result in the time being |
181 | shifted from 14:00 (which is the London time of the period start) to |
182 | 14:00 Paris time. |
183 | |
184 | @param oldSpec the time specification which provides the clock times |
185 | @param newSpec the new time specification |
186 | */ |
187 | void shiftTimes( const KDateTime::Spec &oldSpec, |
188 | const KDateTime::Spec &newSpec ); |
189 | |
190 | private: |
191 | //@cond PRIVATE |
192 | class Private; |
193 | Private *const d; |
194 | //@endcond |
195 | }; |
196 | |
197 | } |
198 | |
199 | #endif |
200 | |