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
38namespace KCalCore {
39
40/**
41 @brief
42 Provides a To-do in the sense of RFC2445.
43*/
44class KCALCORE_EXPORT Todo : public Incidence
45{
46public:
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
321protected:
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
338private:
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
365Q_DECLARE_TYPEINFO(KCalCore::Todo::Ptr, Q_MOVABLE_TYPE);
366Q_DECLARE_METATYPE(KCalCore::Todo::Ptr)
367
368namespace KPIMUtils {
369// super class trait specialization
370template <> struct SuperClass<KCalCore::Todo> : public SuperClassTrait<KCalCore::Incidence> {};
371}
372//@endcond
373
374#endif
375