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 David Jarvie <software@astrojar.org.uk> |
6 | Copyright (c) 2010 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.net> |
7 | |
8 | This library is free software; you can redistribute it and/or |
9 | modify it under the terms of the GNU Library General Public |
10 | License as published by the Free Software Foundation; either |
11 | version 2 of the License, or (at your option) any later version. |
12 | |
13 | This library is distributed in the hope that it will be useful, |
14 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
15 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
16 | Library General Public License for more details. |
17 | |
18 | You should have received a copy of the GNU Library General Public License |
19 | along with this library; see the file COPYING.LIB. If not, write to |
20 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
21 | Boston, MA 02110-1301, USA. |
22 | */ |
23 | /** |
24 | @file |
25 | This file is part of the API for handling calendar data and |
26 | defines the Alarm class. |
27 | |
28 | @author Cornelius Schumacher \<schumacher@kde.org\> |
29 | */ |
30 | |
31 | #ifndef KCALCORE_ALARM_H |
32 | #define KCALCORE_ALARM_H |
33 | |
34 | #include "kcalcore_export.h" |
35 | #include "customproperties.h" |
36 | #include "duration.h" |
37 | #include "person.h" |
38 | |
39 | #include <KDE/KDateTime> |
40 | |
41 | #include <QtCore/QString> |
42 | #include <QtCore/QStringList> |
43 | #include <QtCore/QVector> |
44 | #include <QDataStream> |
45 | #include <QMetaType> |
46 | |
47 | namespace KCalCore { |
48 | |
49 | class Incidence; |
50 | |
51 | /** |
52 | @brief |
53 | Represents an alarm notification. |
54 | |
55 | Alarms are user notifications that occur at specified times. |
56 | Notifications can be on-screen pop-up dialogs, email messages, |
57 | the playing of audio files, or the running of another program. |
58 | |
59 | Alarms always belong to a parent Incidence. |
60 | */ |
61 | class KCALCORE_EXPORT Alarm : public CustomProperties |
62 | { |
63 | public: |
64 | /** |
65 | The different types of alarms. |
66 | */ |
67 | enum Type { |
68 | Invalid, /**< Invalid, or no alarm */ |
69 | Display, /**< Display a dialog box */ |
70 | Procedure, /**< Call a script */ |
71 | Email, /**< Send email */ |
72 | Audio /**< Play an audio file */ |
73 | }; |
74 | |
75 | /** |
76 | A shared pointer to an Alarm object. |
77 | */ |
78 | typedef QSharedPointer<Alarm> Ptr; |
79 | |
80 | /** |
81 | List of alarms. |
82 | */ |
83 | typedef QVector<Ptr> List; |
84 | |
85 | /** |
86 | Constructs an alarm belonging to the @p parent Incidence. |
87 | |
88 | @param parent is the Incidence this alarm will belong to. |
89 | */ |
90 | // Can't find a way to use a shared pointer here. |
91 | // Inside incidence.cpp, it does alarm->setParent( this ) |
92 | explicit Alarm(Incidence *parent); |
93 | |
94 | /** |
95 | Copy constructor. |
96 | @param other is the alarm to copy. |
97 | */ |
98 | Alarm(const Alarm &other); |
99 | |
100 | /** |
101 | Destroys the alarm. |
102 | */ |
103 | virtual ~Alarm(); |
104 | |
105 | /** |
106 | Copy operator. |
107 | */ |
108 | Alarm &operator=(const Alarm &); |
109 | |
110 | /** |
111 | Compares two alarms for equality. |
112 | @param a is the comparison alarm. |
113 | */ |
114 | bool operator==(const Alarm &a) const; |
115 | |
116 | /** |
117 | Compares two alarms for inequality. |
118 | |
119 | @param a is the comparison alarm. |
120 | */ |
121 | bool operator!=(const Alarm &a) const; |
122 | |
123 | /** |
124 | Sets the @p parent Incidence of the alarm. |
125 | |
126 | @param parent is alarm parent Incidence to set. |
127 | |
128 | @see parentUid() |
129 | */ |
130 | // Is there a way to use QSharedPointer here? |
131 | // although it's safe, Incidence's dtor calls setParent( 0 ) |
132 | // se we don't dereference a deleted pointer here. |
133 | // Also, I renamed "Incidence *parent()" to "QString parentUid()" |
134 | // So we don't return raw pointers |
135 | void setParent(Incidence *parent); |
136 | |
137 | /** |
138 | Returns the parent's incidence UID of the alarm. |
139 | |
140 | @see setParent() |
141 | */ |
142 | // We don't have a share pointer to return, so return the UID. |
143 | QString parentUid() const; |
144 | |
145 | /** |
146 | Sets the #Type for this alarm to @p type. |
147 | If the specified type is different from the current type of the alarm, |
148 | then the alarm's type-specific properties are re-initialized. |
149 | |
150 | @param type is the alarm #Type to set. |
151 | |
152 | @see type() |
153 | */ |
154 | void setType(Type type); |
155 | |
156 | /** |
157 | Returns the #Type of the alarm. |
158 | |
159 | @see setType() |
160 | */ |
161 | Type type() const; |
162 | |
163 | /** |
164 | Sets the #Display type for this alarm. |
165 | If @p text is specified non-empty, then it is used as the description |
166 | text to display when the alarm is triggered. |
167 | |
168 | @param text is the description to display when the alarm is triggered. |
169 | |
170 | @see setText(), text() |
171 | */ |
172 | void setDisplayAlarm(const QString &text = QString()); |
173 | |
174 | /** |
175 | Sets the description @p text to be displayed when the alarm is triggered. |
176 | Ignored if the alarm is not a display alarm. |
177 | |
178 | @param text is the description to display when the alarm is triggered. |
179 | |
180 | @see setDisplayAlarm(), text() |
181 | */ |
182 | void setText(const QString &text); |
183 | |
184 | /** |
185 | Returns the display text string for a #Display alarm type. |
186 | Returns an empty string if the alarm is not a #Display type. |
187 | |
188 | @see setDisplayAlarm(), setText() |
189 | */ |
190 | QString text() const; |
191 | |
192 | /** |
193 | Sets the #Audio type for this alarm and the name of the audio file |
194 | to play when the alarm is triggered. |
195 | |
196 | @param audioFile is the name of the audio file to play when the alarm |
197 | is triggered. |
198 | |
199 | @see setAudioFile(), audioFile() |
200 | */ |
201 | void setAudioAlarm(const QString &audioFile = QString()); |
202 | |
203 | /** |
204 | Sets the name of the audio file to play when the audio alarm is triggered. |
205 | Ignored if the alarm is not an #Audio type. |
206 | |
207 | @param audioFile is the name of the audio file to play when the alarm |
208 | is triggered. |
209 | |
210 | @see setAudioAlarm(), audioFile() |
211 | */ |
212 | void setAudioFile(const QString &audioFile); |
213 | |
214 | /** |
215 | Returns the audio file name for an #Audio alarm type. |
216 | Returns an empty string if the alarm is not an #Audio type. |
217 | |
218 | @see setAudioAlarm(), setAudioFile() |
219 | */ |
220 | QString audioFile() const; |
221 | |
222 | /** |
223 | Sets the #Procedure type for this alarm and the program (with arguments) |
224 | to execute when the alarm is triggered. |
225 | |
226 | @param programFile is the name of the program file to execute when |
227 | the alarm is triggered. |
228 | @param arguments is a string of arguments to supply to @p programFile. |
229 | |
230 | @see setProgramFile(), programFile(), |
231 | setProgramArguments(), programArguments() |
232 | */ |
233 | void setProcedureAlarm(const QString &programFile, |
234 | const QString &arguments = QString()); |
235 | |
236 | /** |
237 | Sets the program file to execute when the alarm is triggered. |
238 | Ignored if the alarm is not a #Procedure type. |
239 | |
240 | @param programFile is the name of the program file to execute when |
241 | the alarm is triggered. |
242 | |
243 | @see setProcedureAlarm(), programFile(), |
244 | setProgramArguments(), programArguments() |
245 | */ |
246 | void setProgramFile(const QString &programFile); |
247 | |
248 | /** |
249 | Returns the program file name for a #Procedure alarm type. |
250 | Returns an empty string if the alarm is not a #Procedure type. |
251 | |
252 | @see setProcedureAlarm(), setProgramFile(), |
253 | setProgramArguments(), programArguments() |
254 | */ |
255 | QString programFile() const; |
256 | |
257 | /** |
258 | Sets the program arguments string when the alarm is triggered. |
259 | Ignored if the alarm is not a #Procedure type. |
260 | |
261 | @param arguments is a string of arguments to supply to the program. |
262 | |
263 | @see setProcedureAlarm(), setProgramFile(), programFile(), |
264 | programArguments() |
265 | */ |
266 | void setProgramArguments(const QString &arguments); |
267 | |
268 | /** |
269 | Returns the program arguments string for a #Procedure alarm type. |
270 | Returns an empty string if the alarm is not a #Procedure type. |
271 | |
272 | @see setProcedureAlarm(), setProgramFile(), programFile(), |
273 | setProgramArguments() |
274 | */ |
275 | QString programArguments() const; |
276 | |
277 | /** |
278 | Sets the #Email type for this alarm and the email @p subject, @p text, |
279 | @p addresses, and @p attachments that make up an email message to be |
280 | sent when the alarm is triggered. |
281 | |
282 | @param subject is the email subject. |
283 | @param text is a string containing the body of the email message. |
284 | @param addressees is Person list of email addresses. |
285 | @param attachments is a a QStringList of optional file names |
286 | of email attachments. |
287 | |
288 | @see setMailSubject(), setMailText(), setMailAddresses(), |
289 | setMailAttachments() |
290 | */ |
291 | void setEmailAlarm(const QString &subject, const QString &text, |
292 | const Person::List &addressees, |
293 | const QStringList &attachments = QStringList()); |
294 | |
295 | /** |
296 | Sets the email address of an #Email type alarm. |
297 | Ignored if the alarm is not an #Email type. |
298 | |
299 | @param mailAlarmAddress is a Person to receive a mail message when |
300 | an #Email type alarm is triggered. |
301 | |
302 | @see setMailSubject(), setMailText(), setMailAddresses(), |
303 | setMailAttachment(), setMailAttachments(), mailAddresses() |
304 | */ |
305 | void setMailAddress(const Person::Ptr &mailAlarmAddress); |
306 | |
307 | /** |
308 | Sets a list of email addresses of an #Email type alarm. |
309 | Ignored if the alarm is not an #Email type. |
310 | |
311 | @param mailAlarmAddresses is a Person list to receive a mail message |
312 | when an #Email type alarm is triggered. |
313 | |
314 | @see setMailSubject(), setMailText(), setMailAddress(), |
315 | setMailAttachments(), setMailAttachment(), mailAddresses() |
316 | */ |
317 | void setMailAddresses(const Person::List &mailAlarmAddresses); |
318 | |
319 | /** |
320 | Adds an address to the list of email addresses to send mail to when the |
321 | alarm is triggered. |
322 | Ignored if the alarm is not an #Email type. |
323 | |
324 | @param mailAlarmAddress is a Person to add to the list of addresses to |
325 | receive a mail message when an #Email type alarm is triggered. |
326 | |
327 | @see setMailAddress(), setMailAddresses(), mailAddresses() |
328 | */ |
329 | void addMailAddress(const Person::Ptr &mailAlarmAddress); |
330 | |
331 | /** |
332 | Returns the list of addresses for an #Email alarm type. |
333 | Returns an empty list if the alarm is not an #Email type. |
334 | |
335 | @see addMailAddress(), setMailAddress(), setMailAddresses() |
336 | */ |
337 | Person::List mailAddresses() const; |
338 | |
339 | /** |
340 | Sets the subject line of a mail message for an #Email alarm type. |
341 | Ignored if the alarm is not an #Email type. |
342 | |
343 | @param mailAlarmSubject is a string to be used as a subject line |
344 | of an email message to send when the #Email type alarm is triggered. |
345 | |
346 | @see setMailText(), setMailAddress(), setMailAddresses(), |
347 | setMailAttachment(), setMailAttachments(), mailSubject() |
348 | */ |
349 | void setMailSubject(const QString &mailAlarmSubject); |
350 | |
351 | /** |
352 | Returns the subject line string for an #Email alarm type. |
353 | Returns an empty string if the alarm is not an #Email type. |
354 | |
355 | @see setMailSubject() |
356 | */ |
357 | QString mailSubject() const; |
358 | |
359 | /** |
360 | Sets the filename to attach to a mail message for an #Email alarm type. |
361 | Ignored if the alarm is not an #Email type. |
362 | |
363 | @param mailAttachFile is a string containing a filename to be attached |
364 | to an email message to send when the #Email type alarm is triggered. |
365 | |
366 | @see setMailSubject(), setMailText(), setMailAddress(), |
367 | setMailAddresses(), setMailAttachments(), mailAttachments() |
368 | */ |
369 | void setMailAttachment(const QString &mailAttachFile); |
370 | |
371 | /** |
372 | Sets a list of filenames to attach to a mail message for an #Email |
373 | alarm type. Ignored if the alarm is not an #Email type. |
374 | |
375 | @param mailAttachFiles is a QString list of filenames to attach to |
376 | a mail message when an #Email type alarm is triggered. |
377 | |
378 | @see setMailSubject(), setMailText(), setMailAttachment(), |
379 | setMailAddress(), setMailAddresses() |
380 | */ |
381 | void setMailAttachments(const QStringList &mailAttachFiles); |
382 | |
383 | /** |
384 | Adds a filename to the list of files to attach to a mail message for |
385 | an #Email alarm type. Ignored if the alarm is not an #Email type. |
386 | |
387 | @param mailAttachFile is a string containing a filename to be attached |
388 | to an email message to send when the #Email type alarm is triggered. |
389 | |
390 | @see setMailAttachment(), setMailAttachments(), mailAttachments() |
391 | */ |
392 | void addMailAttachment(const QString &mailAttachFile); |
393 | |
394 | /** |
395 | Returns the list of attachment filenames for an #Email alarm type. |
396 | Returns an empty list if the alarm is not an #Email type. |
397 | |
398 | @see addMailAttachment(), setMailAttachment(), setMailAttachments() |
399 | */ |
400 | QStringList mailAttachments() const; |
401 | |
402 | /** |
403 | Sets the body text for an #Email alarm type. |
404 | Ignored if the alarm is not an #Email type. |
405 | |
406 | @param text is a string containing the body text of a mail message |
407 | when an #Email type alarm is triggered. |
408 | |
409 | @see setMailSubject(), setMailAddress(), setMailAddresses(), |
410 | setMailAttachment(), setMailAttachments() |
411 | */ |
412 | void setMailText(const QString &text); |
413 | |
414 | /** |
415 | Returns the body text for an #Email alarm type. |
416 | Returns an empty string if the alarm is not an #Email type. |
417 | |
418 | @see setMailText() |
419 | */ |
420 | QString mailText() const; |
421 | |
422 | /** |
423 | Sets the trigger time of the alarm. |
424 | |
425 | @param alarmTime is the KDateTime alarm trigger. |
426 | |
427 | @see time() |
428 | */ |
429 | void setTime(const KDateTime &alarmTime); |
430 | |
431 | /** |
432 | Returns the alarm trigger date/time. |
433 | |
434 | @see setTime() |
435 | */ |
436 | KDateTime time() const; |
437 | |
438 | /** |
439 | Returns the next alarm trigger date/time after given date/time. |
440 | Takes recurrent incidences into account. |
441 | |
442 | @param preTime date/time from where to start |
443 | @param ignoreRepetitions don't take repetitions into account |
444 | @see nextRepetition() |
445 | */ |
446 | KDateTime nextTime(const KDateTime &preTime, bool ignoreRepetitions = false) const; |
447 | |
448 | /** |
449 | Returns the date/time when the last repetition of the alarm goes off. |
450 | If the alarm does not repeat this is equivalent to calling time(). |
451 | |
452 | @see setTime() |
453 | */ |
454 | KDateTime endTime() const; |
455 | |
456 | /** |
457 | Returns true if the alarm has a trigger date/time. |
458 | */ |
459 | bool hasTime() const; |
460 | |
461 | /** |
462 | Sets the alarm offset relative to the start of the parent Incidence. |
463 | |
464 | @param offset is a Duration to be used as a time relative to the |
465 | start of the parent Incidence to be used as the alarm trigger. |
466 | |
467 | @see setEndOffset(), startOffset(), endOffset() |
468 | */ |
469 | void setStartOffset(const Duration &offset); |
470 | |
471 | /** |
472 | Returns offset of alarm in time relative to the start of the parent |
473 | Incidence. If the alarm's time is not defined in terms of an offset |
474 | relative to the start of the event, returns zero. |
475 | |
476 | @see setStartOffset(), hasStartOffset() |
477 | */ |
478 | Duration startOffset() const; |
479 | |
480 | /** |
481 | Returns whether the alarm is defined in terms of an offset relative |
482 | to the start of the parent Incidence. |
483 | |
484 | @see startOffset(), setStartOffset() |
485 | */ |
486 | bool hasStartOffset() const; |
487 | |
488 | /** |
489 | Sets the alarm offset relative to the end of the parent Incidence. |
490 | |
491 | @param offset is a Duration to be used as a time relative to the |
492 | end of the parent Incidence to be used as the alarm trigger. |
493 | |
494 | @see setStartOffset(), startOffset(), endOffset() |
495 | */ |
496 | void setEndOffset(const Duration &offset); |
497 | |
498 | /** |
499 | Returns offset of alarm in time relative to the end of the event. |
500 | If the alarm's time is not defined in terms of an offset relative |
501 | to the end of the event, returns zero. |
502 | |
503 | @see setEndOffset(), hasEndOffset() |
504 | */ |
505 | Duration endOffset() const; |
506 | |
507 | /** |
508 | Returns whether the alarm is defined in terms of an offset relative |
509 | to the end of the event. |
510 | |
511 | @see endOffset(), setEndOffset() |
512 | */ |
513 | bool hasEndOffset() const; |
514 | |
515 | /** |
516 | Shift the times of the alarm so that they appear at the same clock |
517 | time as before but in a new time zone. The shift is done from a viewing |
518 | time zone rather than from the actual alarm time zone. |
519 | |
520 | For example, shifting an alarm whose start time is 09:00 America/New York, |
521 | using an old viewing time zone (@p oldSpec) of Europe/London, to a new |
522 | time zone (@p newSpec) of Europe/Paris, will result in the time being |
523 | shifted from 14:00 (which is the London time of the alarm start) to |
524 | 14:00 Paris time. |
525 | |
526 | @param oldSpec the time specification which provides the clock times |
527 | @param newSpec the new time specification |
528 | */ |
529 | void shiftTimes(const KDateTime::Spec &oldSpec, |
530 | const KDateTime::Spec &newSpec); |
531 | |
532 | /** |
533 | Sets the snooze time interval for the alarm. |
534 | |
535 | @param alarmSnoozeTime the time between snoozes. |
536 | |
537 | @see snoozeTime() |
538 | */ |
539 | void setSnoozeTime(const Duration &alarmSnoozeTime); |
540 | |
541 | /** |
542 | Returns the snooze time interval. |
543 | |
544 | @see setSnoozeTime() |
545 | */ |
546 | Duration snoozeTime() const; |
547 | |
548 | /** |
549 | Sets how many times an alarm is to repeat itself after its initial |
550 | occurrence (w/snoozes). |
551 | |
552 | @param alarmRepeatCount is the number of times an alarm may repeat, |
553 | excluding the initial occurrence. |
554 | |
555 | @see repeatCount() |
556 | */ |
557 | void setRepeatCount(int alarmRepeatCount); |
558 | |
559 | /** |
560 | Returns how many times an alarm may repeats after its initial occurrence. |
561 | |
562 | @see setRepeatCount() |
563 | */ |
564 | int repeatCount() const; |
565 | |
566 | /** |
567 | Returns the date/time of the alarm's initial occurrence or its next |
568 | repetition after a given time. |
569 | |
570 | @param preTime the date/time after which to find the next repetition. |
571 | |
572 | @return the date/time of the next repetition, or an invalid date/time |
573 | if the specified time is at or after the alarm's last repetition. |
574 | |
575 | @see previousRepetition() |
576 | */ |
577 | KDateTime nextRepetition(const KDateTime &preTime) const; |
578 | |
579 | /** |
580 | Returns the date/time of the alarm's latest repetition or, if none, |
581 | its initial occurrence before a given time. |
582 | |
583 | @param afterTime is the date/time before which to find the latest |
584 | repetition. |
585 | |
586 | @return the date and time of the latest repetition, or an invalid |
587 | date/time if the specified time is at or before the alarm's initial |
588 | occurrence. |
589 | |
590 | @see nextRepetition() |
591 | */ |
592 | KDateTime previousRepetition(const KDateTime &afterTime) const; |
593 | |
594 | /** |
595 | Returns the interval between the alarm's initial occurrence and |
596 | its final repetition. |
597 | */ |
598 | Duration duration() const; |
599 | |
600 | /** |
601 | Toggles the alarm status, i.e, an enable alarm becomes disabled |
602 | and a disabled alarm becomes enabled. |
603 | |
604 | @see enabled(), setEnabled() |
605 | */ |
606 | void toggleAlarm(); |
607 | |
608 | /** |
609 | Sets the enabled status of the alarm. |
610 | @param enable if true, then enable the alarm; else disable the alarm. |
611 | |
612 | @see enabled(), toggleAlarm() |
613 | */ |
614 | void setEnabled(bool enable); |
615 | |
616 | /** |
617 | Returns the alarm enabled status: true (enabled) or false (disabled). |
618 | |
619 | @see setEnabled(), toggleAlarm() |
620 | */ |
621 | bool enabled() const; |
622 | |
623 | /** |
624 | Set if the location radius for the alarm has been defined. |
625 | @param hasLocationRadius if true, then this alarm has a location radius. |
626 | |
627 | @see setLocationRadius() |
628 | */ |
629 | void setHasLocationRadius(bool hasLocationRadius); |
630 | |
631 | /** |
632 | Returns true if alarm has location radius defined. |
633 | |
634 | @see setLocationRadius() |
635 | */ |
636 | bool hasLocationRadius() const; |
637 | |
638 | /** |
639 | Set location radius for the alarm. This means that alarm will be |
640 | triggered when user approaches the location. Given value will be |
641 | stored into custom properties as X-LOCATION-RADIUS. |
642 | |
643 | @param locationRadius radius in meters |
644 | @see locationRadius() |
645 | */ |
646 | void setLocationRadius(int locationRadius); |
647 | |
648 | /** |
649 | Returns the location radius in meters. |
650 | |
651 | @see setLocationRadius() |
652 | */ |
653 | int locationRadius() const; |
654 | |
655 | protected: |
656 | /** |
657 | @copydoc |
658 | CustomProperties::customPropertyUpdated() |
659 | */ |
660 | virtual void customPropertyUpdated(); |
661 | |
662 | /** |
663 | @copydoc |
664 | IncidenceBase::virtual_hook() |
665 | */ |
666 | virtual void virtual_hook(int id, void *data); |
667 | |
668 | private: |
669 | //@cond PRIVATE |
670 | class Private; |
671 | Private *const d; |
672 | //@endcond |
673 | friend KCALCORE_EXPORT QDataStream &operator<<(QDataStream &s, const KCalCore::Alarm::Ptr &); |
674 | friend KCALCORE_EXPORT QDataStream &operator>>(QDataStream &s, const KCalCore::Alarm::Ptr &); |
675 | }; |
676 | /** |
677 | * Alarm serializer. |
678 | * |
679 | * @since 4.12 |
680 | */ |
681 | KCALCORE_EXPORT QDataStream &operator<<(QDataStream &out, const KCalCore::Alarm::Ptr &); |
682 | |
683 | /** |
684 | * Alarm deserializer. |
685 | * |
686 | * @since 4.12 |
687 | */ |
688 | KCALCORE_EXPORT QDataStream &operator>>(QDataStream &in, const KCalCore::Alarm::Ptr &); |
689 | |
690 | } |
691 | |
692 | //@cond PRIVATE |
693 | Q_DECLARE_TYPEINFO(KCalCore::Alarm::Ptr, Q_MOVABLE_TYPE); |
694 | Q_DECLARE_METATYPE(KCalCore::Alarm::Ptr) |
695 | //@endcond |
696 | |
697 | #endif |
698 | |