1/*
2 This file is part of the kcal 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 KCAL_TODO_H
32#define KCAL_TODO_H
33
34#include "incidence.h"
35#include <kpimutils/supertrait.h>
36#include <QtCore/QByteArray>
37
38namespace KCal {
39
40/**
41 @brief
42 Provides a To-do in the sense of RFC2445.
43*/
44class KCAL_DEPRECATED_EXPORT Todo : public Incidence
45{
46 public:
47 /**
48 List of to-dos.
49 */
50 typedef ListBase<Todo> List;
51
52 /**
53 A shared pointer to a Todo object.
54 */
55 typedef boost::shared_ptr<Todo> Ptr;
56
57 /**
58 A shared pointer to a non-mutable Todo object.
59 */
60 typedef boost::shared_ptr<const Todo> ConstPtr;
61
62 /**
63 Constructs an empty to-do.
64 */
65 Todo();
66
67 /**
68 Copy constructor.
69 @param other is the to-do to copy.
70 */
71 Todo( const Todo &other );
72
73 /**
74 Destroys a to-do.
75 */
76 ~Todo();
77
78 /**
79 @copydoc
80 IncidenceBase::type()
81 */
82 QByteArray type() const;
83
84 /**
85 @copydoc
86 IncidenceBase::typeStr()
87 */
88 //KDE5: QString typeStr() const;
89
90 /**
91 Returns an exact copy of this todo. The returned object is owned by the
92 caller.
93 */
94 Todo *clone();
95
96 /**
97 Sets due date and time.
98
99 @param dtDue The due date/time.
100 @param first If true and the todo recurs, the due date of the first
101 occurrence will be returned. If false and recurrent, the date of the
102 current occurrence will be returned. If non-recurrent, the normal due
103 date will be returned.
104 */
105 void setDtDue( const KDateTime &dtDue, bool first = false );
106
107 /**
108 Returns due date and time.
109
110 @param first If true and the todo recurs, the due date of the first
111 occurrence will be returned. If false and recurrent, the date of the
112 current occurrence will be returned. If non-recurrent, the normal due
113 date will be returned.
114 */
115 KDateTime dtDue( bool first = false ) const;
116
117 /**
118 Returns due time as string formatted according to the user's locale
119 settings.
120
121 @param shortfmt If set, use short date format; else use long format.
122 @param spec If set, return the time in the given spec, else use the
123 todo's current spec.
124
125 @deprecated use IncidenceFormatter::timeToString()
126 */
127 KCAL_DEPRECATED QString dtDueTimeStr(
128 bool shortfmt = true, const KDateTime::Spec &spec = KDateTime::Spec() ) const;
129
130 /**
131 Returns due date as string formatted according to the user's locale
132 settings.
133
134 @param shortfmt If set, use short date format; else use long format.
135 @param spec If set, return the date in the given spec, else use the
136 todo's current spec.
137
138 @deprecated use IncidenceFormatter::dateToString()
139 */
140 KCAL_DEPRECATED QString dtDueDateStr(
141 bool shortfmt = true, const KDateTime::Spec &spec = KDateTime::Spec() ) const;
142
143 /**
144 Returns due date and time as string formatted according to the user's
145 locale settings.
146
147 @param shortfmt If set, use short date format; else use long format.
148 @param spec If set, return the date/time in the given spec, else use
149 the todo's current spec.
150
151 @deprecated use IncidenceFormatter::dateTimeToString()
152 */
153 KCAL_DEPRECATED QString dtDueStr(
154 bool shortfmt = true, const KDateTime::Spec &spec = KDateTime::Spec() ) const;
155
156 /**
157 Returns true if the todo has a due date, otherwise return false.
158 */
159 bool hasDueDate() const;
160
161 /**
162 Sets if the todo has a due date.
163
164 @param hasDueDate true if todo has a due date, otherwise false
165 */
166 void setHasDueDate( bool hasDueDate );
167
168 /**
169 Returns true if the todo has a start date, otherwise return false.
170 */
171 bool hasStartDate() const;
172
173 /**
174 Sets if the todo has a start date.
175
176 @param hasStartDate true if todo has a start date, otherwise false
177 */
178 void setHasStartDate( bool hasStartDate );
179
180 /**
181 @copydoc
182 IncidenceBase::dtStart()
183 */
184 virtual KDateTime dtStart() const;
185
186 /**
187 Returns the start date of the todo.
188 @param first If true, the start date of the todo will be returned;
189 also, if the todo recurs, the start date of the first occurrence
190 will be returned.
191 If false and the todo recurs, the relative start date will be returned,
192 based on the date returned by dtRecurrence().
193 */
194 KDateTime dtStart( bool first ) const;
195
196 /**
197 Sets the start date of the todo.
198
199 @param dtStart is the to-do start date.
200 */
201 void setDtStart( const KDateTime &dtStart );
202
203 /**
204 Returns a todo's starting time as a string formatted according to the
205 user's locale settings.
206
207 @param shortfmt If set, use short date format; else use long format.
208 @param first If true, the start date of the todo will be returned;
209 also, if the todo recurs, the start date of the first occurrence
210 will be returned.
211 If false and the todo recurs, the relative start date will be returned,
212 based on the date returned by dtRecurrence().
213 @param spec If set, returns the time in the given spec, else use the
214 todo's current spec.
215
216 @deprecated use IncidenceFormatter::timeToString()
217 */
218 KCAL_DEPRECATED QString dtStartTimeStr(
219 bool shortfmt, bool first, const KDateTime::Spec &spec = KDateTime::Spec() ) const;
220
221 /**
222 @copydoc
223 IncidenceBase::dtStartTimeStr()
224 */
225 virtual KCAL_DEPRECATED QString dtStartTimeStr(
226 bool shortfmt = true, const KDateTime::Spec &spec = KDateTime::Spec() ) const;
227
228 /**
229 Returns a todo's starting date as a string formatted according to the
230 user's locale settings.
231
232 @param shortfmt If set, use short date format; else use long format.
233 @param first If true, the start date of the todo will be returned;
234 also, if the todo recurs, the start date of the first occurrence
235 will be returned.
236 If false and the todo recurs, the relative start date will be returned,
237 based on the date returned by dtRecurrence().
238 @param spec If set, returns the date in the given spec, else use the
239 todo's current spec.
240
241 @deprecated use IncidenceFormatter::dateToString()
242 */
243 KCAL_DEPRECATED QString dtStartDateStr(
244 bool shortfmt, bool first, const KDateTime::Spec &spec = KDateTime::Spec() ) const;
245
246 /**
247 @copydoc
248 IncidenceBase::dtStartDateStr()
249 */
250 virtual KCAL_DEPRECATED QString dtStartDateStr(
251 bool shortfmt = true, const KDateTime::Spec &spec = KDateTime::Spec() ) const;
252
253 /**
254 Returns a todo's starting date and time as a string formatted according
255 to the user's locale settings.
256
257 @param shortfmt If set, use short date format; else use long format.
258 @param first If true, the start date of the todo will be returned;
259 also, if the todo recurs, the start date of the first occurrence
260 will be returned.
261 If false and the todo recurs, the relative start date will be returned,
262 based on the date returned by dtRecurrence().
263 @param spec If set, returns the date and time in the given spec, else
264 use the todo's current spec.
265
266 @deprecated use IncidenceFormatter::dateTimeToString()
267 */
268 KCAL_DEPRECATED QString dtStartStr(
269 bool shortfmt, bool first, const KDateTime::Spec &spec = KDateTime::Spec() ) const;
270
271 /**
272 @copydoc
273 IncidenceBase::dtStartStr()
274 */
275 virtual KCAL_DEPRECATED QString dtStartStr(
276 bool shortfmt = true, const KDateTime::Spec &spec = KDateTime::Spec() ) const;
277
278 /**
279 Returns true if the todo is 100% completed, otherwise return false.
280 @see isOverdue, isInProgress(), isOpenEnded(), isNotStarted(bool),
281 setCompleted(), percentComplete()
282 */
283 bool isCompleted() const;
284
285 /**
286 Sets completed state.
287
288 @param completed If true set completed state to 100%, if false set
289 completed state to 0%.
290
291 @see isCompleted(), percentComplete()
292 */
293 void setCompleted( bool completed );
294
295 /**
296 Returns what percentage of the to-do is completed. Returns a value
297 between 0 and 100.
298 */
299 int percentComplete() const;
300
301 /**
302 Sets what percentage of the to-do is completed. Valid values are in the
303 range from 0 to 100.
304
305 @param percent is the completion percentage, which as integer value
306 between 0 and 100, inclusive.
307
308 @see isCompleted(), setCompleted()
309 */
310 void setPercentComplete( int percent );
311
312 /**
313 Returns date and time when todo was completed.
314 */
315 KDateTime completed() const;
316
317 /**
318 Returns string contaiting date and time when the todo was completed
319 formatted according to the user's locale settings.
320
321 @param shortfmt If set, use short date format; else use long format.
322 */
323 QString completedStr( bool shortfmt = false ) const;
324
325 /**
326 Sets date and time of completion.
327
328 @param completeDate is the to-do completion date.
329 */
330 void setCompleted( const KDateTime &completeDate );
331
332 /**
333 Returns true, if the to-do has a date associated with completion,
334 otherwise return false.
335 */
336 bool hasCompletedDate() const;
337
338 /**
339 Returns true, if the to-do is in-progress (started, or >0% completed);
340 otherwise return false. If the to-do is overdue, then it is not
341 considered to be in-progress.
342
343 @param first If true, the start and due dates of the todo will be used;
344 also, if the todo recurs, the start date and due date of the first
345 occurrence will be used.
346 If false and the todo recurs, the relative start and due dates will be
347 used, based on the date returned by dtRecurrence().
348 @see isOverdue(), isCompleted(), isOpenEnded(), isNotStarted(bool)
349 @since 4.4
350 */
351 bool isInProgress( bool first ) const;
352
353 /**
354 Returns true, if the to-do is open-ended (no due date); false otherwise.
355 @see isOverdue(), isCompleted(), isInProgress(), isNotStarted(bool)
356 @since 4.4
357 */
358 bool isOpenEnded() const;
359
360 /**
361 Returns true, if the to-do has yet to be started (no start date and 0%
362 completed); otherwise return false.
363
364 @param first If true, the start date of the todo will be used;
365 also, if the todo recurs, the start date of the first occurrence
366 will be used.
367 If false and the todo recurs, the relative start date will be used,
368 based on the date returned by dtRecurrence().
369 @see isOverdue(), isCompleted(), isInProgress(), isOpenEnded()
370 @since 4.4
371 */
372 bool isNotStarted( bool first ) const;
373
374 /**
375 @copydoc
376 IncidenceBase::shiftTimes()
377 */
378 virtual void shiftTimes( const KDateTime::Spec &oldSpec,
379 const KDateTime::Spec &newSpec );
380
381 /**
382 Sets the due date/time of the current occurrence if recurrent.
383
384 @param dt is the
385 */
386 void setDtRecurrence( const KDateTime &dt );
387
388 /**
389 Returns the due date/time of the current occurrence if recurrent.
390 */
391 KDateTime dtRecurrence() const;
392
393 /**
394 Returns true if the @p date specified is one on which the to-do will
395 recur. Todos are a special case, hence the overload. It adds an extra
396 check, which make it return false if there's an occurrence between
397 the recur start and today.
398
399 @param date is the date to check.
400 @param timeSpec is the
401 */
402 virtual bool recursOn( const QDate &date,
403 const KDateTime::Spec &timeSpec ) const;
404
405 /**
406 Returns true if this todo is overdue (e.g. due date is lower than today
407 and not completed), else false.
408 @see isCompleted(), isInProgress(), isOpenEnded(), isNotStarted(bool)
409 */
410 bool isOverdue() const;
411
412 /**
413 Assignment operator.
414 @param other is the to-do to assign.
415 */
416 Todo &operator=( const Todo &other );
417
418 /**
419 Compare this with @p todo for equality.
420 @param todo is the to-do to compare.
421 */
422 bool operator==( const Todo &todo ) const;
423
424 protected:
425 /**
426 Returns the end date/time of the base incidence.
427 */
428 virtual KDateTime endDateRecurrenceBase() const;
429
430 private:
431 /**
432 @copydoc
433 IncidenceBase::accept()
434 */
435 bool accept( Visitor &v ) { return v.visit( this ); }
436
437 //@cond PRIVATE
438 class Private;
439 Private *const d;
440 //@endcond
441};
442
443}
444
445//@cond PRIVATE
446// super class trait specialization
447namespace KPIMUtils {
448 template <> struct SuperClass<KCal::Todo> : public SuperClassTrait<KCal::Incidence>{};
449}
450//@endcond
451
452#endif
453