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
47namespace KCalCore {
48
49class 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*/
61class KCALCORE_EXPORT Alarm : public CustomProperties
62{
63public:
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
655protected:
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
668private:
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 */
681KCALCORE_EXPORT QDataStream &operator<<(QDataStream &out, const KCalCore::Alarm::Ptr &);
682
683/**
684 * Alarm deserializer.
685 *
686 * @since 4.12
687 */
688KCALCORE_EXPORT QDataStream &operator>>(QDataStream &in, const KCalCore::Alarm::Ptr &);
689
690}
691
692//@cond PRIVATE
693Q_DECLARE_TYPEINFO(KCalCore::Alarm::Ptr, Q_MOVABLE_TYPE);
694Q_DECLARE_METATYPE(KCalCore::Alarm::Ptr)
695//@endcond
696
697#endif
698