KCalendarCore

todo.h
Go to the documentation of this file.
1/*
2 This file is part of the kcalcore library.
3
4 SPDX-FileCopyrightText: 2001-2003 Cornelius Schumacher <schumacher@kde.org>
5 SPDX-FileCopyrightText: 2009 Allen Winter <winter@kde.org>
6
7 SPDX-License-Identifier: LGPL-2.0-or-later
8*/
9/**
10 @file
11 This file is part of the API for handling calendar data and
12 defines the Todo class.
13
14 @author Cornelius Schumacher <schumacher@kde.org>
15 @author Allen Winter <winter@kde.org>
16*/
17
18#ifndef KCALCORE_TODO_H
19#define KCALCORE_TODO_H
20
21#include "incidence.h"
22#include "kcalendarcore_export.h"
23
24namespace KCalendarCore
25{
26
27class TodoPrivate;
28
29/**
30 @brief
31 Provides a To-do in the sense of RFC2445.
32*/
33class KCALENDARCORE_EXPORT Todo : public Incidence
34{
35public:
36 /**
37 A shared pointer to a Todo object.
38 */
40
41 /**
42 List of to-dos.
43 */
45
46 ///@cond PRIVATE
47 // needed for Akonadi polymorphic payload support
48 typedef Incidence SuperClass;
49 ///@endcond
50
51 /**
52 Constructs an empty to-do.
53 */
55
56 /**
57 Copy constructor.
58 @param other is the to-do to copy.
59 */
60 Todo(const Todo &other);
61
62 /**
63 Costructs a todo out of an incidence
64 This constructs allows to make it easy to create a todo from an event.
65 @param other is the incidence to copy.
66 @since 4.14
67 */
68 Todo(const Incidence &other); // krazy:exclude=explicit (copy ctor)
69
70 /**
71 Destroys a to-do.
72 */
73 ~Todo() override;
74
75 /**
76 @copydoc IncidenceBase::type()
77 */
78 Q_REQUIRED_RESULT IncidenceType type() const override;
79
80 /**
81 @copydoc IncidenceBase::typeStr()
82 */
83 Q_REQUIRED_RESULT QByteArray typeStr() const override;
84
85 /**
86 Returns an exact copy of this todo. The returned object is owned by the caller.
87 @return A pointer to a Todo containing an exact copy of this object.
88 */
89 Todo *clone() const override;
90
91 /**
92 Sets due date and time.
93
94 @param dtDue The due date/time.
95 @param first If true and the todo recurs, the due date of the first
96 occurrence will be set. If false and the todo recurs, the occurrence at
97 that date/time becomes the current occurrence. If the todo does not recur,
98 the due date of the todo will be set.
99 */
100 void setDtDue(const QDateTime &dtDue, bool first = false);
101
102 /**
103 Returns the todo due datetime.
104
105 @param first If true and the todo recurs, the due datetime of the first
106 occurrence will be returned. If false and recurrent, the datetime of the
107 current occurrence will be returned. If non-recurrent, the normal due
108 datetime will be returned.
109 @return A QDateTime containing the todo due datetime.
110 */
111 Q_REQUIRED_RESULT QDateTime dtDue(bool first = false) const;
112
113 /**
114 Returns if the todo has a due datetime.
115 @return true if the todo has a due datetime; false otherwise.
116 */
117 Q_REQUIRED_RESULT bool hasDueDate() const;
118
119 /**
120 Returns if the todo has a start datetime.
121 @return true if the todo has a start datetime; false otherwise.
122 */
123 Q_REQUIRED_RESULT bool hasStartDate() const;
124
125 /**
126 @copydoc IncidenceBase::dtStart()
127 */
128 Q_REQUIRED_RESULT QDateTime dtStart() const override;
129
130 /**
131 Returns the start datetime of the todo.
132
133 @param first If true, the start datetime of the todo will be returned;
134 also, if the todo recurs, the start datetime of the first occurrence
135 will be returned.
136 If false and the todo recurs, the relative start datetime will be returned,
137 based on the datetime returned by dtRecurrence().
138 @return A QDateTime for the start datetime of the todo.
139 */
140 Q_REQUIRED_RESULT QDateTime dtStart(bool first) const;
141
142 /**
143 Returns whether the todo is completed or not.
144 @return true if the todo is 100% completed, has status @c StatusCompleted,
145 or has a completed date; false otherwise.
146
147 @see isOverdue, isInProgress(), isOpenEnded(), isNotStarted(bool),
148 setCompleted(), percentComplete()
149 */
150 Q_REQUIRED_RESULT bool isCompleted() const;
151
152 /**
153 Sets completion percentage and status.
154
155 @param completed If @c true, percentage complete is set to 100%, and
156 status is set to @c StatusCompleted; the completion date is @b not set or cleared.
157 If @c false, percentage complete is set to 0%,
158 status is set to @c StatusNone, and the completion date is cleared.
159
160
161 @see isCompleted(), percentComplete(), hasCompletedDate()
162 */
163 void setCompleted(bool completed);
164
165 /**
166 Returns what percentage of the to-do is completed.
167 @return The percentage complete of the to-do as an integer between 0 and 100, inclusive.
168 @see setPercentComplete(), isCompleted()
169 */
170 Q_REQUIRED_RESULT int percentComplete() const;
171
172 /**
173 Sets what percentage of the to-do is completed.
174
175 To prevent inconsistency, if @p percent is not 100, completed() is cleared,
176 and if status() is StatusCompleted it is reset to StatusNone.
177
178 @param percent is the completion percentage. Values greater than 100 are
179 treated as 100; values less than p are treated as 0.
180
181 @see isCompleted(), setCompleted()
182 */
183 void setPercentComplete(int percent);
184
185 /**
186 Returns the to-do was completion datetime.
187
188 @return A QDateTime for the completion datetime of the to-do.
189 @see hasCompletedDate()
190 */
191 Q_REQUIRED_RESULT QDateTime completed() const;
192
193 /**
194 Marks this Todo, or its current recurrence, as completed.
195
196 If the todo does not recur, its completion percentage is set to 100%,
197 and its completion date is set to @p completeDate. If its status is not
198 StatusNone, it is set to StatusCompleted.
199
200 @note
201 If @p completeDate is invalid, the completion date is cleared, but the
202 todo is still "complete".
203
204 If the todo recurs, the first incomplete recurrence is marked complete.
205
206 @param completeDate is the to-do completion date.
207 @see completed(), hasCompletedDate()
208 */
209 void setCompleted(const QDateTime &completeDate);
210
211 /**
212 Returns if the to-do has a completion datetime.
213
214 @return true if the to-do has a date associated with completion; false otherwise.
215 @see setCompleted(), completed()
216 */
217 bool hasCompletedDate() const;
218
219 /**
220 Returns true, if the to-do is in-progress (started, or >0% completed);
221 otherwise return false. If the to-do is overdue, then it is not
222 considered to be in-progress.
223
224 @param first If true, the start and due dates of the todo will be used;
225 also, if the todo recurs, the start date and due date of the first
226 occurrence will be used.
227 If false and the todo recurs, the relative start and due dates will be
228 used, based on the date returned by dtRecurrence().
229 @see isOverdue(), isCompleted(), isOpenEnded(), isNotStarted(bool)
230 */
231 Q_REQUIRED_RESULT bool isInProgress(bool first) const;
232
233 /**
234 Returns true, if the to-do is open-ended (no due date); false otherwise.
235 @see isOverdue(), isCompleted(), isInProgress(), isNotStarted(bool)
236 */
237 Q_REQUIRED_RESULT bool isOpenEnded() const;
238
239 /**
240 Returns true, if the to-do has yet to be started (no start date and 0%
241 completed); otherwise return false.
242
243 @param first If true, the start date of the todo will be used;
244 also, if the todo recurs, the start date of the first occurrence
245 will be used.
246 If false and the todo recurs, the relative start date will be used,
247 based on the date returned by dtRecurrence().
248 @see isOverdue(), isCompleted(), isInProgress(), isOpenEnded()
249 */
250 Q_REQUIRED_RESULT bool isNotStarted(bool first) const;
251
252 /**
253 @copydoc IncidenceBase::shiftTimes()
254 */
255 void shiftTimes(const QTimeZone &oldZone, const QTimeZone &newZone) override;
256
257 /**
258 @copydoc IncidenceBase::setAllDay().
259 */
260 void setAllDay(bool allDay) override;
261
262 /**
263 Identify the earliest uncompleted occurrence of a recurring Todo.
264
265 @param dt Normally, the start date-time of the occurrence.
266 For backwards compatibility, if the Todo does not have a @c dtStart()
267 then pass the occurrence's due date-time.
268 */
269 void setDtRecurrence(const QDateTime &dt);
270
271 /**
272 Returns an identifier for the earliest uncompleted occurrence of a
273 recurring Todo.
274
275 @note
276 Do not rely on the returned value to determine whether the Todo is
277 completed; use @c isCompleted() instead.
278 */
279 Q_REQUIRED_RESULT QDateTime dtRecurrence() const;
280
281 /**
282 Returns true if the @p date specified is one on which the to-do will
283 recur. Todos are a special case, hence the overload. It adds an extra
284 check, which make it return false if there's an occurrence between
285 the recur start and today.
286
287 @param date is the date to check.
288 @param timeZone is the time zone
289 */
290 bool recursOn(const QDate &date, const QTimeZone &timeZone) const override;
291
292 /**
293 Returns true if this todo is overdue (e.g. due date is lower than today
294 and not completed), else false.
295 @see isCompleted(), isInProgress(), isOpenEnded(), isNotStarted(bool)
296 */
297 bool isOverdue() const;
298
299 /**
300 @copydoc IncidenceBase::dateTime()
301 */
302 Q_REQUIRED_RESULT QDateTime dateTime(DateTimeRole role) const override;
303
304 /**
305 @copydoc IncidenceBase::setDateTime()
306 */
307 void setDateTime(const QDateTime &dateTime, DateTimeRole role) override;
308
309 /**
310 @copydoc IncidenceBase::mimeType()
311 */
312 Q_REQUIRED_RESULT QLatin1String mimeType() const override;
313
314 /**
315 @copydoc Incidence::iconName()
316 */
317 Q_REQUIRED_RESULT QLatin1String iconName(const QDateTime &recurrenceId = {}) const override;
318
319 /**
320 @copydoc
321 Incidence::supportsGroupwareCommunication()
322 */
323 bool supportsGroupwareCommunication() const override;
324
325 /**
326 Returns the Akonadi specific sub MIME type of a KCalendarCore::Todo.
327 */
328 Q_REQUIRED_RESULT static QLatin1String todoMimeType();
329
330protected:
331 /**
332 Compare this with @p todo for equality.
333 @param todo is the to-do to compare.
334 */
335 bool equals(const IncidenceBase &todo) const override;
336
337 /**
338 @copydoc IncidenceBase::assign()
339 */
340 IncidenceBase &assign(const IncidenceBase &other) override;
341
342 /**
343 @copydoc IncidenceBase::virtual_hook()
344 */
345 void virtual_hook(VirtualHook id, void *data) override;
346
347private:
348 /**
349 @copydoc IncidenceBase::accept()
350 */
351 bool accept(Visitor &v, const IncidenceBase::Ptr &incidence) override;
352
353 /**
354 Disabled, otherwise could be dangerous if you subclass Todo.
355 Use IncidenceBase::operator= which is safe because it calls
356 virtual function assign().
357 @param other is another Todo object to assign to this one.
358 */
359 Todo &operator=(const Todo &other) = delete;
360
361 // For polymorphic serialization
362 void serialize(QDataStream &out) const override;
363 void deserialize(QDataStream &in) override;
364
365 //@cond PRIVATE
366 Q_DECLARE_PRIVATE(Todo)
367 //@endcond
368};
369
370} // namespace KCalendarCore
371
372//@cond PRIVATE
373Q_DECLARE_TYPEINFO(KCalendarCore::Todo::Ptr, Q_RELOCATABLE_TYPE);
374Q_DECLARE_METATYPE(KCalendarCore::Todo::Ptr)
375Q_DECLARE_METATYPE(KCalendarCore::Todo *)
376//@endcond
377
378#endif
An abstract class that provides a common base for all calendar incidence classes.
IncidenceType
The different types of incidences, per RFC2445.
DateTimeRole
The different types of incidence date/times roles.
Provides the abstract base class common to non-FreeBusy (Events, To-dos, Journals) calendar component...
Definition incidence.h:60
Provides a To-do in the sense of RFC2445.
Definition todo.h:34
Todo(const Incidence &other)
Costructs a todo out of an incidence This constructs allows to make it easy to create a todo from an ...
IncidenceBase & assign(const IncidenceBase &other) override
Provides polymorfic assignment.
Todo * clone() const override
Returns an exact copy of this todo.
IncidenceType type() const override
Returns the incidence type.
QByteArray typeStr() const override
Prints the type of incidence as a string.
bool equals(const IncidenceBase &todo) const override
Compare this with todo for equality.
Todo()
Constructs an empty to-do.
Todo(const Todo &other)
Copy constructor.
QSharedPointer< Todo > Ptr
A shared pointer to a Todo object.
Definition todo.h:39
~Todo() override
Destroys a to-do.
QList< Ptr > List
List of to-dos.
Definition todo.h:44
void setDtDue(const QDateTime &dtDue, bool first=false)
Sets due date and time.
This class provides the interface for a visitor of calendar components.
Definition visitor.h:31
This file is part of the API for handling calendar data and defines the Incidence class.
Namespace for all KCalendarCore types.
Definition alarm.h:37
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 16:57:05 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.