1 /*
2 This file is part of the kcalcore library.
3
4 SPDX-FileCopyrightText: 2001-2003 Cornelius Schumacher <schumacher@kde.org>
5 SPDX-FileCopyrightText: 2003-2004 Reinhold Kainhofer <reinhold@kainhofer.com>
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 Incidence class.
13
14 @author Cornelius Schumacher \<schumacher@kde.org\>
15 @author Reinhold Kainhofer \<reinhold@kainhofer.com\>
16 */
17
18 #ifndef KCALCORE_INCIDENCE_H
19 #define KCALCORE_INCIDENCE_H
20
21 #include "alarm.h"
22 #include "attachment.h"
23 #include "conference.h"
24 #include "incidencebase.h"
25 #include "kcalendarcore_export.h"
26 #include "recurrence.h"
27
28 #include <QMetaType>
29
30 //@cond PRIVATE
31 // Value used to signal invalid/unset latitude or longitude.
32 #define INVALID_LATLON 255.0 // krazy:exclude=defines (part of the API)
33 //@endcond
34
35 namespace KCalendarCore
36 {
37
38 class IncidencePrivate;
39
40 /**
41 @brief
42 Provides the abstract base class common to non-FreeBusy (Events, To-dos,
43 Journals) calendar components known as incidences.
44
45 Several properties are not allowed for VFREEBUSY objects (see rfc:2445),
46 so they are not in IncidenceBase. The hierarchy is:
47
48 IncidenceBase
49 + FreeBusy
50 + Incidence
51 + Event
52 + Todo
53 + Journal
54
55 So IncidenceBase contains all properties that are common to all classes,
56 and Incidence contains all additional properties that are common to
57 Events, Todos and Journals, but are not allowed for FreeBusy entries.
58 */
59 class KCALENDARCORE_EXPORT Incidence : public IncidenceBase, public Recurrence::RecurrenceObserver
60 {
61 Q_GADGET
62 Q_PROPERTY(QString description READ description WRITE setDescription)
63 Q_PROPERTY(QString summary READ summary WRITE setSummary)
64 Q_PROPERTY(QString location READ location WRITE setLocation)
65 Q_PROPERTY(bool hasGeo READ hasGeo WRITE setHasGeo)
66 Q_PROPERTY(float geoLatitude READ geoLatitude WRITE setGeoLatitude)
67 Q_PROPERTY(float geoLongitude READ geoLongitude WRITE setGeoLongitude)
68 Q_PROPERTY(QStringList categories READ categories WRITE setCategories)
69 Q_PROPERTY(int priority READ priority WRITE setPriority)
70 Q_PROPERTY(QDateTime created READ created WRITE setCreated)
71 Q_PROPERTY(KCalendarCore::Incidence::Secrecy secrecy READ secrecy WRITE setSecrecy)
72 Q_PROPERTY(KCalendarCore::Incidence::Status status READ status WRITE setStatus)
73 Q_PROPERTY(QVariantList attachments READ attachmentsVariant)
74 Q_PROPERTY(QVariantList conferences READ conferencesVariant)
75 public:
76 /**
77 The different types of overall incidence status or confirmation.
78 The meaning is specific to the incidence type in context.
79 */
80 enum Status {
81 StatusNone, /**< No status */
82 StatusTentative, /**< event is tentative */
83 StatusConfirmed, /**< event is definite */
84 StatusCompleted, /**< to-do completed */
85 StatusNeedsAction, /**< to-do needs action */
86 StatusCanceled, /**< event or to-do canceled; journal removed */
87 StatusInProcess, /**< to-do in process */
88 StatusDraft, /**< journal is draft */
89 StatusFinal, /**< journal is final */
90 StatusX, /**< a non-standard status string */
91 };
92 Q_ENUM(Status)
93
94 /**
95 The different types of incidence access classifications.
96 */
97 enum Secrecy {
98 SecrecyPublic, /**< Not secret (default) */
99 SecrecyPrivate, /**< Secret to the owner */
100 SecrecyConfidential, /**< Secret to the owner and some others */
101 };
102 Q_ENUM(Secrecy)
103
104 /**
105 The different types of RELTYPE values specified by the RFC.
106 Only RelTypeParent is supported for now.
107 */
108 enum RelType {
109 RelTypeParent, /**< The related incidence is a parent. */
110 RelTypeChild, /**< The related incidence is a child. */
111 RelTypeSibling, /**< The related incidence is a peer. */
112 };
113
114 /**
115 A shared pointer to an Incidence.
116 */
117 typedef QSharedPointer<Incidence> Ptr;
118
119 /**
120 List of incidences.
121 */
122 typedef QVector<Ptr> List;
123
124 /**
125 Constructs an empty incidence.*
126 */
127 Incidence();
128
129 /**
130 Destroys an incidence.
131 */
132 ~Incidence() override;
133
134 /**
135 Returns an exact copy of this incidence. The returned object is owned
136 by the caller.
137
138 Dirty fields are cleared.
139 */
140 virtual Incidence *clone() const = 0;
141
142 /**
143 Returns a unique identifier for a specific instance of an incidence.
144
145 Due to the recurrence-id, the uid is not unique for a KCalendarCore::Incidence.
146 @since 4.11
147 */
148 Q_REQUIRED_RESULT QString instanceIdentifier() const;
149
150 /**
151 Set readonly state of incidence.
152
153 @param readonly If true, the incidence is set to readonly, if false the
154 incidence is set to readwrite.
155 */
156 void setReadOnly(bool readonly) override;
157
158 /**
159 @copydoc IncidenceBase::setLastModified().
160 */
161 void setLastModified(const QDateTime &lm) override;
162
163 /**
164 Set localOnly state of incidence.
165 A local only incidence can be updated but it will not increase the revision
166 number neither the modified date.
167
168 @param localonly If true, the incidence is set to localonly, if false the
169 incidence is set to normal stat.
170 */
171 void setLocalOnly(bool localonly);
172
173 /**
174 Get the localOnly status.
175 @return true if Local only, false otherwise.
176
177 @see setLocalOnly()
178 */
179 Q_REQUIRED_RESULT bool localOnly() const;
180
181 /**
182 @copydoc IncidenceBase::setAllDay().
183 */
184 void setAllDay(bool allDay) override;
185
186 /**
187 Recreate incidence. The incidence is made a new unique incidence, but already stored
188 information is preserved. Sets unique id, creation date, last
189 modification date and revision number.
190 */
191 void recreate();
192
193 /**
194 Sets the incidence creation date/time. It is stored as a UTC date/time.
195
196 @param dt is the creation date/time.
197 @see created().
198 */
199 void setCreated(const QDateTime &dt);
200
201 /**
202 Returns the incidence creation date/time.
203 @see setCreated().
204 */
205 Q_REQUIRED_RESULT QDateTime created() const;
206
207 /**
208 Sets the number of revisions this incidence has seen.
209
210 @param rev is the incidence revision number.
211 @see revision().
212 */
213 void setRevision(int rev);
214
215 /**
216 Returns the number of revisions this incidence has seen.
217 @see setRevision().
218 */
219 Q_REQUIRED_RESULT int revision() const;
220
221 /**
222 Sets the incidence starting date/time.
223
224 @param dt is the starting date/time.
225 @see IncidenceBase::dtStart().
226 */
227 void setDtStart(const QDateTime &dt) override;
228
229 /**
230 @copydoc IncidenceBase::shiftTimes()
231 */
232 void shiftTimes(const QTimeZone &oldZone, const QTimeZone &newZone) override;
233
234 /**
235 Sets the incidence description.
236
237 @param description is the incidence description string.
238 @param isRich if true indicates the description string contains richtext.
239 @see description().
240 */
241 void setDescription(const QString &description, bool isRich);
242
243 /**
244 Sets the incidence description and tries to guess if the description
245 is rich text.
246
247 @param description is the incidence description string.
248 @see description().
249 */
250 void setDescription(const QString &description);
251
252 /**
253 Returns the incidence description.
254 @see setDescription().
255 @see richDescription().
256 */
257 Q_REQUIRED_RESULT QString description() const;
258
259 /**
260 Returns the incidence description in rich text format.
261 @see setDescription().
262 @see description().
263 */
264 Q_REQUIRED_RESULT QString richDescription() const;
265
266 /**
267 Returns true if incidence description contains RichText; false otherwise.
268 @see setDescription(), description().
269 */
270 Q_REQUIRED_RESULT bool descriptionIsRich() const;
271
272 /**
273 Sets the incidence summary.
274
275 @param summary is the incidence summary string.
276 @param isRich if true indicates the summary string contains richtext.
277 @see summary().
278 */
279 void setSummary(const QString &summary, bool isRich);
280
281 /**
282 Sets the incidence summary and tries to guess if the summary is richtext.
283
284 @param summary is the incidence summary string.
285 @see summary().
286 */
287 void setSummary(const QString &summary);
288
289 /**
290 Returns the incidence summary.
291 @see setSummary().
292 @see richSummary().
293 */
294 Q_REQUIRED_RESULT QString summary() const;
295
296 /**
297 Returns the incidence summary in rich text format.
298 @see setSummary().
299 @see summary().
300 */
301 Q_REQUIRED_RESULT QString richSummary() const;
302
303 /**
304 Returns true if incidence summary contains RichText; false otherwise.
305 @see setSummary(), summary().
306 */
307 Q_REQUIRED_RESULT bool summaryIsRich() const;
308
309 /**
310 Sets the incidence location. Do _not_ use with journals.
311
312 @param location is the incidence location string.
313 @param isRich if true indicates the location string contains richtext.
314 @see location().
315 */
316 void setLocation(const QString &location, bool isRich);
317
318 /**
319 Sets the incidence location and tries to guess if the location is
320 richtext. Do _not_ use with journals.
321
322 @param location is the incidence location string.
323 @see location().
324 */
325 void setLocation(const QString &location);
326
327 /**
328 Returns the incidence location. Do _not_ use with journals.
329 @see setLocation().
330 @see richLocation().
331 */
332 Q_REQUIRED_RESULT QString location() const;
333
334 /**
335 Returns the incidence location in rich text format.
336 @see setLocation().
337 @see location().
338 */
339 Q_REQUIRED_RESULT QString richLocation() const;
340
341 /**
342 Returns true if incidence location contains RichText; false otherwise.
343 @see setLocation(), location().
344 */
345 Q_REQUIRED_RESULT bool locationIsRich() const;
346
347 /**
348 Sets the incidence category list.
349
350 @param categories is a list of category strings.
351 @see setCategories( const QString &), categories().
352 */
353 void setCategories(const QStringList &categories);
354
355 /**
356 Sets the incidence category list based on a comma delimited string.
357
358 @param catStr is a QString containing a list of categories which
359 are delimited by a comma character.
360 @see setCategories( const QStringList &), categories().
361 */
362 void setCategories(const QString &catStr);
363
364 /**
365 Returns the incidence categories as a list of strings.
366 @see setCategories( const QStringList &), setCategories( const QString &).
367 */
368 Q_REQUIRED_RESULT QStringList categories() const;
369
370 /**
371 Returns the incidence categories as a comma separated string.
372 @see categories().
373 */
374 Q_REQUIRED_RESULT QString categoriesStr() const;
375
376 /**
377 Relates another incidence to this one, by UID. This function should only
378 be used when constructing a calendar before the related incidence exists.
379
380 @param uid is a QString containing a UID for another incidence.
381 @param relType specifies the relation type.
382
383 @warning KCalendarCore only supports one related-to field per reltype for now.
384
385 @see relatedTo().
386 */
387 void setRelatedTo(const QString &uid, RelType relType = RelTypeParent);
388
389 /**
390 Returns a UID string for the incidence that is related to this one.
391 This function should only be used when constructing a calendar before
392 the related incidence exists.
393
394 @warning KCalendarCore only supports one related-to field per reltype for now.
395
396 @param relType specifies the relation type.
397
398 @see setRelatedTo().
399 */
400 Q_REQUIRED_RESULT QString relatedTo(RelType relType = RelTypeParent) const;
401
402 /**
403 Set the incidence color, as added in RFC7986.
404
405 @param colorName a named color as defined in CSS3 color name, see
406 https://www.w3.org/TR/css-color-3/#svg-color.
407 @since: 5.76
408 */
409 void setColor(const QString &colorName);
410
411 /**
412 Returns the color, if any is defined, for this incidence.
413
414 @since: 5.76
415 */
416 Q_REQUIRED_RESULT QString color() const;
417
418 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
419 // %%%%% Convenience wrappers for property handling
420 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
421 /**
422 Returns true if the alternative (=text/html) description is
423 available.
424 @see setAltDescription(), altDescription()
425 */
426 Q_REQUIRED_RESULT bool hasAltDescription() const;
427 /**
428 Sets the incidence's alternative (=text/html) description. If
429 the text is empty, the property is removed.
430
431 @param altdescription is the incidence altdescription string.
432 @see altAltdescription().
433 */
434 void setAltDescription(const QString &altdescription);
435
436 /**
437 Returns the incidence alternative (=text/html) description.
438 @see setAltDescription().
439 */
440 Q_REQUIRED_RESULT QString altDescription() const;
441
442 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
443 // %%%%% Recurrence-related methods
444 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
445
446 /**
447 Returns the recurrence rule associated with this incidence. If there is
448 none, returns an appropriate (non-0) object.
449 */
450 Recurrence *recurrence() const;
451
452 /**
453 Removes all recurrence and exception rules and dates.
454 */
455 void clearRecurrence();
456
457 /**
458 @copydoc Recurrence::recurs()
459 */
460 Q_REQUIRED_RESULT bool recurs() const;
461
462 /**
463 @copydoc Recurrence::recurrenceType()
464 */
465 Q_REQUIRED_RESULT ushort recurrenceType() const;
466
467 /**
468 @copydoc Recurrence::recursOn()
469 */
470 virtual bool recursOn(const QDate &date, const QTimeZone &timeZone) const;
471
472 /**
473 @copydoc Recurrence::recursAt()
474 */
475 Q_REQUIRED_RESULT bool recursAt(const QDateTime &dt) const;
476
477 /**
478 Calculates the start date/time for all recurrences that happen at some
479 time on the given date (might start before that date, but end on or
480 after the given date).
481
482 @param date the date when the incidence should occur
483 @param timeSpec time specification for @p date.
484 @return the start date/time of all occurrences that overlap with the
485 given date; an empty list if the incidence does not overlap with the
486 date at all.
487 */
488 virtual QList<QDateTime> startDateTimesForDate(const QDate &date, const QTimeZone &timeZone) const;
489
490 /**
491 Calculates the start date/time for all recurrences that happen at the
492 given time.
493
494 @param datetime the date/time when the incidence should occur.
495 @return the start date/time of all occurrences that overlap with the
496 given date/time; an empty list if the incidence does not happen at the
497 given time at all.
498 */
499 Q_REQUIRED_RESULT virtual QList<QDateTime> startDateTimesForDateTime(const QDateTime &datetime) const;
500
501 /**
502 Returns the end date/time of the incidence occurrence if it starts at
503 specified date/time.
504
505 @param startDt is the specified starting date/time.
506 @return the corresponding end date/time for the occurrence; or the start
507 date/time if the end date/time is invalid; or the end date/time if
508 the start date/time is invalid.
509 */
510 Q_REQUIRED_RESULT virtual QDateTime endDateForStart(const QDateTime &startDt) const;
511
512 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
513 // %%%%% Attachment-related methods
514 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
515
516 /**
517 Adds an attachment to the incidence.
518
519 @param attachment a valid Attachment object.
520 */
521 void addAttachment(const Attachment &attachment);
522
523 /**
524 Removes all attachments of the specified MIME type from the incidence.
525 The memory used by all the removed attachments is freed.
526
527 @param mime is a QString containing the MIME type.
528 @see deleteAttachment().
529 */
530 void deleteAttachments(const QString &mime);
531
532 /**
533 Returns a list of all incidence attachments.
534 @see attachments( const QString &).
535 */
536 Q_REQUIRED_RESULT Attachment::List attachments() const;
537
538 /**
539 Returns a list of all incidence attachments with the specified MIME type.
540
541 @param mime is a QString containing the MIME type.
542 @see attachments().
543 */
544 Q_REQUIRED_RESULT Attachment::List attachments(const QString &mime) const;
545
546 /**
547 Removes all attachments and frees the memory used by them.
548 @see deleteAttachments( const QString &).
549 */
550 void clearAttachments();
551
552 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
553 // %%%%% Secrecy and Status methods
554 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
555
556 /**
557 Sets the incidence #Secrecy.
558
559 @param secrecy is the incidence #Secrecy to set.
560 @see secrecy(), secrecyStr().
561 */
562 void setSecrecy(Secrecy secrecy);
563
564 /**
565 Returns the incidence #Secrecy.
566 @see setSecrecy(), secrecyStr().
567 */
568 Q_REQUIRED_RESULT Secrecy secrecy() const;
569
570 /**
571 Sets the incidence status to a standard #Status value.
572 Note that StatusX cannot be specified.
573
574 @param status is the incidence #Status to set.
575 @see status(), setCustomStatus().
576 */
577 void setStatus(Status status);
578
579 /**
580 Sets the incidence #Status to a non-standard status value.
581
582 @param status is a non-standard status string. If empty,
583 the incidence #Status will be set to StatusNone.
584 @see setStatus(), status() customStatus().
585 */
586 void setCustomStatus(const QString &status);
587
588 /**
589 Returns the non-standard status value.
590 @see setCustomStatus().
591 */
592 Q_REQUIRED_RESULT QString customStatus() const;
593
594 /**
595 Returns the incidence #Status.
596 @see setStatus(), setCustomStatus(), statusStr().
597 */
598 Q_REQUIRED_RESULT Status status() const;
599
600 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
601 // %%%%% Other methods
602 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
603
604 /**
605 Sets a list of incidence resources. (Note: resources in this context
606 means items used by the incidence such as money, fuel, hours, etc).
607
608 @param resources is a list of resource strings.
609 @see resources().
610 */
611 void setResources(const QStringList &resources);
612
613 /**
614 Returns the incidence resources as a list of strings.
615 @see setResources().
616 */
617 Q_REQUIRED_RESULT QStringList resources() const;
618
619 /**
620 Sets the incidences priority. The priority must be an integer value
621 between 0 and 9, where 0 is undefined, 1 is the highest, and 9 is the
622 lowest priority (decreasing order).
623
624 @param priority is the incidence priority to set.
625 @see priority().
626 */
627 void setPriority(int priority);
628
629 /**
630 Returns the incidence priority.
631 @see setPriority().
632 */
633 Q_REQUIRED_RESULT int priority() const;
634
635 /**
636 Returns true if the incidence has geo data, otherwise return false.
637 @see setHasGeo(), setGeoLatitude(float), setGeoLongitude(float).
638 */
639 Q_REQUIRED_RESULT bool hasGeo() const;
640
641 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 89)
642 /**
643 Sets if the incidence has geo data.
644 @param hasGeo if true, latitude and longitude must be set to valid values.
645 If false, geoLatitude() and geoLongitude() will return INVALID_LATLON.
646 @deprecated since 5.89. Use setGeoLatitude() and setGeoLongitude().
647 @see hasGeo(), geoLatitude(), geoLongitude().
648 */
649 KCALENDARCORE_DEPRECATED_VERSION(5, 89, "Use setGeoLatitude() and setGeoLongitude()")
650 void setHasGeo(bool hasGeo);
651 #endif
652
653 /**
654 Set the incidence's geoLatitude.
655 @param geolatitude is the incidence geolatitude to set; a value between -90.0 and 90.0,
656 or INVALID_LATLON (or NaN, which is treated as INVALID_LATLON).
657 @see geoLatitude().
658 */
659 void setGeoLatitude(float geolatitude);
660
661 /**
662 Returns the incidence's geoLatitude as a value between -90.0 and 90.0 or INVALID_LATLON.
663 If either of geoLatitude() and geoLongitude() are INVALID_LATLON, then both are, and hasGeo() is false.
664 @return incidences geolatitude value
665 @see setGeoLatitude().
666 */
667 Q_REQUIRED_RESULT float geoLatitude() const;
668
669 /**
670 Set the incidence's geoLongitude.
671 @param geolongitude is the incidence geolongitude to set; a value between -180.0 and 180.0,
672 or INVALID_LATLON (or NaN, which is treated as INVALID_LATLON).
673 @see geoLongitude().
674 */
675 void setGeoLongitude(float geolongitude);
676
677 /**
678 Returns the incidence's geoLongitude as a value between -180.0 and 180.0 or INVALID_LATLON.
679 If either of geoLatitude() and geoLongitude() are INVALID_LATLON, then both are, and hasGeo() is false.
680 @return incidences geolongitude value
681 @see setGeoLongitude().
682 */
683 Q_REQUIRED_RESULT float geoLongitude() const;
684
685 /**
686 Returns true if the incidence has recurrenceId, otherwise return false.
687 @see setRecurrenceId(QDateTime)
688 */
689 Q_REQUIRED_RESULT bool hasRecurrenceId() const;
690
691 /**
692 Set the incidences recurrenceId.
693 This field indicates that this is an exception to a recurring incidence.
694 The uid of this incidence MUST be the same as the one of the recurring main incidence.
695 @param recurrenceId is the incidence recurrenceId to set
696 @see recurrenceId().
697 */
698 void setRecurrenceId(const QDateTime &recurrenceId);
699
700 /**
701 Returns the incidence recurrenceId.
702 @return incidences recurrenceId value
703 @see setRecurrenceId().
704 */
705 Q_REQUIRED_RESULT QDateTime recurrenceId() const override;
706
707 /**
708 Set to true if the exception also applies to all future occurrences.
709 This option is only relevant if the incidence has a recurrenceId set.
710 @param thisAndFuture value
711 @see thisAndFuture(), setRecurrenceId()
712 @since 4.11
713 */
714 void setThisAndFuture(bool thisAndFuture);
715
716 /**
717 Returns true if the exception also applies to all future occurrences.
718 @return incidences thisAndFuture value
719 @see setThisAndFuture()
720 @since 4.11
721 */
722 Q_REQUIRED_RESULT bool thisAndFuture() const;
723
724 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
725 // %%%%% Alarm-related methods
726 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
727
728 /**
729 Returns a list of all incidence alarms.
730 */
731 Q_REQUIRED_RESULT Alarm::List alarms() const;
732
733 /**
734 Create a new incidence alarm.
735 */
736 Alarm::Ptr newAlarm();
737
738 /**
739 Adds an alarm to the incidence.
740
741 @param alarm is a pointer to a valid Alarm object.
742 @see removeAlarm().
743 */
744 void addAlarm(const Alarm::Ptr &alarm);
745
746 /**
747 Removes the specified alarm from the incidence.
748
749 @param alarm is a pointer to a valid Alarm object.
750 @see addAlarm().
751 */
752 void removeAlarm(const Alarm::Ptr &alarm);
753
754 /**
755 Removes all alarms.
756 @see removeAlarm().
757 */
758 void clearAlarms();
759
760 /**
761 Returns true if any of the incidence alarms are enabled; false otherwise.
762 */
763 Q_REQUIRED_RESULT bool hasEnabledAlarms() const;
764
765 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
766 // %%%%% Conferences-related method
767 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
768
769 /**
770 * Returns list of all incidence conferencing methods.
771 * @since 5.77
772 */
773 Q_REQUIRED_RESULT Conference::List conferences() const;
774
775 /**
776 * Replaces all conferences in the incidence with given @p conferences
777 *
778 * @param conferences New conferences to store in the incidence.
779 * @since 5.77
780 */
781 void setConferences(const Conference::List &conferences);
782
783 /**
784 * Adds a conference to the incidence.
785 *
786 * @param conferene A conference to add.
787 * @since 5.77
788 */
789 void addConference(const Conference &conference);
790
791 /**
792 * Removes all conferences from the incidence.
793 * @since 5.77
794 */
795 void clearConferences();
796
797 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
798 // %%%%% Other methods
799 // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
800
801 /**
802 Set the incidence scheduling ID. Do _not_ use with journals.
803 This is used for accepted invitations as the place to store the UID
804 of the invitation. It is later used again if updates to the
805 invitation comes in.
806 If we did not set a new UID on incidences from invitations, we can
807 end up with more than one resource having events with the same UID,
808 if you have access to other peoples resources.
809
810 While constructing an incidence, when setting the scheduling ID,
811 you will always want to set the incidence UID too. Instead of calling
812 setUID() separately, you can pass the UID through @p uid so both
813 members are changed in one atomic operation ( don't forget that
814 setUID() emits incidenceUpdated() and whoever catches that signal
815 will have an half-initialized incidence, therefore, always set
816 the schedulingID and UID at the same time, and never with two separate
817 calls).
818
819 @param sid is a QString containing the scheduling ID.
820 @param uid is a QString containing the incidence UID to set, if not
821 specified, the current UID isn't changed, and this parameter
822 is ignored.
823 @see schedulingID().
824 */
825 void setSchedulingID(const QString &sid, const QString &uid = QString());
826
827 /**
828 Returns the incidence scheduling ID. Do _not_ use with journals.
829 If a scheduling ID is not set, then return the incidence UID.
830 @see setSchedulingID().
831 */
832 Q_REQUIRED_RESULT QString schedulingID() const;
833
834 /**
835 Observer interface for the recurrence class. If the recurrence is
836 changed, this method will be called for the incidence the recurrence
837 object belongs to.
838
839 @param recurrence is a pointer to a valid Recurrence object.
840 */
841 void recurrenceUpdated(Recurrence *recurrence) override;
842
843 /**
844 Returns the name of the icon that best represents this incidence.
845
846 @param recurrenceId Some recurring incidences might use a different icon,
847 for example, completed to-do occurrences. Use this parameter to identify
848 the specific occurrence in a recurring serie.
849 */
850 virtual QLatin1String iconName(const QDateTime &recurrenceId = {}) const = 0;
851
852 /**
853 * Returns true if the incidence type supports groupware communication.
854 * @since 4.10
855 */
856 virtual bool supportsGroupwareCommunication() const = 0;
857
858 /**
859 Returns the list of possible mime types in an Incidence object:
860 "text/calendar"
861 "application/x-vnd.akonadi.calendar.event"
862 "application/x-vnd.akonadi.calendar.todo"
863 "application/x-vnd.akonadi.calendar.journal"
864
865 @since 4.12
866 */
867 Q_REQUIRED_RESULT static QStringList mimeTypes();
868
869 protected:
870 /**
871 Copy constructor.
872 @param other is the incidence to copy.
873 */
874 Incidence(const Incidence &other);
875
876 /**
877 Compares this with Incidence @p incidence for equality.
878 @param incidence is the Incidence to compare against.
879 @return true if the incidences are equal; false otherwise.
880 */
881 bool equals(const IncidenceBase &incidence) const override;
882
883 /**
884 @copydoc IncidenceBase::assign()
885 */
886 IncidenceBase &assign(const IncidenceBase &other) override;
887
888 void serialize(QDataStream &out) const override;
889 void deserialize(QDataStream &in) override;
890
891 private:
892 /**
893 Disabled, not polymorphic.
894 Use IncidenceBase::operator= which is safe because it calls
895 virtual function assign.
896 @param other is another Incidence object to assign to this one.
897 */
898 Incidence &operator=(const Incidence &other);
899
900 Q_DECL_HIDDEN QVariantList attachmentsVariant() const;
901 Q_DECL_HIDDEN QVariantList conferencesVariant() const;
902
903 //@cond PRIVATE:
904 friend class IncidencePrivate;
905 IncidencePrivate *const d;
906 //@endcond
907 };
908
909 }
910
911 //@cond PRIVATE
qHash(const QSharedPointer<KCalendarCore::Incidence> & key)912 inline uint qHash(const QSharedPointer<KCalendarCore::Incidence> &key)
913 {
914 return qHash(key.data());
915 }
916 //@endcond
917
918 //@cond PRIVATE
919 Q_DECLARE_TYPEINFO(KCalendarCore::Incidence::Ptr, Q_MOVABLE_TYPE);
920 Q_DECLARE_METATYPE(KCalendarCore::Incidence *)
921 //@endcond
922
923 #endif
924