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

KDE's Doxygen guidelines are available online.