KCalendarCore

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

KDE's Doxygen guidelines are available online.