File indexing completed on 2024-04-21 03:52:54
0001 /* 0002 This file is part of the kcalcore library. 0003 0004 SPDX-FileCopyrightText: 2001-2003 Cornelius Schumacher <schumacher@kde.org> 0005 SPDX-FileCopyrightText: 2009 Allen Winter <winter@kde.org> 0006 0007 SPDX-License-Identifier: LGPL-2.0-or-later 0008 */ 0009 /** 0010 @file 0011 This file is part of the API for handling calendar data and 0012 defines the Todo class. 0013 0014 @author Cornelius Schumacher \<schumacher@kde.org\> 0015 @author Allen Winter \<winter@kde.org\> 0016 */ 0017 0018 #ifndef KCALCORE_TODO_H 0019 #define KCALCORE_TODO_H 0020 0021 #include "incidence.h" 0022 #include "kcalendarcore_export.h" 0023 0024 namespace KCalendarCore 0025 { 0026 0027 class TodoPrivate; 0028 0029 /** 0030 @brief 0031 Provides a To-do in the sense of RFC2445. 0032 */ 0033 class KCALENDARCORE_EXPORT Todo : public Incidence 0034 { 0035 public: 0036 /** 0037 A shared pointer to a Todo object. 0038 */ 0039 typedef QSharedPointer<Todo> Ptr; 0040 0041 /** 0042 List of to-dos. 0043 */ 0044 typedef QList<Ptr> List; 0045 0046 ///@cond PRIVATE 0047 // needed for Akonadi polymorphic payload support 0048 typedef Incidence SuperClass; 0049 ///@endcond 0050 0051 /** 0052 Constructs an empty to-do. 0053 */ 0054 Todo(); 0055 0056 /** 0057 Copy constructor. 0058 @param other is the to-do to copy. 0059 */ 0060 Todo(const Todo &other); 0061 0062 /** 0063 Costructs a todo out of an incidence 0064 This constructs allows to make it easy to create a todo from an event. 0065 @param other is the incidence to copy. 0066 @since 4.14 0067 */ 0068 Todo(const Incidence &other); // krazy:exclude=explicit (copy ctor) 0069 0070 /** 0071 Destroys a to-do. 0072 */ 0073 ~Todo() override; 0074 0075 /** 0076 @copydoc IncidenceBase::type() 0077 */ 0078 Q_REQUIRED_RESULT IncidenceType type() const override; 0079 0080 /** 0081 @copydoc IncidenceBase::typeStr() 0082 */ 0083 Q_REQUIRED_RESULT QByteArray typeStr() const override; 0084 0085 /** 0086 Returns an exact copy of this todo. The returned object is owned by the caller. 0087 @return A pointer to a Todo containing an exact copy of this object. 0088 */ 0089 Todo *clone() const override; 0090 0091 /** 0092 Sets due date and time. 0093 0094 @param dtDue The due date/time. 0095 @param first If true and the todo recurs, the due date of the first 0096 occurrence will be set. If false and the todo recurs, the occurrence at 0097 that date/time becomes the current occurrence. If the todo does not recur, 0098 the due date of the todo will be set. 0099 */ 0100 void setDtDue(const QDateTime &dtDue, bool first = false); 0101 0102 /** 0103 Returns the todo due datetime. 0104 0105 @param first If true and the todo recurs, the due datetime of the first 0106 occurrence will be returned. If false and recurrent, the datetime of the 0107 current occurrence will be returned. If non-recurrent, the normal due 0108 datetime will be returned. 0109 @return A QDateTime containing the todo due datetime. 0110 */ 0111 Q_REQUIRED_RESULT QDateTime dtDue(bool first = false) const; 0112 0113 /** 0114 Returns if the todo has a due datetime. 0115 @return true if the todo has a due datetime; false otherwise. 0116 */ 0117 Q_REQUIRED_RESULT bool hasDueDate() const; 0118 0119 /** 0120 Returns if the todo has a start datetime. 0121 @return true if the todo has a start datetime; false otherwise. 0122 */ 0123 Q_REQUIRED_RESULT bool hasStartDate() const; 0124 0125 /** 0126 @copydoc IncidenceBase::dtStart() 0127 */ 0128 Q_REQUIRED_RESULT QDateTime dtStart() const override; 0129 0130 /** 0131 Returns the start datetime of the todo. 0132 0133 @param first If true, the start datetime of the todo will be returned; 0134 also, if the todo recurs, the start datetime of the first occurrence 0135 will be returned. 0136 If false and the todo recurs, the relative start datetime will be returned, 0137 based on the datetime returned by dtRecurrence(). 0138 @return A QDateTime for the start datetime of the todo. 0139 */ 0140 Q_REQUIRED_RESULT QDateTime dtStart(bool first) const; 0141 0142 /** 0143 Returns whether the todo is completed or not. 0144 @return true if the todo is 100% completed, has status @c StatusCompleted, 0145 or has a completed date; false otherwise. 0146 0147 @see isOverdue, isInProgress(), isOpenEnded(), isNotStarted(bool), 0148 setCompleted(), percentComplete() 0149 */ 0150 Q_REQUIRED_RESULT bool isCompleted() const; 0151 0152 /** 0153 Sets completion percentage and status. 0154 0155 @param completed If @c true, percentage complete is set to 100%, and 0156 status is set to @c StatusCompleted; the completion date is @b not set or cleared. 0157 If @c false, percentage complete is set to 0%, 0158 status is set to @c StatusNone, and the completion date is cleared. 0159 0160 0161 @see isCompleted(), percentComplete(), hasCompletedDate() 0162 */ 0163 void setCompleted(bool completed); 0164 0165 /** 0166 Returns what percentage of the to-do is completed. 0167 @return The percentage complete of the to-do as an integer between 0 and 100, inclusive. 0168 @see setPercentComplete(), isCompleted() 0169 */ 0170 Q_REQUIRED_RESULT int percentComplete() const; 0171 0172 /** 0173 Sets what percentage of the to-do is completed. 0174 0175 To prevent inconsistency, if @p percent is not 100, completed() is cleared, 0176 and if status() is StatusCompleted it is reset to StatusNone. 0177 0178 @param percent is the completion percentage. Values greater than 100 are 0179 treated as 100; values less than p are treated as 0. 0180 0181 @see isCompleted(), setCompleted() 0182 */ 0183 void setPercentComplete(int percent); 0184 0185 /** 0186 Returns the to-do was completion datetime. 0187 0188 @return A QDateTime for the completion datetime of the to-do. 0189 @see hasCompletedDate() 0190 */ 0191 Q_REQUIRED_RESULT QDateTime completed() const; 0192 0193 /** 0194 Marks this Todo, or its current recurrence, as completed. 0195 0196 If the todo does not recur, its completion percentage is set to 100%, 0197 and its completion date is set to @p completeDate. If its status is not 0198 StatusNone, it is set to StatusCompleted. 0199 0200 @note 0201 If @p completeDate is invalid, the completion date is cleared, but the 0202 todo is still "complete". 0203 0204 If the todo recurs, the first incomplete recurrence is marked complete. 0205 0206 @param completeDate is the to-do completion date. 0207 @see completed(), hasCompletedDate() 0208 */ 0209 void setCompleted(const QDateTime &completeDate); 0210 0211 /** 0212 Returns if the to-do has a completion datetime. 0213 0214 @return true if the to-do has a date associated with completion; false otherwise. 0215 @see setCompleted(), completed() 0216 */ 0217 bool hasCompletedDate() const; 0218 0219 /** 0220 Returns true, if the to-do is in-progress (started, or >0% completed); 0221 otherwise return false. If the to-do is overdue, then it is not 0222 considered to be in-progress. 0223 0224 @param first If true, the start and due dates of the todo will be used; 0225 also, if the todo recurs, the start date and due date of the first 0226 occurrence will be used. 0227 If false and the todo recurs, the relative start and due dates will be 0228 used, based on the date returned by dtRecurrence(). 0229 @see isOverdue(), isCompleted(), isOpenEnded(), isNotStarted(bool) 0230 */ 0231 Q_REQUIRED_RESULT bool isInProgress(bool first) const; 0232 0233 /** 0234 Returns true, if the to-do is open-ended (no due date); false otherwise. 0235 @see isOverdue(), isCompleted(), isInProgress(), isNotStarted(bool) 0236 */ 0237 Q_REQUIRED_RESULT bool isOpenEnded() const; 0238 0239 /** 0240 Returns true, if the to-do has yet to be started (no start date and 0% 0241 completed); otherwise return false. 0242 0243 @param first If true, the start date of the todo will be used; 0244 also, if the todo recurs, the start date of the first occurrence 0245 will be used. 0246 If false and the todo recurs, the relative start date will be used, 0247 based on the date returned by dtRecurrence(). 0248 @see isOverdue(), isCompleted(), isInProgress(), isOpenEnded() 0249 */ 0250 Q_REQUIRED_RESULT bool isNotStarted(bool first) const; 0251 0252 /** 0253 @copydoc IncidenceBase::shiftTimes() 0254 */ 0255 void shiftTimes(const QTimeZone &oldZone, const QTimeZone &newZone) override; 0256 0257 /** 0258 @copydoc IncidenceBase::setAllDay(). 0259 */ 0260 void setAllDay(bool allDay) override; 0261 0262 /** 0263 Identify the earliest uncompleted occurrence of a recurring Todo. 0264 0265 @param dt Normally, the start date-time of the occurrence. 0266 For backwards compatibility, if the Todo does not have a @c dtStart() 0267 then pass the occurrence's due date-time. 0268 */ 0269 void setDtRecurrence(const QDateTime &dt); 0270 0271 /** 0272 Returns an identifier for the earliest uncompleted occurrence of a 0273 recurring Todo. 0274 0275 @note 0276 Do not rely on the returned value to determine whether the Todo is 0277 completed; use @c isCompleted() instead. 0278 */ 0279 Q_REQUIRED_RESULT QDateTime dtRecurrence() const; 0280 0281 /** 0282 Returns true if the @p date specified is one on which the to-do will 0283 recur. Todos are a special case, hence the overload. It adds an extra 0284 check, which make it return false if there's an occurrence between 0285 the recur start and today. 0286 0287 @param date is the date to check. 0288 @param timeZone is the time zone 0289 */ 0290 bool recursOn(const QDate &date, const QTimeZone &timeZone) const override; 0291 0292 /** 0293 Returns true if this todo is overdue (e.g. due date is lower than today 0294 and not completed), else false. 0295 @see isCompleted(), isInProgress(), isOpenEnded(), isNotStarted(bool) 0296 */ 0297 bool isOverdue() const; 0298 0299 /** 0300 @copydoc IncidenceBase::dateTime() 0301 */ 0302 Q_REQUIRED_RESULT QDateTime dateTime(DateTimeRole role) const override; 0303 0304 /** 0305 @copydoc IncidenceBase::setDateTime() 0306 */ 0307 void setDateTime(const QDateTime &dateTime, DateTimeRole role) override; 0308 0309 /** 0310 @copydoc IncidenceBase::mimeType() 0311 */ 0312 Q_REQUIRED_RESULT QLatin1String mimeType() const override; 0313 0314 /** 0315 @copydoc Incidence::iconName() 0316 */ 0317 Q_REQUIRED_RESULT QLatin1String iconName(const QDateTime &recurrenceId = {}) const override; 0318 0319 /** 0320 @copydoc 0321 Incidence::supportsGroupwareCommunication() 0322 */ 0323 bool supportsGroupwareCommunication() const override; 0324 0325 /** 0326 Returns the Akonadi specific sub MIME type of a KCalendarCore::Todo. 0327 */ 0328 Q_REQUIRED_RESULT static QLatin1String todoMimeType(); 0329 0330 protected: 0331 /** 0332 Compare this with @p todo for equality. 0333 @param todo is the to-do to compare. 0334 */ 0335 bool equals(const IncidenceBase &todo) const override; 0336 0337 /** 0338 @copydoc IncidenceBase::assign() 0339 */ 0340 IncidenceBase &assign(const IncidenceBase &other) override; 0341 0342 /** 0343 @copydoc IncidenceBase::virtual_hook() 0344 */ 0345 void virtual_hook(VirtualHook id, void *data) override; 0346 0347 private: 0348 /** 0349 @copydoc IncidenceBase::accept() 0350 */ 0351 bool accept(Visitor &v, const IncidenceBase::Ptr &incidence) override; 0352 0353 /** 0354 Disabled, otherwise could be dangerous if you subclass Todo. 0355 Use IncidenceBase::operator= which is safe because it calls 0356 virtual function assign(). 0357 @param other is another Todo object to assign to this one. 0358 */ 0359 Todo &operator=(const Todo &other) = delete; 0360 0361 // For polymorphic serialization 0362 void serialize(QDataStream &out) const override; 0363 void deserialize(QDataStream &in) override; 0364 0365 //@cond PRIVATE 0366 Q_DECLARE_PRIVATE(Todo) 0367 //@endcond 0368 }; 0369 0370 } // namespace KCalendarCore 0371 0372 //@cond PRIVATE 0373 Q_DECLARE_TYPEINFO(KCalendarCore::Todo::Ptr, Q_RELOCATABLE_TYPE); 0374 Q_DECLARE_METATYPE(KCalendarCore::Todo::Ptr) 0375 Q_DECLARE_METATYPE(KCalendarCore::Todo *) 0376 //@endcond 0377 0378 #endif