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

KDE's Doxygen guidelines are available online.