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 | |
48 | namespace boost { |
49 | template <typename T> class shared_ptr; |
50 | } |
51 | |
52 | namespace KCal { |
53 | |
54 | class 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 | */ |
66 | class 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 | |