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  Events, Todos, and Journals each have a different set of
590  valid statuses. Note that StatusX cannot be specified.
591  Invalid statuses are logged and ignored.
592 
593  @param status is the incidence #Status to set.
594  @see status(), setCustomStatus().
595  */
596  void setStatus(Status status);
597 
598  /**
599  Sets the incidence #Status to a non-standard status value.
600 
601  @param status is a non-standard status string. If empty,
602  the incidence #Status will be set to StatusNone.
603  @see setStatus(), status() customStatus().
604  */
605  void setCustomStatus(const QString &status);
606 
607  /**
608  Returns the non-standard status value.
609  @see setCustomStatus().
610  */
611  Q_REQUIRED_RESULT QString customStatus() const;
612 
613  /**
614  Returns the incidence #Status.
615  @see setStatus(), setCustomStatus(), statusStr().
616  */
617  Q_REQUIRED_RESULT Status status() const;
618 
619  // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
620  // %%%%% Other methods
621  // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
622 
623  /**
624  Sets a list of incidence resources. (Note: resources in this context
625  means items used by the incidence such as money, fuel, hours, etc).
626 
627  @param resources is a list of resource strings.
628  @see resources().
629  */
630  void setResources(const QStringList &resources);
631 
632  /**
633  Returns the incidence resources as a list of strings.
634  @see setResources().
635  */
636  Q_REQUIRED_RESULT QStringList resources() const;
637 
638  /**
639  Sets the incidences priority. The priority must be an integer value
640  between 0 and 9, where 0 is undefined, 1 is the highest, and 9 is the
641  lowest priority (decreasing order).
642 
643  @param priority is the incidence priority to set.
644  @see priority().
645  */
646  void setPriority(int priority);
647 
648  /**
649  Returns the incidence priority.
650  @see setPriority().
651  */
652  Q_REQUIRED_RESULT int priority() const;
653 
654  /**
655  Returns true if the incidence has geo data, otherwise return false.
656  @see setHasGeo(), setGeoLatitude(float), setGeoLongitude(float).
657  */
658  Q_REQUIRED_RESULT bool hasGeo() const;
659 
660 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 89)
661  /**
662  Sets if the incidence has geo data.
663  @param hasGeo if true, latitude and longitude must be set to valid values.
664  If false, geoLatitude() and geoLongitude() will return INVALID_LATLON.
665  @deprecated since 5.89. Use setGeoLatitude() and setGeoLongitude().
666  @see hasGeo(), geoLatitude(), geoLongitude().
667  */
668  KCALENDARCORE_DEPRECATED_VERSION(5, 89, "Use setGeoLatitude() and setGeoLongitude()")
669  void setHasGeo(bool hasGeo);
670 #endif
671 
672  /**
673  Set the incidence's geoLatitude.
674  @param geolatitude is the incidence geolatitude to set; a value between -90.0 and 90.0,
675  or INVALID_LATLON (or NaN, which is treated as INVALID_LATLON).
676  @see geoLatitude().
677  */
678  void setGeoLatitude(float geolatitude);
679 
680  /**
681  Returns the incidence's geoLatitude as a value between -90.0 and 90.0 or INVALID_LATLON.
682  If either of geoLatitude() and geoLongitude() are INVALID_LATLON, then both are, and hasGeo() is false.
683  @return incidences geolatitude value
684  @see setGeoLatitude().
685  */
686  Q_REQUIRED_RESULT float geoLatitude() const;
687 
688  /**
689  Set the incidence's geoLongitude.
690  @param geolongitude is the incidence geolongitude to set; a value between -180.0 and 180.0,
691  or INVALID_LATLON (or NaN, which is treated as INVALID_LATLON).
692  @see geoLongitude().
693  */
694  void setGeoLongitude(float geolongitude);
695 
696  /**
697  Returns the incidence's geoLongitude as a value between -180.0 and 180.0 or INVALID_LATLON.
698  If either of geoLatitude() and geoLongitude() are INVALID_LATLON, then both are, and hasGeo() is false.
699  @return incidences geolongitude value
700  @see setGeoLongitude().
701  */
702  Q_REQUIRED_RESULT float geoLongitude() const;
703 
704  /**
705  Returns true if the incidence has recurrenceId, otherwise return false.
706  @see setRecurrenceId(QDateTime)
707  */
708  Q_REQUIRED_RESULT bool hasRecurrenceId() const;
709 
710  /**
711  Set the incidences recurrenceId.
712  This field indicates that this is an exception to a recurring incidence.
713  The uid of this incidence MUST be the same as the one of the recurring main incidence.
714  @param recurrenceId is the incidence recurrenceId to set
715  @see recurrenceId().
716  */
717  void setRecurrenceId(const QDateTime &recurrenceId);
718 
719  /**
720  Returns the incidence recurrenceId.
721  @return incidences recurrenceId value
722  @see setRecurrenceId().
723  */
724  Q_REQUIRED_RESULT QDateTime recurrenceId() const override;
725 
726  /**
727  Set to true if the exception also applies to all future occurrences.
728  This option is only relevant if the incidence has a recurrenceId set.
729  @param thisAndFuture value
730  @see thisAndFuture(), setRecurrenceId()
731  @since 4.11
732  */
733  void setThisAndFuture(bool thisAndFuture);
734 
735  /**
736  Returns true if the exception also applies to all future occurrences.
737  @return incidences thisAndFuture value
738  @see setThisAndFuture()
739  @since 4.11
740  */
741  Q_REQUIRED_RESULT bool thisAndFuture() const;
742 
743  // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
744  // %%%%% Alarm-related methods
745  // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
746 
747  /**
748  Returns a list of all incidence alarms.
749  */
750  Q_REQUIRED_RESULT Alarm::List alarms() const;
751 
752  /**
753  Create a new incidence alarm.
754  */
755  Alarm::Ptr newAlarm();
756 
757  /**
758  Adds an alarm to the incidence.
759 
760  @param alarm is a pointer to a valid Alarm object.
761  @see removeAlarm().
762  */
763  void addAlarm(const Alarm::Ptr &alarm);
764 
765  /**
766  Removes the specified alarm from the incidence.
767 
768  @param alarm is a pointer to a valid Alarm object.
769  @see addAlarm().
770  */
771  void removeAlarm(const Alarm::Ptr &alarm);
772 
773  /**
774  Removes all alarms.
775  @see removeAlarm().
776  */
777  void clearAlarms();
778 
779  /**
780  Returns true if any of the incidence alarms are enabled; false otherwise.
781  */
782  Q_REQUIRED_RESULT bool hasEnabledAlarms() const;
783 
784  // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
785  // %%%%% Conferences-related method
786  // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
787 
788  /**
789  * Returns list of all incidence conferencing methods.
790  * @since 5.77
791  */
792  Q_REQUIRED_RESULT Conference::List conferences() const;
793 
794  /**
795  * Replaces all conferences in the incidence with given @p conferences
796  *
797  * @param conferences New conferences to store in the incidence.
798  * @since 5.77
799  */
800  void setConferences(const Conference::List &conferences);
801 
802  /**
803  * Adds a conference to the incidence.
804  *
805  * @param conferene A conference to add.
806  * @since 5.77
807  */
808  void addConference(const Conference &conference);
809 
810  /**
811  * Removes all conferences from the incidence.
812  * @since 5.77
813  */
814  void clearConferences();
815 
816  // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
817  // %%%%% Other methods
818  // %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
819 
820  /**
821  Set the incidence scheduling ID. Do _not_ use with journals.
822  This is used for accepted invitations as the place to store the UID
823  of the invitation. It is later used again if updates to the
824  invitation comes in.
825  If we did not set a new UID on incidences from invitations, we can
826  end up with more than one resource having events with the same UID,
827  if you have access to other peoples resources.
828 
829  While constructing an incidence, when setting the scheduling ID,
830  you will always want to set the incidence UID too. Instead of calling
831  setUID() separately, you can pass the UID through @p uid so both
832  members are changed in one atomic operation ( don't forget that
833  setUID() emits incidenceUpdated() and whoever catches that signal
834  will have an half-initialized incidence, therefore, always set
835  the schedulingID and UID at the same time, and never with two separate
836  calls).
837 
838  @param sid is a QString containing the scheduling ID.
839  @param uid is a QString containing the incidence UID to set, if not
840  specified, the current UID isn't changed, and this parameter
841  is ignored.
842  @see schedulingID().
843  */
844  void setSchedulingID(const QString &sid, const QString &uid = QString());
845 
846  /**
847  Returns the incidence scheduling ID. Do _not_ use with journals.
848  If a scheduling ID is not set, then return the incidence UID.
849  @see setSchedulingID().
850  */
851  Q_REQUIRED_RESULT QString schedulingID() const;
852 
853  /**
854  Observer interface for the recurrence class. If the recurrence is
855  changed, this method will be called for the incidence the recurrence
856  object belongs to.
857 
858  @param recurrence is a pointer to a valid Recurrence object.
859  */
860  void recurrenceUpdated(Recurrence *recurrence) override;
861 
862  /**
863  Returns the name of the icon that best represents this incidence.
864 
865  @param recurrenceId Some recurring incidences might use a different icon,
866  for example, completed to-do occurrences. Use this parameter to identify
867  the specific occurrence in a recurring serie.
868  */
869  virtual QLatin1String iconName(const QDateTime &recurrenceId = {}) const = 0;
870 
871  /**
872  * Returns true if the incidence type supports groupware communication.
873  * @since 4.10
874  */
875  virtual bool supportsGroupwareCommunication() const = 0;
876 
877  /**
878  Returns the list of possible mime types in an Incidence object:
879  "text/calendar"
880  "application/x-vnd.akonadi.calendar.event"
881  "application/x-vnd.akonadi.calendar.todo"
882  "application/x-vnd.akonadi.calendar.journal"
883 
884  @since 4.12
885  */
886  Q_REQUIRED_RESULT static QStringList mimeTypes();
887 
888 protected:
889 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 91)
890  /**
891  Copy constructor.
892  @param other is the incidence to copy.
893  @deprecated Use Incidence(const Incidence &other, IncidencePrivate *p).
894  */
895  Incidence(const Incidence &other);
896 #else
897  Incidence(const Incidence &) = delete;
898 #endif
899 
900  /**
901  @param other is the incidence to copy.
902  @param p (non-null) a Private data object provided by the instantiated
903  class (Event, Todo, Journal, FreeBusy). It passes ownership of the object
904  to IncidenceBase.
905  */
906  Incidence(const Incidence &other, IncidencePrivate *p);
907 
908  /**
909  Compares this with Incidence @p incidence for equality.
910  @param incidence is the Incidence to compare against.
911  @return true if the incidences are equal; false otherwise.
912  */
913  bool equals(const IncidenceBase &incidence) const override;
914 
915  /**
916  @copydoc IncidenceBase::assign()
917  */
918  IncidenceBase &assign(const IncidenceBase &other) override;
919 
920  void serialize(QDataStream &out) const override;
921  void deserialize(QDataStream &in) override;
922 
923 private:
924  /**
925  Disabled, not polymorphic.
926  Use IncidenceBase::operator= which is safe because it calls
927  virtual function assign.
928  @param other is another Incidence object to assign to this one.
929  */
930  Incidence &operator=(const Incidence &other);
931 
932  Q_DECL_HIDDEN QVariantList attachmentsVariant() const;
933  Q_DECL_HIDDEN QVariantList conferencesVariant() const;
934 
935 protected:
936  Q_DECLARE_PRIVATE(Incidence)
937 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 91)
938  KCALENDARCORE_DEPRECATED_VERSION(5, 91, "Do not use")
939  IncidencePrivate *const _ = nullptr; // TODO KF6 remove. ABI compatibility hack.
940 #endif
941 };
942 
943 }
944 
945 //@cond PRIVATE
946 inline uint qHash(const QSharedPointer<KCalendarCore::Incidence> &key)
947 {
948  return qHash(key.data());
949 }
950 //@endcond
951 
952 //@cond PRIVATE
953 Q_DECLARE_TYPEINFO(KCalendarCore::Incidence::Ptr, Q_MOVABLE_TYPE);
954 Q_DECLARE_METATYPE(KCalendarCore::Incidence *)
955 //@endcond
956 
957 #endif
Status
The different types of overall incidence status or confirmation.
Definition: incidence.h:84
T * data() const const
bool equals(const QVariant &lhs, const QVariant &rhs)
@ 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 Thu Dec 8 2022 03:57:16 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.