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 <[email protected]>
5  SPDX-FileCopyrightText: 2009 Allen Winter <[email protected]>
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 <[email protected]>
15  @author Allen Winter <[email protected]>
16 */
17 
18 #ifndef KCALCORE_TODO_H
19 #define KCALCORE_TODO_H
20 
21 #include "incidence.h"
22 #include "kcalendarcore_export.h"
23 
24 namespace KCalendarCore
25 {
26 
27 class TodoPrivate;
28 
29 /**
30  @brief
31  Provides a To-do in the sense of RFC2445.
32 */
33 class KCALENDARCORE_EXPORT Todo : public Incidence
34 {
35 public:
36  /**
37  A shared pointer to a Todo object.
38  */
40 
41  /**
42  List of to-dos.
43  */
44  typedef QVector<Ptr> List;
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  */
54  Todo();
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 
330 protected:
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 
347 private:
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);
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 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 91)
368  KCALENDARCORE_DEPRECATED_VERSION(5, 91, "Do not use")
369  TodoPrivate *const _ = nullptr; // TODO KF6 remove. ABI compatibility hack.
370 #endif
371  //@endcond
372 };
373 
374 } // namespace KCalendarCore
375 
376 //@cond PRIVATE
377 Q_DECLARE_TYPEINFO(KCalendarCore::Todo::Ptr, Q_MOVABLE_TYPE);
378 Q_DECLARE_METATYPE(KCalendarCore::Todo::Ptr)
379 Q_DECLARE_METATYPE(KCalendarCore::Todo *)
380 //@endcond
381 
382 #endif
DateTimeRole
The different types of incidence date/times roles.
Namespace for all KCalendarCore types.
Definition: alarm.h:36
Provides the abstract base class common to non-FreeBusy (Events, To-dos, Journals) calendar component...
Definition: incidence.h:59
An abstract class that provides a common base for all calendar incidence classes.
Definition: incidencebase.h:98
Provides a To-do in the sense of RFC2445.
Definition: todo.h:33
QSharedPointer< Todo > Ptr
A shared pointer to a Todo object.
Definition: todo.h:39
This class provides the interface for a visitor of calendar components.
Definition: visitor.h:30
IncidenceType
The different types of incidences, per RFC2445.
QVector< Ptr > List
List of to-dos.
Definition: todo.h:44
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Oct 1 2023 03:58:00 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.