KCalendarCore

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

KDE's Doxygen guidelines are available online.