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

KDE's Doxygen guidelines are available online.