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