1 | /* |
2 | This file is part of the kcalcore library. |
3 | |
4 | Copyright (c) 2001-2003 Cornelius Schumacher <schumacher@kde.org> |
5 | Copyright (C) 2009 Allen Winter <winter@kde.org> |
6 | |
7 | This library is free software; you can redistribute it and/or |
8 | modify it under the terms of the GNU Library General Public |
9 | License as published by the Free Software Foundation; either |
10 | version 2 of the License, or (at your option) any later version. |
11 | |
12 | This library is distributed in the hope that it will be useful, |
13 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
14 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
15 | Library General Public License for more details. |
16 | |
17 | You should have received a copy of the GNU Library General Public License |
18 | along with this library; see the file COPYING.LIB. If not, write to |
19 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
20 | Boston, MA 02110-1301, USA. |
21 | */ |
22 | /** |
23 | @file |
24 | This file is part of the API for handling calendar data and |
25 | defines the Todo class. |
26 | |
27 | @author Cornelius Schumacher \<schumacher@kde.org\> |
28 | @author Allen Winter \<winter@kde.org\> |
29 | */ |
30 | |
31 | #ifndef KCALCORE_TODO_H |
32 | #define KCALCORE_TODO_H |
33 | |
34 | #include "kcalcore_export.h" |
35 | #include "incidence.h" |
36 | #include "supertrait.h" |
37 | |
38 | namespace KCalCore { |
39 | |
40 | /** |
41 | @brief |
42 | Provides a To-do in the sense of RFC2445. |
43 | */ |
44 | class KCALCORE_EXPORT Todo : public Incidence |
45 | { |
46 | public: |
47 | /** |
48 | A shared pointer to a Todo object. |
49 | */ |
50 | typedef QSharedPointer<Todo> Ptr; |
51 | |
52 | /** |
53 | List of to-dos. |
54 | */ |
55 | typedef QVector<Ptr> List; |
56 | |
57 | /** |
58 | Constructs an empty to-do. |
59 | */ |
60 | Todo(); |
61 | |
62 | /** |
63 | Copy constructor. |
64 | @param other is the to-do to copy. |
65 | */ |
66 | Todo(const Todo &other); |
67 | |
68 | /** |
69 | Destroys a to-do. |
70 | */ |
71 | ~Todo(); |
72 | |
73 | /** |
74 | @copydoc IncidenceBase::type() |
75 | */ |
76 | IncidenceType type() const; |
77 | |
78 | /** |
79 | @copydoc IncidenceBase::typeStr() |
80 | */ |
81 | QByteArray typeStr() const; |
82 | |
83 | /** |
84 | Returns an exact copy of this todo. The returned object is owned by the caller. |
85 | @return A pointer to a Todo containing an exact copy of this object. |
86 | */ |
87 | Todo *clone() const; |
88 | |
89 | /** |
90 | Sets due date and time. |
91 | |
92 | @param dtDue The due date/time. |
93 | @param first If true and the todo recurs, the due date of the first |
94 | occurrence will be returned. If false and recurrent, the date of the |
95 | current occurrence will be returned. If non-recurrent, the normal due |
96 | date will be returned. |
97 | */ |
98 | void setDtDue(const KDateTime &dtDue, bool first = false); |
99 | |
100 | /** |
101 | Returns the todo due datetime. |
102 | |
103 | @param first If true and the todo recurs, the due datetime of the first |
104 | occurrence will be returned. If false and recurrent, the datetime of the |
105 | current occurrence will be returned. If non-recurrent, the normal due |
106 | datetime will be returned. |
107 | @return A KDateTime containing the todo due datetime. |
108 | */ |
109 | KDateTime dtDue(bool first = false) const; |
110 | |
111 | /** |
112 | Returns if the todo has a due datetime. |
113 | @return true if the todo has a due datetime; false otherwise. |
114 | */ |
115 | bool hasDueDate() const; |
116 | |
117 | /** |
118 | Sets if the todo has a due datetime. |
119 | @param hasDueDate true if todo has a due datetime, otherwise false |
120 | @deprecated Use setDtDue( KDateTime() ) |
121 | */ |
122 | KCALCORE_DEPRECATED void setHasDueDate(bool hasDueDate); |
123 | |
124 | /** |
125 | Returns if the todo has a start datetime. |
126 | @return true if the todo has a start datetime; false otherwise. |
127 | */ |
128 | bool hasStartDate() const; |
129 | |
130 | /** |
131 | Sets if the todo has a start datetime. |
132 | @param hasStartDate true if todo has a start datetime, otherwise false. |
133 | @deprecated Use setDtStart( KDateTime() ) |
134 | */ |
135 | KCALCORE_DEPRECATED void setHasStartDate(bool hasStartDate); |
136 | |
137 | /** |
138 | @copydoc IncidenceBase::dtStart() |
139 | */ |
140 | virtual KDateTime dtStart() const; |
141 | |
142 | /** |
143 | Returns the start datetime of the todo. |
144 | |
145 | @param first If true, the start datetime of the todo will be returned; |
146 | also, if the todo recurs, the start datetime of the first occurrence |
147 | will be returned. |
148 | If false and the todo recurs, the relative start datetime will be returned, |
149 | based on the datetime returned by dtRecurrence(). |
150 | @return A KDateTime for the start datetime of the todo. |
151 | */ |
152 | KDateTime dtStart(bool first) const; |
153 | |
154 | /** |
155 | Sets the start datetime of the todo. |
156 | @param dtStart is the to-do start datetime. |
157 | */ //TODO_KDE5: Remove (see IncidenceBase) |
158 | void setDtStart(const KDateTime &dtStart); |
159 | |
160 | /** |
161 | Returns if the todo is 100% completed. |
162 | @return true if the todo is 100% completed; false otherwise. |
163 | |
164 | @see isOverdue, isInProgress(), isOpenEnded(), isNotStarted(bool), |
165 | setCompleted(), percentComplete() |
166 | */ |
167 | bool isCompleted() const; |
168 | |
169 | /** |
170 | Sets completed state. |
171 | |
172 | @param completed If true set completed state to 100%, if false set |
173 | completed state to 0%. |
174 | |
175 | @see isCompleted(), percentComplete() |
176 | */ |
177 | void setCompleted(bool completed); |
178 | |
179 | /** |
180 | Returns what percentage of the to-do is completed. |
181 | @return The percentage complete of the to-do as an integer between 0 and 100, inclusive. |
182 | @see setPercentComplete(), isCompleted() |
183 | */ |
184 | int percentComplete() const; |
185 | |
186 | /** |
187 | Sets what percentage of the to-do is completed. Valid values are in the |
188 | range from 0 to 100. |
189 | |
190 | @param percent is the completion percentage, which as integer value |
191 | between 0 and 100, inclusive. |
192 | |
193 | @see isCompleted(), setCompleted() |
194 | */ |
195 | void setPercentComplete(int percent); |
196 | |
197 | /** |
198 | Returns the to-do was completion datetime. |
199 | |
200 | @return A KDateTime for the completeion datetime of the to-do. |
201 | @see hasCompletedDate() |
202 | */ |
203 | KDateTime completed() const; |
204 | |
205 | /** |
206 | Sets date and time of completion. |
207 | |
208 | @param completeDate is the to-do completion date. |
209 | @see completed(), hasCompletedDate() |
210 | */ |
211 | void setCompleted(const KDateTime &completeDate); |
212 | |
213 | /** |
214 | Returns if the to-do has a completion datetime. |
215 | |
216 | @return true if the to-do has a date associated with completion; false otherwise. |
217 | @see setCompleted(), completed() |
218 | */ |
219 | bool hasCompletedDate() const; |
220 | |
221 | /** |
222 | Returns true, if the to-do is in-progress (started, or >0% completed); |
223 | otherwise return false. If the to-do is overdue, then it is not |
224 | considered to be in-progress. |
225 | |
226 | @param first If true, the start and due dates of the todo will be used; |
227 | also, if the todo recurs, the start date and due date of the first |
228 | occurrence will be used. |
229 | If false and the todo recurs, the relative start and due dates will be |
230 | used, based on the date returned by dtRecurrence(). |
231 | @see isOverdue(), isCompleted(), isOpenEnded(), isNotStarted(bool) |
232 | */ |
233 | bool isInProgress(bool first) const; |
234 | |
235 | /** |
236 | Returns true, if the to-do is open-ended (no due date); false otherwise. |
237 | @see isOverdue(), isCompleted(), isInProgress(), isNotStarted(bool) |
238 | */ |
239 | bool isOpenEnded() const; |
240 | |
241 | /** |
242 | Returns true, if the to-do has yet to be started (no start date and 0% |
243 | completed); otherwise return false. |
244 | |
245 | @param first If true, the start date of the todo will be used; |
246 | also, if the todo recurs, the start date of the first occurrence |
247 | will be used. |
248 | If false and the todo recurs, the relative start date will be used, |
249 | based on the date returned by dtRecurrence(). |
250 | @see isOverdue(), isCompleted(), isInProgress(), isOpenEnded() |
251 | */ |
252 | bool isNotStarted(bool first) const; |
253 | |
254 | /** |
255 | @copydoc IncidenceBase::shiftTimes() |
256 | */ |
257 | virtual void shiftTimes(const KDateTime::Spec &oldSpec, |
258 | const KDateTime::Spec &newSpec); |
259 | |
260 | /** |
261 | @copydoc IncidenceBase::setAllDay(). |
262 | */ |
263 | void setAllDay(bool allDay); |
264 | |
265 | /** |
266 | Sets the due date/time of the current occurrence if recurrent. |
267 | |
268 | @param dt is the |
269 | */ |
270 | void setDtRecurrence(const KDateTime &dt); |
271 | |
272 | /** |
273 | Returns the due date/time of the current occurrence if recurrent. |
274 | */ |
275 | KDateTime dtRecurrence() const; |
276 | |
277 | /** |
278 | Returns true if the @p date specified is one on which the to-do will |
279 | recur. Todos are a special case, hence the overload. It adds an extra |
280 | check, which make it return false if there's an occurrence between |
281 | the recur start and today. |
282 | |
283 | @param date is the date to check. |
284 | @param timeSpec is the |
285 | */ |
286 | virtual bool recursOn(const QDate &date, |
287 | const KDateTime::Spec &timeSpec) const; |
288 | |
289 | /** |
290 | Returns true if this todo is overdue (e.g. due date is lower than today |
291 | and not completed), else false. |
292 | @see isCompleted(), isInProgress(), isOpenEnded(), isNotStarted(bool) |
293 | */ |
294 | bool isOverdue() const; |
295 | |
296 | /** |
297 | @copydoc IncidenceBase::dateTime() |
298 | */ |
299 | KDateTime dateTime(DateTimeRole role) const; |
300 | |
301 | /** |
302 | @copydoc IncidenceBase::setDateTime() |
303 | */ |
304 | void setDateTime(const KDateTime &dateTime, DateTimeRole role); |
305 | |
306 | /** |
307 | @copydoc IncidenceBase::mimeType() |
308 | */ |
309 | QLatin1String mimeType() const; |
310 | |
311 | /** |
312 | @copydoc Incidence::iconName() |
313 | */ |
314 | QLatin1String iconName(const KDateTime &recurrenceId = KDateTime()) const; |
315 | |
316 | /** |
317 | Returns the Akonadi specific sub MIME type of a KCalCore::Todo. |
318 | */ |
319 | static QLatin1String todoMimeType(); |
320 | |
321 | protected: |
322 | /** |
323 | Compare this with @p todo for equality. |
324 | @param todo is the to-do to compare. |
325 | */ |
326 | virtual bool equals(const IncidenceBase &todo) const; |
327 | |
328 | /** |
329 | @copydoc IncidenceBase::assign() |
330 | */ |
331 | virtual IncidenceBase &assign(const IncidenceBase &other); |
332 | |
333 | /** |
334 | @copydoc IncidenceBase::virtual_hook() |
335 | */ |
336 | virtual void virtual_hook(int id, void *data); |
337 | |
338 | private: |
339 | /** |
340 | @copydoc IncidenceBase::accept() |
341 | */ |
342 | bool accept(Visitor &v, IncidenceBase::Ptr incidence); |
343 | |
344 | /** |
345 | Disabled, otherwise could be dangerous if you subclass Todo. |
346 | Use IncidenceBase::operator= which is safe because it calls |
347 | virtual function assign(). |
348 | @param other is another Todo object to assign to this one. |
349 | */ |
350 | Todo &operator=(const Todo &other); |
351 | |
352 | // For polymorfic serialization |
353 | void serialize(QDataStream &out); |
354 | void deserialize(QDataStream &in); |
355 | |
356 | //@cond PRIVATE |
357 | class Private; |
358 | Private *const d; |
359 | //@endcond |
360 | }; |
361 | |
362 | } // namespace KCalCore |
363 | |
364 | //@cond PRIVATE |
365 | Q_DECLARE_TYPEINFO(KCalCore::Todo::Ptr, Q_MOVABLE_TYPE); |
366 | Q_DECLARE_METATYPE(KCalCore::Todo::Ptr) |
367 | |
368 | namespace KPIMUtils { |
369 | // super class trait specialization |
370 | template <> struct SuperClass<KCalCore::Todo> : public SuperClassTrait<KCalCore::Incidence> {}; |
371 | } |
372 | //@endcond |
373 | |
374 | #endif |
375 | |