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 if the todo is 100% completed.
141  @return true if the todo is 100% completed; false otherwise.
142 
143  @see isOverdue, isInProgress(), isOpenEnded(), isNotStarted(bool),
144  setCompleted(), percentComplete()
145  */
146  Q_REQUIRED_RESULT bool isCompleted() const;
147 
148  /**
149  Sets completed state.
150 
151  @param completed If true set completed state to 100%, if false set
152  completed state to 0%.
153 
154  @see isCompleted(), percentComplete()
155  */
156  void setCompleted(bool completed);
157 
158  /**
159  Returns what percentage of the to-do is completed.
160  @return The percentage complete of the to-do as an integer between 0 and 100, inclusive.
161  @see setPercentComplete(), isCompleted()
162  */
163  Q_REQUIRED_RESULT int percentComplete() const;
164 
165  /**
166  Sets what percentage of the to-do is completed. Valid values are in the
167  range from 0 to 100.
168 
169  @param percent is the completion percentage, which as integer value
170  between 0 and 100, inclusive.
171 
172  @see isCompleted(), setCompleted()
173  */
174  void setPercentComplete(int percent);
175 
176  /**
177  Returns the to-do was completion datetime.
178 
179  @return A QDateTime for the completeion datetime of the to-do.
180  @see hasCompletedDate()
181  */
182  Q_REQUIRED_RESULT QDateTime completed() const;
183 
184  /**
185  Sets date and time of completion.
186 
187  @param completeDate is the to-do completion date.
188  @see completed(), hasCompletedDate()
189  */
190  void setCompleted(const QDateTime &completeDate);
191 
192  /**
193  Returns if the to-do has a completion datetime.
194 
195  @return true if the to-do has a date associated with completion; false otherwise.
196  @see setCompleted(), completed()
197  */
198  bool hasCompletedDate() const;
199 
200  /**
201  Returns true, if the to-do is in-progress (started, or >0% completed);
202  otherwise return false. If the to-do is overdue, then it is not
203  considered to be in-progress.
204 
205  @param first If true, the start and due dates of the todo will be used;
206  also, if the todo recurs, the start date and due date of the first
207  occurrence will be used.
208  If false and the todo recurs, the relative start and due dates will be
209  used, based on the date returned by dtRecurrence().
210  @see isOverdue(), isCompleted(), isOpenEnded(), isNotStarted(bool)
211  */
212  Q_REQUIRED_RESULT bool isInProgress(bool first) const;
213 
214  /**
215  Returns true, if the to-do is open-ended (no due date); false otherwise.
216  @see isOverdue(), isCompleted(), isInProgress(), isNotStarted(bool)
217  */
218  Q_REQUIRED_RESULT bool isOpenEnded() const;
219 
220  /**
221  Returns true, if the to-do has yet to be started (no start date and 0%
222  completed); otherwise return false.
223 
224  @param first If true, the start date of the todo will be used;
225  also, if the todo recurs, the start date of the first occurrence
226  will be used.
227  If false and the todo recurs, the relative start date will be used,
228  based on the date returned by dtRecurrence().
229  @see isOverdue(), isCompleted(), isInProgress(), isOpenEnded()
230  */
231  Q_REQUIRED_RESULT bool isNotStarted(bool first) const;
232 
233  /**
234  @copydoc IncidenceBase::shiftTimes()
235  */
236  void shiftTimes(const QTimeZone &oldZone, const QTimeZone &newZone) override;
237 
238  /**
239  @copydoc IncidenceBase::setAllDay().
240  */
241  void setAllDay(bool allDay) override;
242 
243  /**
244  Sets the due date/time of the current occurrence if recurrent.
245 
246  @param dt is the
247  */
248  void setDtRecurrence(const QDateTime &dt);
249 
250  /**
251  Returns the due date/time of the current occurrence if recurrent.
252  */
253  Q_REQUIRED_RESULT QDateTime dtRecurrence() const;
254 
255  /**
256  Returns true if the @p date specified is one on which the to-do will
257  recur. Todos are a special case, hence the overload. It adds an extra
258  check, which make it return false if there's an occurrence between
259  the recur start and today.
260 
261  @param date is the date to check.
262  @param timeZone is the time zone
263  */
264  bool recursOn(const QDate &date, const QTimeZone &timeZone) const override;
265 
266  /**
267  Returns true if this todo is overdue (e.g. due date is lower than today
268  and not completed), else false.
269  @see isCompleted(), isInProgress(), isOpenEnded(), isNotStarted(bool)
270  */
271  bool isOverdue() const;
272 
273  /**
274  @copydoc IncidenceBase::dateTime()
275  */
276  Q_REQUIRED_RESULT QDateTime dateTime(DateTimeRole role) const override;
277 
278  /**
279  @copydoc IncidenceBase::setDateTime()
280  */
281  void setDateTime(const QDateTime &dateTime, DateTimeRole role) override;
282 
283  /**
284  @copydoc IncidenceBase::mimeType()
285  */
286  Q_REQUIRED_RESULT QLatin1String mimeType() const override;
287 
288  /**
289  @copydoc Incidence::iconName()
290  */
291  Q_REQUIRED_RESULT QLatin1String iconName(const QDateTime &recurrenceId = {}) const override;
292 
293  /**
294  @copydoc
295  Incidence::supportsGroupwareCommunication()
296  */
297  bool supportsGroupwareCommunication() const override;
298 
299  /**
300  Returns the Akonadi specific sub MIME type of a KCalendarCore::Todo.
301  */
302  Q_REQUIRED_RESULT static QLatin1String todoMimeType();
303 
304 protected:
305  /**
306  Compare this with @p todo for equality.
307  @param todo is the to-do to compare.
308  */
309  bool equals(const IncidenceBase &todo) const override;
310 
311  /**
312  @copydoc IncidenceBase::assign()
313  */
314  IncidenceBase &assign(const IncidenceBase &other) override;
315 
316  /**
317  @copydoc IncidenceBase::virtual_hook()
318  */
319  void virtual_hook(VirtualHook id, void *data) override;
320 
321 private:
322  /**
323  @copydoc IncidenceBase::accept()
324  */
325  bool accept(Visitor &v, const IncidenceBase::Ptr &incidence) override;
326 
327  /**
328  Disabled, otherwise could be dangerous if you subclass Todo.
329  Use IncidenceBase::operator= which is safe because it calls
330  virtual function assign().
331  @param other is another Todo object to assign to this one.
332  */
333  Todo &operator=(const Todo &other);
334 
335  // For polymorfic serialization
336  void serialize(QDataStream &out) const override;
337  void deserialize(QDataStream &in) override;
338 
339  //@cond PRIVATE
340  class Private;
341  Private *const d;
342  //@endcond
343 };
344 
345 } // namespace KCalendarCore
346 
347 //@cond PRIVATE
348 Q_DECLARE_TYPEINFO(KCalendarCore::Todo::Ptr, Q_MOVABLE_TYPE);
349 Q_DECLARE_METATYPE(KCalendarCore::Todo::Ptr)
350 Q_DECLARE_METATYPE(KCalendarCore::Todo *)
351 //@endcond
352 
353 #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 Sat Apr 10 2021 22:51:00 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.