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 | |
38 | namespace KCal { |
39 | |
40 | /** |
41 | @brief |
42 | Provides a To-do in the sense of RFC2445. |
43 | */ |
44 | class 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 |
447 | namespace KPIMUtils { |
448 | template <> struct SuperClass<KCal::Todo> : public SuperClassTrait<KCal::Incidence>{}; |
449 | } |
450 | //@endcond |
451 | |
452 | #endif |
453 | |