File indexing completed on 2024-04-28 15:19:06
0001 /* 0002 This file is part of the kcalcore library. 0003 0004 SPDX-FileCopyrightText: 2001-2003 Cornelius Schumacher <schumacher@kde.org> 0005 SPDX-FileCopyrightText: 2003-2004 Reinhold Kainhofer <reinhold@kainhofer.com> 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 Incidence class. 0013 0014 @author Cornelius Schumacher \<schumacher@kde.org\> 0015 @author Reinhold Kainhofer \<reinhold@kainhofer.com\> 0016 */ 0017 0018 #ifndef KCALCORE_INCIDENCE_H 0019 #define KCALCORE_INCIDENCE_H 0020 0021 #include "alarm.h" 0022 #include "attachment.h" 0023 #include "conference.h" 0024 #include "incidencebase.h" 0025 #include "kcalendarcore_export.h" 0026 #include "recurrence.h" 0027 0028 #include <QMetaType> 0029 0030 //@cond PRIVATE 0031 // Value used to signal invalid/unset latitude or longitude. 0032 #define INVALID_LATLON 255.0 // krazy:exclude=defines (part of the API) 0033 //@endcond 0034 0035 namespace KCalendarCore 0036 { 0037 0038 class IncidencePrivate; 0039 0040 /** 0041 @brief 0042 Provides the abstract base class common to non-FreeBusy (Events, To-dos, 0043 Journals) calendar components known as incidences. 0044 0045 Several properties are not allowed for VFREEBUSY objects (see rfc:2445), 0046 so they are not in IncidenceBase. The hierarchy is: 0047 0048 IncidenceBase 0049 + FreeBusy 0050 + Incidence 0051 + Event 0052 + Todo 0053 + Journal 0054 0055 So IncidenceBase contains all properties that are common to all classes, 0056 and Incidence contains all additional properties that are common to 0057 Events, Todos and Journals, but are not allowed for FreeBusy entries. 0058 */ 0059 class KCALENDARCORE_EXPORT Incidence : public IncidenceBase, public Recurrence::RecurrenceObserver 0060 { 0061 Q_GADGET 0062 Q_PROPERTY(QString description READ description WRITE setDescription) 0063 Q_PROPERTY(QString summary READ summary WRITE setSummary) 0064 Q_PROPERTY(QString location READ location WRITE setLocation) 0065 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 89) 0066 Q_PROPERTY(bool hasGeo READ hasGeo WRITE setHasGeo) 0067 #else 0068 Q_PROPERTY(bool hasGeo READ hasGeo) 0069 #endif 0070 Q_PROPERTY(float geoLatitude READ geoLatitude WRITE setGeoLatitude) 0071 Q_PROPERTY(float geoLongitude READ geoLongitude WRITE setGeoLongitude) 0072 Q_PROPERTY(QStringList categories READ categories WRITE setCategories) 0073 Q_PROPERTY(int priority READ priority WRITE setPriority) 0074 Q_PROPERTY(QDateTime created READ created WRITE setCreated) 0075 Q_PROPERTY(KCalendarCore::Incidence::Secrecy secrecy READ secrecy WRITE setSecrecy) 0076 Q_PROPERTY(KCalendarCore::Incidence::Status status READ status WRITE setStatus) 0077 Q_PROPERTY(QVariantList attachments READ attachmentsVariant) 0078 Q_PROPERTY(QVariantList conferences READ conferencesVariant) 0079 public: 0080 /** 0081 The different types of overall incidence status or confirmation. 0082 The meaning is specific to the incidence type in context. 0083 */ 0084 enum Status { 0085 StatusNone, /**< No status */ 0086 StatusTentative, /**< event is tentative */ 0087 StatusConfirmed, /**< event is definite */ 0088 StatusCompleted, /**< to-do completed */ 0089 StatusNeedsAction, /**< to-do needs action */ 0090 StatusCanceled, /**< event or to-do canceled; journal removed */ 0091 StatusInProcess, /**< to-do in process */ 0092 StatusDraft, /**< journal is draft */ 0093 StatusFinal, /**< journal is final */ 0094 StatusX, /**< a non-standard status string */ 0095 }; 0096 Q_ENUM(Status) 0097 0098 /** 0099 The different types of incidence access classifications. 0100 */ 0101 enum Secrecy { 0102 SecrecyPublic, /**< Not secret (default) */ 0103 SecrecyPrivate, /**< Secret to the owner */ 0104 SecrecyConfidential, /**< Secret to the owner and some others */ 0105 }; 0106 Q_ENUM(Secrecy) 0107 0108 /** 0109 The different types of RELTYPE values specified by the RFC. 0110 Only RelTypeParent is supported for now. 0111 */ 0112 enum RelType { 0113 RelTypeParent, /**< The related incidence is a parent. */ 0114 RelTypeChild, /**< The related incidence is a child. */ 0115 RelTypeSibling, /**< The related incidence is a peer. */ 0116 }; 0117 0118 /** 0119 A shared pointer to an Incidence. 0120 */ 0121 typedef QSharedPointer<Incidence> Ptr; 0122 0123 /** 0124 List of incidences. 0125 */ 0126 typedef QVector<Ptr> List; 0127 0128 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 91) 0129 /** 0130 Constructs an empty incidence. 0131 @deprecated Use Incidence(IncidencePrivate *p). 0132 */ 0133 Incidence(); 0134 #else 0135 Incidence() = delete; 0136 #endif 0137 0138 /** 0139 Constructs an empty incidence. 0140 @param p (non-null) a Private data object provided by the instantiated 0141 class (Event, Todo, Journal, FreeBusy). It passes ownership of the object 0142 to IncidenceBase. 0143 */ 0144 Incidence(IncidencePrivate *p); 0145 0146 /** 0147 Destroys an incidence. 0148 */ 0149 ~Incidence() override; 0150 0151 /** 0152 Returns an exact copy of this incidence. The returned object is owned 0153 by the caller. 0154 0155 Dirty fields are cleared. 0156 */ 0157 virtual Incidence *clone() const = 0; 0158 0159 /** 0160 Returns a unique identifier for a specific instance of an incidence. 0161 0162 Due to the recurrence-id, the uid is not unique for a KCalendarCore::Incidence. 0163 @since 4.11 0164 */ 0165 Q_REQUIRED_RESULT QString instanceIdentifier() const; 0166 0167 /** 0168 Set readonly state of incidence. 0169 0170 @param readonly If true, the incidence is set to readonly, if false the 0171 incidence is set to readwrite. 0172 */ 0173 void setReadOnly(bool readonly) override; 0174 0175 /** 0176 @copydoc IncidenceBase::setLastModified(). 0177 */ 0178 void setLastModified(const QDateTime &lm) override; 0179 0180 /** 0181 Set localOnly state of incidence. 0182 A local only incidence can be updated but it will not increase the revision 0183 number neither the modified date. 0184 0185 @param localonly If true, the incidence is set to localonly, if false the 0186 incidence is set to normal stat. 0187 */ 0188 void setLocalOnly(bool localonly); 0189 0190 /** 0191 Get the localOnly status. 0192 @return true if Local only, false otherwise. 0193 0194 @see setLocalOnly() 0195 */ 0196 Q_REQUIRED_RESULT bool localOnly() const; 0197 0198 /** 0199 @copydoc IncidenceBase::setAllDay(). 0200 */ 0201 void setAllDay(bool allDay) override; 0202 0203 /** 0204 Recreate incidence. The incidence is made a new unique incidence, but already stored 0205 information is preserved. Sets unique id, creation date, last 0206 modification date and revision number. 0207 */ 0208 void recreate(); 0209 0210 /** 0211 Sets the incidence creation date/time. It is stored as a UTC date/time. 0212 0213 @param dt is the creation date/time. 0214 @see created(). 0215 */ 0216 void setCreated(const QDateTime &dt); 0217 0218 /** 0219 Returns the incidence creation date/time. 0220 @see setCreated(). 0221 */ 0222 Q_REQUIRED_RESULT QDateTime created() const; 0223 0224 /** 0225 Sets the number of revisions this incidence has seen. 0226 0227 @param rev is the incidence revision number. 0228 @see revision(). 0229 */ 0230 void setRevision(int rev); 0231 0232 /** 0233 Returns the number of revisions this incidence has seen. 0234 @see setRevision(). 0235 */ 0236 Q_REQUIRED_RESULT int revision() const; 0237 0238 /** 0239 Sets the incidence starting date/time. 0240 0241 @param dt is the starting date/time. 0242 @see IncidenceBase::dtStart(). 0243 */ 0244 void setDtStart(const QDateTime &dt) override; 0245 0246 /** 0247 @copydoc IncidenceBase::shiftTimes() 0248 */ 0249 void shiftTimes(const QTimeZone &oldZone, const QTimeZone &newZone) override; 0250 0251 /** 0252 Sets the incidence description. 0253 0254 @param description is the incidence description string. 0255 @param isRich if true indicates the description string contains richtext. 0256 @see description(). 0257 */ 0258 void setDescription(const QString &description, bool isRich); 0259 0260 /** 0261 Sets the incidence description and tries to guess if the description 0262 is rich text. 0263 0264 @param description is the incidence description string. 0265 @see description(). 0266 */ 0267 void setDescription(const QString &description); 0268 0269 /** 0270 Returns the incidence description. 0271 @see setDescription(). 0272 @see richDescription(). 0273 */ 0274 Q_REQUIRED_RESULT QString description() const; 0275 0276 /** 0277 Returns the incidence description in rich text format. 0278 @see setDescription(). 0279 @see description(). 0280 */ 0281 Q_REQUIRED_RESULT QString richDescription() const; 0282 0283 /** 0284 Returns true if incidence description contains RichText; false otherwise. 0285 @see setDescription(), description(). 0286 */ 0287 Q_REQUIRED_RESULT bool descriptionIsRich() const; 0288 0289 /** 0290 Sets the incidence summary. 0291 0292 @param summary is the incidence summary string. 0293 @param isRich if true indicates the summary string contains richtext. 0294 @see summary(). 0295 */ 0296 void setSummary(const QString &summary, bool isRich); 0297 0298 /** 0299 Sets the incidence summary and tries to guess if the summary is richtext. 0300 0301 @param summary is the incidence summary string. 0302 @see summary(). 0303 */ 0304 void setSummary(const QString &summary); 0305 0306 /** 0307 Returns the incidence summary. 0308 @see setSummary(). 0309 @see richSummary(). 0310 */ 0311 Q_REQUIRED_RESULT QString summary() const; 0312 0313 /** 0314 Returns the incidence summary in rich text format. 0315 @see setSummary(). 0316 @see summary(). 0317 */ 0318 Q_REQUIRED_RESULT QString richSummary() const; 0319 0320 /** 0321 Returns true if incidence summary contains RichText; false otherwise. 0322 @see setSummary(), summary(). 0323 */ 0324 Q_REQUIRED_RESULT bool summaryIsRich() const; 0325 0326 /** 0327 Sets the incidence location. Do _not_ use with journals. 0328 0329 @param location is the incidence location string. 0330 @param isRich if true indicates the location string contains richtext. 0331 @see location(). 0332 */ 0333 void setLocation(const QString &location, bool isRich); 0334 0335 /** 0336 Sets the incidence location and tries to guess if the location is 0337 richtext. Do _not_ use with journals. 0338 0339 @param location is the incidence location string. 0340 @see location(). 0341 */ 0342 void setLocation(const QString &location); 0343 0344 /** 0345 Returns the incidence location. Do _not_ use with journals. 0346 @see setLocation(). 0347 @see richLocation(). 0348 */ 0349 Q_REQUIRED_RESULT QString location() const; 0350 0351 /** 0352 Returns the incidence location in rich text format. 0353 @see setLocation(). 0354 @see location(). 0355 */ 0356 Q_REQUIRED_RESULT QString richLocation() const; 0357 0358 /** 0359 Returns true if incidence location contains RichText; false otherwise. 0360 @see setLocation(), location(). 0361 */ 0362 Q_REQUIRED_RESULT bool locationIsRich() const; 0363 0364 /** 0365 Sets the incidence category list. 0366 0367 @param categories is a list of category strings. 0368 @see setCategories( const QString &), categories(). 0369 */ 0370 void setCategories(const QStringList &categories); 0371 0372 /** 0373 Sets the incidence category list based on a comma delimited string. 0374 0375 @param catStr is a QString containing a list of categories which 0376 are delimited by a comma character. 0377 @see setCategories( const QStringList &), categories(). 0378 */ 0379 void setCategories(const QString &catStr); 0380 0381 /** 0382 Returns the incidence categories as a list of strings. 0383 @see setCategories( const QStringList &), setCategories( const QString &). 0384 */ 0385 Q_REQUIRED_RESULT QStringList categories() const; 0386 0387 /** 0388 Returns the incidence categories as a comma separated string. 0389 @see categories(). 0390 */ 0391 Q_REQUIRED_RESULT QString categoriesStr() const; 0392 0393 /** 0394 Relates another incidence to this one, by UID. This function should only 0395 be used when constructing a calendar before the related incidence exists. 0396 0397 @param uid is a QString containing a UID for another incidence. 0398 @param relType specifies the relation type. 0399 0400 @warning KCalendarCore only supports one related-to field per reltype for now. 0401 0402 @see relatedTo(). 0403 */ 0404 void setRelatedTo(const QString &uid, RelType relType = RelTypeParent); 0405 0406 /** 0407 Returns a UID string for the incidence that is related to this one. 0408 This function should only be used when constructing a calendar before 0409 the related incidence exists. 0410 0411 @warning KCalendarCore only supports one related-to field per reltype for now. 0412 0413 @param relType specifies the relation type. 0414 0415 @see setRelatedTo(). 0416 */ 0417 Q_REQUIRED_RESULT QString relatedTo(RelType relType = RelTypeParent) const; 0418 0419 /** 0420 Set the incidence color, as added in RFC7986. 0421 0422 @param colorName a named color as defined in CSS3 color name, see 0423 https://www.w3.org/TR/css-color-3/#svg-color. 0424 @since: 5.76 0425 */ 0426 void setColor(const QString &colorName); 0427 0428 /** 0429 Returns the color, if any is defined, for this incidence. 0430 0431 @since: 5.76 0432 */ 0433 Q_REQUIRED_RESULT QString color() const; 0434 0435 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 0436 // %%%%% Convenience wrappers for property handling 0437 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 0438 /** 0439 Returns true if the alternative (=text/html) description is 0440 available. 0441 @see setAltDescription(), altDescription() 0442 */ 0443 Q_REQUIRED_RESULT bool hasAltDescription() const; 0444 /** 0445 Sets the incidence's alternative (=text/html) description. If 0446 the text is empty, the property is removed. 0447 0448 @param altdescription is the incidence altdescription string. 0449 @see altAltdescription(). 0450 */ 0451 void setAltDescription(const QString &altdescription); 0452 0453 /** 0454 Returns the incidence alternative (=text/html) description. 0455 @see setAltDescription(). 0456 */ 0457 Q_REQUIRED_RESULT QString altDescription() const; 0458 0459 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 0460 // %%%%% Recurrence-related methods 0461 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 0462 0463 /** 0464 Returns the recurrence rule associated with this incidence. If there is 0465 none, returns an appropriate (non-0) object. 0466 */ 0467 Recurrence *recurrence() const; 0468 0469 /** 0470 Removes all recurrence and exception rules and dates. 0471 */ 0472 void clearRecurrence(); 0473 0474 /** 0475 @copydoc Recurrence::recurs() 0476 */ 0477 Q_REQUIRED_RESULT bool recurs() const; 0478 0479 /** 0480 @copydoc Recurrence::recurrenceType() 0481 */ 0482 Q_REQUIRED_RESULT ushort recurrenceType() const; 0483 0484 /** 0485 @copydoc Recurrence::recursOn() 0486 */ 0487 virtual bool recursOn(const QDate &date, const QTimeZone &timeZone) const; 0488 0489 /** 0490 @copydoc Recurrence::recursAt() 0491 */ 0492 Q_REQUIRED_RESULT bool recursAt(const QDateTime &dt) const; 0493 0494 /** 0495 Calculates the start date/time for all recurrences that happen at some 0496 time on the given date (might start before that date, but end on or 0497 after the given date). 0498 0499 @param date the date when the incidence should occur 0500 @param timeSpec time specification for @p date. 0501 @return the start date/time of all occurrences that overlap with the 0502 given date; an empty list if the incidence does not overlap with the 0503 date at all. 0504 */ 0505 virtual QList<QDateTime> startDateTimesForDate(const QDate &date, const QTimeZone &timeZone) const; 0506 0507 /** 0508 Calculates the start date/time for all recurrences that happen at the 0509 given time. 0510 0511 @param datetime the date/time when the incidence should occur. 0512 @return the start date/time of all occurrences that overlap with the 0513 given date/time; an empty list if the incidence does not happen at the 0514 given time at all. 0515 */ 0516 Q_REQUIRED_RESULT virtual QList<QDateTime> startDateTimesForDateTime(const QDateTime &datetime) const; 0517 0518 /** 0519 Returns the end date/time of the incidence occurrence if it starts at 0520 specified date/time. 0521 0522 @param startDt is the specified starting date/time. 0523 @return the corresponding end date/time for the occurrence; or the start 0524 date/time if the end date/time is invalid; or the end date/time if 0525 the start date/time is invalid. 0526 */ 0527 Q_REQUIRED_RESULT virtual QDateTime endDateForStart(const QDateTime &startDt) const; 0528 0529 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 0530 // %%%%% Attachment-related methods 0531 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 0532 0533 /** 0534 Adds an attachment to the incidence. 0535 0536 @param attachment a valid Attachment object. 0537 */ 0538 void addAttachment(const Attachment &attachment); 0539 0540 /** 0541 Removes all attachments of the specified MIME type from the incidence. 0542 The memory used by all the removed attachments is freed. 0543 0544 @param mime is a QString containing the MIME type. 0545 @see deleteAttachment(). 0546 */ 0547 void deleteAttachments(const QString &mime); 0548 0549 /** 0550 Returns a list of all incidence attachments. 0551 @see attachments( const QString &). 0552 */ 0553 Q_REQUIRED_RESULT Attachment::List attachments() const; 0554 0555 /** 0556 Returns a list of all incidence attachments with the specified MIME type. 0557 0558 @param mime is a QString containing the MIME type. 0559 @see attachments(). 0560 */ 0561 Q_REQUIRED_RESULT Attachment::List attachments(const QString &mime) const; 0562 0563 /** 0564 Removes all attachments and frees the memory used by them. 0565 @see deleteAttachments( const QString &). 0566 */ 0567 void clearAttachments(); 0568 0569 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 0570 // %%%%% Secrecy and Status methods 0571 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 0572 0573 /** 0574 Sets the incidence #Secrecy. 0575 0576 @param secrecy is the incidence #Secrecy to set. 0577 @see secrecy(), secrecyStr(). 0578 */ 0579 void setSecrecy(Secrecy secrecy); 0580 0581 /** 0582 Returns the incidence #Secrecy. 0583 @see setSecrecy(), secrecyStr(). 0584 */ 0585 Q_REQUIRED_RESULT Secrecy secrecy() const; 0586 0587 /** 0588 Sets the incidence status to a standard #Status value. 0589 Events, Todos, and Journals each have a different set of 0590 valid statuses. Note that StatusX cannot be specified. 0591 Invalid statuses are logged and ignored. 0592 0593 @param status is the incidence #Status to set. 0594 @see status(), setCustomStatus(). 0595 */ 0596 void setStatus(Status status); 0597 0598 /** 0599 Sets the incidence #Status to a non-standard status value. 0600 0601 @param status is a non-standard status string. If empty, 0602 the incidence #Status will be set to StatusNone. 0603 @see setStatus(), status() customStatus(). 0604 */ 0605 void setCustomStatus(const QString &status); 0606 0607 /** 0608 Returns the non-standard status value. 0609 @see setCustomStatus(). 0610 */ 0611 Q_REQUIRED_RESULT QString customStatus() const; 0612 0613 /** 0614 Returns the incidence #Status. 0615 @see setStatus(), setCustomStatus(), statusStr(). 0616 */ 0617 Q_REQUIRED_RESULT Status status() const; 0618 0619 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 0620 // %%%%% Other methods 0621 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 0622 0623 /** 0624 Sets a list of incidence resources. (Note: resources in this context 0625 means items used by the incidence such as money, fuel, hours, etc). 0626 0627 @param resources is a list of resource strings. 0628 @see resources(). 0629 */ 0630 void setResources(const QStringList &resources); 0631 0632 /** 0633 Returns the incidence resources as a list of strings. 0634 @see setResources(). 0635 */ 0636 Q_REQUIRED_RESULT QStringList resources() const; 0637 0638 /** 0639 Sets the incidences priority. The priority must be an integer value 0640 between 0 and 9, where 0 is undefined, 1 is the highest, and 9 is the 0641 lowest priority (decreasing order). 0642 0643 @param priority is the incidence priority to set. 0644 @see priority(). 0645 */ 0646 void setPriority(int priority); 0647 0648 /** 0649 Returns the incidence priority. 0650 @see setPriority(). 0651 */ 0652 Q_REQUIRED_RESULT int priority() const; 0653 0654 /** 0655 Returns true if the incidence has geo data, otherwise return false. 0656 @see setHasGeo(), setGeoLatitude(float), setGeoLongitude(float). 0657 */ 0658 Q_REQUIRED_RESULT bool hasGeo() const; 0659 0660 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 89) 0661 /** 0662 Sets if the incidence has geo data. 0663 @param hasGeo if true, latitude and longitude must be set to valid values. 0664 If false, geoLatitude() and geoLongitude() will return INVALID_LATLON. 0665 @deprecated since 5.89. Use setGeoLatitude() and setGeoLongitude(). 0666 @see hasGeo(), geoLatitude(), geoLongitude(). 0667 */ 0668 KCALENDARCORE_DEPRECATED_VERSION(5, 89, "Use setGeoLatitude() and setGeoLongitude()") 0669 void setHasGeo(bool hasGeo); 0670 #endif 0671 0672 /** 0673 Set the incidence's geoLatitude. 0674 @param geolatitude is the incidence geolatitude to set; a value between -90.0 and 90.0, 0675 or INVALID_LATLON (or NaN, which is treated as INVALID_LATLON). 0676 @see geoLatitude(). 0677 */ 0678 void setGeoLatitude(float geolatitude); 0679 0680 /** 0681 Returns the incidence's geoLatitude as a value between -90.0 and 90.0 or INVALID_LATLON. 0682 If either of geoLatitude() and geoLongitude() are INVALID_LATLON, then both are, and hasGeo() is false. 0683 @return incidences geolatitude value 0684 @see setGeoLatitude(). 0685 */ 0686 Q_REQUIRED_RESULT float geoLatitude() const; 0687 0688 /** 0689 Set the incidence's geoLongitude. 0690 @param geolongitude is the incidence geolongitude to set; a value between -180.0 and 180.0, 0691 or INVALID_LATLON (or NaN, which is treated as INVALID_LATLON). 0692 @see geoLongitude(). 0693 */ 0694 void setGeoLongitude(float geolongitude); 0695 0696 /** 0697 Returns the incidence's geoLongitude as a value between -180.0 and 180.0 or INVALID_LATLON. 0698 If either of geoLatitude() and geoLongitude() are INVALID_LATLON, then both are, and hasGeo() is false. 0699 @return incidences geolongitude value 0700 @see setGeoLongitude(). 0701 */ 0702 Q_REQUIRED_RESULT float geoLongitude() const; 0703 0704 /** 0705 Returns true if the incidence has recurrenceId, otherwise return false. 0706 @see setRecurrenceId(QDateTime) 0707 */ 0708 Q_REQUIRED_RESULT bool hasRecurrenceId() const; 0709 0710 /** 0711 Set the incidences recurrenceId. 0712 This field indicates that this is an exception to a recurring incidence. 0713 The uid of this incidence MUST be the same as the one of the recurring main incidence. 0714 @param recurrenceId is the incidence recurrenceId to set 0715 @see recurrenceId(). 0716 */ 0717 void setRecurrenceId(const QDateTime &recurrenceId); 0718 0719 /** 0720 Returns the incidence recurrenceId. 0721 @return incidences recurrenceId value 0722 @see setRecurrenceId(). 0723 */ 0724 Q_REQUIRED_RESULT QDateTime recurrenceId() const override; 0725 0726 /** 0727 Set to true if the exception also applies to all future occurrences. 0728 This option is only relevant if the incidence has a recurrenceId set. 0729 @param thisAndFuture value 0730 @see thisAndFuture(), setRecurrenceId() 0731 @since 4.11 0732 */ 0733 void setThisAndFuture(bool thisAndFuture); 0734 0735 /** 0736 Returns true if the exception also applies to all future occurrences. 0737 @return incidences thisAndFuture value 0738 @see setThisAndFuture() 0739 @since 4.11 0740 */ 0741 Q_REQUIRED_RESULT bool thisAndFuture() const; 0742 0743 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 0744 // %%%%% Alarm-related methods 0745 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 0746 0747 /** 0748 Returns a list of all incidence alarms. 0749 */ 0750 Q_REQUIRED_RESULT Alarm::List alarms() const; 0751 0752 /** 0753 Create a new incidence alarm. 0754 */ 0755 Alarm::Ptr newAlarm(); 0756 0757 /** 0758 Adds an alarm to the incidence. 0759 0760 @param alarm is a pointer to a valid Alarm object. 0761 @see removeAlarm(). 0762 */ 0763 void addAlarm(const Alarm::Ptr &alarm); 0764 0765 /** 0766 Removes the specified alarm from the incidence. 0767 0768 @param alarm is a pointer to a valid Alarm object. 0769 @see addAlarm(). 0770 */ 0771 void removeAlarm(const Alarm::Ptr &alarm); 0772 0773 /** 0774 Removes all alarms. 0775 @see removeAlarm(). 0776 */ 0777 void clearAlarms(); 0778 0779 /** 0780 Returns true if any of the incidence alarms are enabled; false otherwise. 0781 */ 0782 Q_REQUIRED_RESULT bool hasEnabledAlarms() const; 0783 0784 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 0785 // %%%%% Conferences-related method 0786 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 0787 0788 /** 0789 * Returns list of all incidence conferencing methods. 0790 * @since 5.77 0791 */ 0792 Q_REQUIRED_RESULT Conference::List conferences() const; 0793 0794 /** 0795 * Replaces all conferences in the incidence with given @p conferences 0796 * 0797 * @param conferences New conferences to store in the incidence. 0798 * @since 5.77 0799 */ 0800 void setConferences(const Conference::List &conferences); 0801 0802 /** 0803 * Adds a conference to the incidence. 0804 * 0805 * @param conferene A conference to add. 0806 * @since 5.77 0807 */ 0808 void addConference(const Conference &conference); 0809 0810 /** 0811 * Removes all conferences from the incidence. 0812 * @since 5.77 0813 */ 0814 void clearConferences(); 0815 0816 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 0817 // %%%%% Other methods 0818 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 0819 0820 /** 0821 Set the incidence scheduling ID. Do _not_ use with journals. 0822 This is used for accepted invitations as the place to store the UID 0823 of the invitation. It is later used again if updates to the 0824 invitation comes in. 0825 If we did not set a new UID on incidences from invitations, we can 0826 end up with more than one resource having events with the same UID, 0827 if you have access to other peoples resources. 0828 0829 While constructing an incidence, when setting the scheduling ID, 0830 you will always want to set the incidence UID too. Instead of calling 0831 setUID() separately, you can pass the UID through @p uid so both 0832 members are changed in one atomic operation ( don't forget that 0833 setUID() emits incidenceUpdated() and whoever catches that signal 0834 will have an half-initialized incidence, therefore, always set 0835 the schedulingID and UID at the same time, and never with two separate 0836 calls). 0837 0838 @param sid is a QString containing the scheduling ID. 0839 @param uid is a QString containing the incidence UID to set, if not 0840 specified, the current UID isn't changed, and this parameter 0841 is ignored. 0842 @see schedulingID(). 0843 */ 0844 void setSchedulingID(const QString &sid, const QString &uid = QString()); 0845 0846 /** 0847 Returns the incidence scheduling ID. Do _not_ use with journals. 0848 If a scheduling ID is not set, then return the incidence UID. 0849 @see setSchedulingID(). 0850 */ 0851 Q_REQUIRED_RESULT QString schedulingID() const; 0852 0853 /** 0854 Observer interface for the recurrence class. If the recurrence is 0855 changed, this method will be called for the incidence the recurrence 0856 object belongs to. 0857 0858 @param recurrence is a pointer to a valid Recurrence object. 0859 */ 0860 void recurrenceUpdated(Recurrence *recurrence) override; 0861 0862 /** 0863 Returns the name of the icon that best represents this incidence. 0864 0865 @param recurrenceId Some recurring incidences might use a different icon, 0866 for example, completed to-do occurrences. Use this parameter to identify 0867 the specific occurrence in a recurring serie. 0868 */ 0869 virtual QLatin1String iconName(const QDateTime &recurrenceId = {}) const = 0; 0870 0871 /** 0872 * Returns true if the incidence type supports groupware communication. 0873 * @since 4.10 0874 */ 0875 virtual bool supportsGroupwareCommunication() const = 0; 0876 0877 /** 0878 Returns the list of possible mime types in an Incidence object: 0879 "text/calendar" 0880 "application/x-vnd.akonadi.calendar.event" 0881 "application/x-vnd.akonadi.calendar.todo" 0882 "application/x-vnd.akonadi.calendar.journal" 0883 0884 @since 4.12 0885 */ 0886 Q_REQUIRED_RESULT static QStringList mimeTypes(); 0887 0888 protected: 0889 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 91) 0890 /** 0891 Copy constructor. 0892 @param other is the incidence to copy. 0893 @deprecated Use Incidence(const Incidence &other, IncidencePrivate *p). 0894 */ 0895 Incidence(const Incidence &other); 0896 #else 0897 Incidence(const Incidence &) = delete; 0898 #endif 0899 0900 /** 0901 @param other is the incidence to copy. 0902 @param p (non-null) a Private data object provided by the instantiated 0903 class (Event, Todo, Journal, FreeBusy). It passes ownership of the object 0904 to IncidenceBase. 0905 */ 0906 Incidence(const Incidence &other, IncidencePrivate *p); 0907 0908 /** 0909 Compares this with Incidence @p incidence for equality. 0910 @param incidence is the Incidence to compare against. 0911 @return true if the incidences are equal; false otherwise. 0912 */ 0913 bool equals(const IncidenceBase &incidence) const override; 0914 0915 /** 0916 @copydoc IncidenceBase::assign() 0917 */ 0918 IncidenceBase &assign(const IncidenceBase &other) override; 0919 0920 void serialize(QDataStream &out) const override; 0921 void deserialize(QDataStream &in) override; 0922 0923 private: 0924 /** 0925 Disabled, not polymorphic. 0926 Use IncidenceBase::operator= which is safe because it calls 0927 virtual function assign. 0928 @param other is another Incidence object to assign to this one. 0929 */ 0930 Incidence &operator=(const Incidence &other); 0931 0932 Q_DECL_HIDDEN QVariantList attachmentsVariant() const; 0933 Q_DECL_HIDDEN QVariantList conferencesVariant() const; 0934 0935 protected: 0936 Q_DECLARE_PRIVATE(Incidence) 0937 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 91) 0938 KCALENDARCORE_DEPRECATED_VERSION(5, 91, "Do not use") 0939 IncidencePrivate *const _ = nullptr; // TODO KF6 remove. ABI compatibility hack. 0940 #endif 0941 }; 0942 0943 } 0944 0945 //@cond PRIVATE 0946 inline uint qHash(const QSharedPointer<KCalendarCore::Incidence> &key) 0947 { 0948 return qHash(key.data()); 0949 } 0950 //@endcond 0951 0952 //@cond PRIVATE 0953 Q_DECLARE_TYPEINFO(KCalendarCore::Incidence::Ptr, Q_MOVABLE_TYPE); 0954 Q_DECLARE_METATYPE(KCalendarCore::Incidence *) 0955 //@endcond 0956 0957 #endif