1/*
2 This file is part of the kcal 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 KCAL_ALARM_H
32#define KCAL_ALARM_H
33
34#include <QtCore/QString>
35#include <QtCore/QStringList>
36#include <QtCore/QList>
37
38#include <kdatetime.h>
39
40#include "customproperties.h"
41#include "duration.h"
42#include "person.h"
43#include "listbase.h"
44#include "kcal_export.h"
45
46#include <kpimutils/supertrait.h>
47
48namespace boost {
49 template <typename T> class shared_ptr;
50}
51
52namespace KCal {
53
54class Incidence;
55
56/**
57 @brief
58 Represents an alarm notification.
59
60 Alarms are user notifications that occur at specified times.
61 Notifications can be on-screen pop-up dialogs, email messages,
62 the playing of audio files, or the running of another program.
63
64 Alarms always belong to a parent Incidence.
65*/
66class KCAL_DEPRECATED_EXPORT Alarm : public CustomProperties
67{
68 public:
69 /**
70 The different types of alarms.
71 */
72 enum Type {
73 Invalid, /**< Invalid, or no alarm */
74 Display, /**< Display a dialog box */
75 Procedure, /**< Call a script */
76 Email, /**< Send email */
77 Audio /**< Play an audio file */
78 };
79
80 /**
81 List of alarms.
82 */
83 typedef ListBase<Alarm> List;
84
85 /**
86 A shared pointer to a Alarm object.
87 */
88 typedef boost::shared_ptr<Alarm> Ptr;
89
90 /**
91 Constructs an alarm belonging to the @p parent Incidence.
92
93 @param parent is the Incidence this alarm will belong to.
94 */
95 explicit Alarm( Incidence *parent );
96
97 /**
98 Copy constructor.
99 @param other is the alarm to copy.
100 */
101 Alarm( const Alarm &other );
102
103 /**
104 Destroys the alarm.
105 */
106 virtual ~Alarm();
107
108 /**
109 Assignment operator.
110 @since 4.5
111 */
112 Alarm &operator=( const Alarm & );
113
114 /**
115 Compares two alarms for equality.
116 @param a is the comparison alarm.
117 */
118 bool operator==( const Alarm &a ) const;
119
120 /**
121 Compares two alarms for inequality.
122
123 @param a is the comparison alarm.
124 */
125 bool operator!=( const Alarm &a ) const { return !operator==( a ); }
126
127 /**
128 Sets the @p parent Incidence of the alarm.
129
130 @param parent is alarm parent Incidence to set.
131
132 @see parent()
133 */
134 void setParent( Incidence *parent );
135
136 /**
137 Returns a pointer to the parent incidence of the alarm.
138
139 @see setParent()
140 */
141 Incidence *parent() const;
142
143 /**
144 Sets the #Type for this alarm to @p type.
145 If the specified type is different from the current type of the alarm,
146 then the alarm's type-specific properties are re-initialized.
147
148 @param type is the alarm #Type to set.
149
150 @see type()
151 */
152 void setType( Type type );
153
154 /**
155 Returns the #Type of the alarm.
156
157 @see setType()
158 */
159 Type type() const;
160
161 /**
162 Sets the #Display type for this alarm.
163 If @p text is specified non-empty, then it is used as the description
164 text to display when the alarm is triggered.
165
166 @param text is the description to display when the alarm is triggered.
167
168 @see setText(), text()
169 */
170 void setDisplayAlarm( const QString &text = QString() );
171
172 /**
173 Sets the description @p text to be displayed when the alarm is triggered.
174 Ignored if the alarm is not a display alarm.
175
176 @param text is the description to display when the alarm is triggered.
177
178 @see setDisplayAlarm(), text()
179 */
180 void setText( const QString &text );
181
182 /**
183 Returns the display text string for a #Display alarm type.
184 Returns an empty string if the alarm is not a #Display type.
185
186 @see setDisplayAlarm(), setText()
187 */
188 QString text() const;
189
190 /**
191 Sets the #Audio type for this alarm and the name of the audio file
192 to play when the alarm is triggered.
193
194 @param audioFile is the name of the audio file to play when the alarm
195 is triggered.
196
197 @see setAudioFile(), audioFile()
198 */
199 void setAudioAlarm( const QString &audioFile = QString() );
200
201 /**
202 Sets the name of the audio file to play when the audio alarm is triggered.
203 Ignored if the alarm is not an #Audio type.
204
205 @param audioFile is the name of the audio file to play when the alarm
206 is triggered.
207
208 @see setAudioAlarm(), audioFile()
209 */
210 void setAudioFile( const QString &audioFile );
211
212 /**
213 Returns the audio file name for an #Audio alarm type.
214 Returns an empty string if the alarm is not an #Audio type.
215
216 @see setAudioAlarm(), setAudioFile()
217 */
218 QString audioFile() const;
219
220 /**
221 Sets the #Procedure type for this alarm and the program (with arguments)
222 to execute when the alarm is triggered.
223
224 @param programFile is the name of the program file to execute when
225 the alarm is triggered.
226 @param arguments is a string of arguments to supply to @p programFile.
227
228 @see setProgramFile(), programFile(),
229 setProgramArguments(), programArguments()
230 */
231 void setProcedureAlarm( const QString &programFile,
232 const QString &arguments = QString() );
233
234 /**
235 Sets the program file to execute when the alarm is triggered.
236 Ignored if the alarm is not a #Procedure type.
237
238 @param programFile is the name of the program file to execute when
239 the alarm is triggered.
240
241 @see setProcedureAlarm(), programFile(),
242 setProgramArguments(), programArguments()
243 */
244 void setProgramFile( const QString &programFile );
245
246 /**
247 Returns the program file name for a #Procedure alarm type.
248 Returns an empty string if the alarm is not a #Procedure type.
249
250 @see setProcedureAlarm(), setProgramFile(),
251 setProgramArguments(), programArguments()
252 */
253 QString programFile() const;
254
255 /**
256 Sets the program arguments string when the alarm is triggered.
257 Ignored if the alarm is not a #Procedure type.
258
259 @param arguments is a string of arguments to supply to the program.
260
261 @see setProcedureAlarm(), setProgramFile(), programFile(),
262 programArguments()
263 */
264 void setProgramArguments( const QString &arguments );
265
266 /**
267 Returns the program arguments string for a #Procedure alarm type.
268 Returns an empty string if the alarm is not a #Procedure type.
269
270 @see setProcedureAlarm(), setProgramFile(), programFile(),
271 setProgramArguments()
272 */
273 QString programArguments() const;
274
275 /**
276 Sets the #Email type for this alarm and the email @p subject, @p text,
277 @p addresses, and @p attachments that make up an email message to be
278 sent when the alarm is triggered.
279
280 @param subject is the email subject.
281 @param text is a string containing the body of the email message.
282 @param addressees is Person list of email addresses.
283 @param attachments is a a QStringList of optional file names
284 of email attachments.
285
286 @see setMailSubject(), setMailText(), setMailAddresses(),
287 setMailAttachments()
288 */
289 void setEmailAlarm( const QString &subject, const QString &text,
290 const QList<Person> &addressees,
291 const QStringList &attachments = QStringList() );
292
293 /**
294 Sets the email address of an #Email type alarm.
295 Ignored if the alarm is not an #Email type.
296
297 @param mailAlarmAddress is a Person to receive a mail message when
298 an #Email type alarm is triggered.
299
300 @see setMailSubject(), setMailText(), setMailAddresses(),
301 setMailAttachment(), setMailAttachments(), mailAddresses()
302 */
303 void setMailAddress( const Person &mailAlarmAddress );
304
305 /**
306 Sets a list of email addresses of an #Email type alarm.
307 Ignored if the alarm is not an #Email type.
308
309 @param mailAlarmAddresses is a Person list to receive a mail message
310 when an #Email type alarm is triggered.
311
312 @see setMailSubject(), setMailText(), setMailAddress(),
313 setMailAttachments(), setMailAttachment(), mailAddresses()
314 */
315 void setMailAddresses( const QList<Person> &mailAlarmAddresses );
316
317 /**
318 Adds an address to the list of email addresses to send mail to when the
319 alarm is triggered.
320 Ignored if the alarm is not an #Email type.
321
322 @param mailAlarmAddress is a Person to add to the list of addresses to
323 receive a mail message when an #Email type alarm is triggered.
324
325 @see setMailAddress(), setMailAddresses(), mailAddresses()
326 */
327 void addMailAddress( const Person &mailAlarmAddress );
328
329 /**
330 Returns the list of addresses for an #Email alarm type.
331 Returns an empty list if the alarm is not an #Email type.
332
333 @see addMailAddress(), setMailAddress(), setMailAddresses()
334 */
335 QList<Person> mailAddresses() const;
336
337 /**
338 Sets the subject line of a mail message for an #Email alarm type.
339 Ignored if the alarm is not an #Email type.
340
341 @param mailAlarmSubject is a string to be used as a subject line
342 of an email message to send when the #Email type alarm is triggered.
343
344 @see setMailText(), setMailAddress(), setMailAddresses(),
345 setMailAttachment(), setMailAttachments(), mailSubject()
346 */
347 void setMailSubject( const QString &mailAlarmSubject );
348
349 /**
350 Returns the subject line string for an #Email alarm type.
351 Returns an empty string if the alarm is not an #Email type.
352
353 @see setMailSubject()
354 */
355 QString mailSubject() const;
356
357 /**
358 Sets the filename to attach to a mail message for an #Email alarm type.
359 Ignored if the alarm is not an #Email type.
360
361 @param mailAttachFile is a string containing a filename to be attached
362 to an email message to send when the #Email type alarm is triggered.
363
364 @see setMailSubject(), setMailText(), setMailAddress(),
365 setMailAddresses(), setMailAttachments(), mailAttachments()
366 */
367 void setMailAttachment( const QString &mailAttachFile );
368
369 /**
370 Sets a list of filenames to attach to a mail message for an #Email
371 alarm type. Ignored if the alarm is not an #Email type.
372
373 @param mailAttachFiles is a QString list of filenames to attach to
374 a mail message when an #Email type alarm is triggered.
375
376 @see setMailSubject(), setMailText(), setMailAttachment(),
377 setMailAddress(), setMailAddresses()
378 */
379 void setMailAttachments( const QStringList &mailAttachFiles );
380
381 /**
382 Adds a filename to the list of files to attach to a mail message for
383 an #Email alarm type. Ignored if the alarm is not an #Email type.
384
385 @param mailAttachFile is a string containing a filename to be attached
386 to an email message to send when the #Email type alarm is triggered.
387
388 @see setMailAttachment(), setMailAttachments(), mailAttachments()
389 */
390 void addMailAttachment( const QString &mailAttachFile );
391
392 /**
393 Returns the list of attachment filenames for an #Email alarm type.
394 Returns an empty list if the alarm is not an #Email type.
395
396 @see addMailAttachment(), setMailAttachment(), setMailAttachments()
397 */
398 QStringList mailAttachments() const;
399
400 /**
401 Sets the body text for an #Email alarm type.
402 Ignored if the alarm is not an #Email type.
403
404 @param text is a string containing the body text of a mail message
405 when an #Email type alarm is triggered.
406
407 @see setMailSubject(), setMailAddress(), setMailAddresses(),
408 setMailAttachment(), setMailAttachments()
409 */
410 void setMailText( const QString &text );
411
412 /**
413 Returns the body text for an #Email alarm type.
414 Returns an empty string if the alarm is not an #Email type.
415
416 @see setMailText()
417 */
418 QString mailText() const;
419
420 /**
421 Sets the trigger time of the alarm.
422
423 @param alarmTime is the KDateTime alarm trigger.
424
425 @see time()
426 */
427 void setTime( const KDateTime &alarmTime );
428
429 /**
430 Returns the alarm trigger date/time.
431
432 @see setTime()
433 */
434 KDateTime time() const;
435
436 /**
437 Returns the date/time when the last repetition of the alarm goes off.
438 If the alarm does not repeat this is equivalent to calling time().
439
440 @see setTime()
441 */
442 KDateTime endTime() const;
443
444 /**
445 Returns true if the alarm has a trigger date/time.
446 */
447 bool hasTime() const;
448
449 /**
450 Sets the alarm offset relative to the start of the parent Incidence.
451
452 @param offset is a Duration to be used as a time relative to the
453 start of the parent Incidence to be used as the alarm trigger.
454
455 @see setEndOffset(), startOffset(), endOffset()
456 */
457 void setStartOffset( const Duration &offset );
458
459 /**
460 Returns offset of alarm in time relative to the start of the parent
461 Incidence. If the alarm's time is not defined in terms of an offset
462 relative to the start of the event, returns zero.
463
464 @see setStartOffset(), hasStartOffset()
465 */
466 Duration startOffset() const;
467
468 /**
469 Returns whether the alarm is defined in terms of an offset relative
470 to the start of the parent Incidence.
471
472 @see startOffset(), setStartOffset()
473 */
474 bool hasStartOffset() const;
475
476 /**
477 Sets the alarm offset relative to the end of the parent Incidence.
478
479 @param offset is a Duration to be used as a time relative to the
480 end of the parent Incidence to be used as the alarm trigger.
481
482 @see setStartOffset(), startOffset(), endOffset()
483 */
484 void setEndOffset( const Duration &offset );
485
486 /**
487 Returns offset of alarm in time relative to the end of the event.
488 If the alarm's time is not defined in terms of an offset relative
489 to the end of the event, returns zero.
490
491 @see setEndOffset(), hasEndOffset()
492 */
493 Duration endOffset() const;
494
495 /**
496 Returns whether the alarm is defined in terms of an offset relative
497 to the end of the event.
498
499 @see endOffset(), setEndOffset()
500 */
501 bool hasEndOffset() const;
502
503 /**
504 Shift the times of the alarm so that they appear at the same clock
505 time as before but in a new time zone. The shift is done from a viewing
506 time zone rather than from the actual alarm time zone.
507
508 For example, shifting an alarm whose start time is 09:00 America/New York,
509 using an old viewing time zone (@p oldSpec) of Europe/London, to a new
510 time zone (@p newSpec) of Europe/Paris, will result in the time being
511 shifted from 14:00 (which is the London time of the alarm start) to
512 14:00 Paris time.
513
514 @param oldSpec the time specification which provides the clock times
515 @param newSpec the new time specification
516 */
517 void shiftTimes( const KDateTime::Spec &oldSpec,
518 const KDateTime::Spec &newSpec );
519
520 /**
521 Sets the snooze time interval for the alarm.
522
523 @param alarmSnoozeTime the time between snoozes.
524
525 @see snoozeTime()
526 */
527 void setSnoozeTime( const Duration &alarmSnoozeTime );
528
529 /**
530 Returns the snooze time interval.
531
532 @see setSnoozeTime()
533 */
534 Duration snoozeTime() const;
535
536 /**
537 Sets how many times an alarm is to repeat itself after its initial
538 occurrence (w/snoozes).
539
540 @param alarmRepeatCount is the number of times an alarm may repeat,
541 excluding the initial occurrence.
542
543 @see repeatCount()
544 */
545 void setRepeatCount( int alarmRepeatCount );
546
547 /**
548 Returns how many times an alarm may repeats after its initial occurrence.
549
550 @see setRepeatCount()
551 */
552 int repeatCount() const;
553
554 /**
555 Returns the date/time of the alarm's initial occurrence or its next
556 repetition after a given time.
557
558 @param preTime the date/time after which to find the next repetition.
559
560 @return the date/time of the next repetition, or an invalid date/time
561 if the specified time is at or after the alarm's last repetition.
562
563 @see previousRepetition()
564 */
565 KDateTime nextRepetition( const KDateTime &preTime ) const;
566
567 /**
568 Returns the date/time of the alarm's latest repetition or, if none,
569 its initial occurrence before a given time.
570
571 @param afterTime is the date/time before which to find the latest
572 repetition.
573
574 @return the date and time of the latest repetition, or an invalid
575 date/time if the specified time is at or before the alarm's initial
576 occurrence.
577
578 @see nextRepetition()
579 */
580 KDateTime previousRepetition( const KDateTime &afterTime ) const;
581
582 /**
583 Returns the interval between the alarm's initial occurrence and
584 its final repetition.
585 */
586 Duration duration() const;
587
588 /**
589 Toggles the alarm status, i.e, an enable alarm becomes disabled
590 and a disabled alarm becomes enabled.
591
592 @see enabled(), setEnabled()
593 */
594 void toggleAlarm();
595
596 /**
597 Sets the enabled status of the alarm.
598
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 bool enabled() const;
611
612 protected:
613 /**
614 @copydoc
615 CustomProperties::customPropertyUpdated()
616 */
617 virtual void customPropertyUpdated();
618
619 private:
620 //@cond PRIVATE
621 class Private;
622 Private *const d;
623 //@endcond
624};
625
626}
627
628#endif
629