summaryrefslogtreecommitdiffabout
path: root/libkcal/alarm.h
Unidiff
Diffstat (limited to 'libkcal/alarm.h') (more/less context) (ignore whitespace changes)
-rw-r--r--libkcal/alarm.h245
1 files changed, 245 insertions, 0 deletions
diff --git a/libkcal/alarm.h b/libkcal/alarm.h
new file mode 100644
index 0000000..ae2eca3
--- a/dev/null
+++ b/libkcal/alarm.h
@@ -0,0 +1,245 @@
1/*
2 This file is part of libkcal.
3 Copyright (c) 2001 Cornelius Schumacher <schumacher@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
19*/
20
21#ifndef KCAL_ALARM_H
22#define KCAL_ALARM_H
23
24#include <qstring.h>
25#include <qvaluelist.h>
26
27#include "customproperties.h"
28#include "duration.h"
29#include "person.h"
30
31namespace KCal {
32
33class Incidence;
34
35/**
36 This class represents an alarm notification.
37*/
38class Alarm : public CustomProperties
39{
40 public:
41 enum Type { Invalid, Display, Procedure, Email, Audio };
42 typedef QValueList<Alarm *> List;
43
44 /** Construct a new alarm with variables initialized to "sane" values. */
45 explicit Alarm(Incidence *parent);
46 /** Destruct Alarm object. */
47 ~Alarm();
48
49 /** Compare this alarm with another one. */
50 bool operator==(const Alarm &) const;
51 bool operator!=(const Alarm &a) const { return !operator==(a); }
52
53 /** Set the type of the alarm.
54 If the specified type is different from the current type of the alarm,
55 the alarm's type-specific properties are initialised to null.
56 @param type type of alarm.
57 */
58 void setType(Type type);
59 /** Return the type of the alarm */
60 Type type() const;
61
62 /** Set the alarm to be a display alarm.
63 @param text text to display when the alarm is triggered.
64 */
65 void setDisplayAlarm(const QString &text);
66 /** Set the text to be displayed when the alarm is triggered.
67 Ignored if the alarm is not a display alarm.
68 */
69 void setText(const QString &text);
70 /** Return the text string that displays when the alarm is triggered. */
71 QString text() const;
72
73 /** Set the alarm to be an audio alarm.
74 @param audioFile optional file to play when the alarm is triggered.
75 */
76 void setAudioAlarm(const QString &audioFile = QString::null);
77 /** Set the file to play when the audio alarm is triggered.
78 Ignored if the alarm is not an audio alarm.
79 */
80 void setAudioFile(const QString &audioFile);
81 /** Return the name of the audio file for the alarm.
82 @return The audio file for the alarm, or QString::null if not an audio alarm.
83 */
84 QString audioFile() const;
85
86 /** Set the alarm to be a procedure alarm.
87 @param programFile program to execute when the alarm is triggered.
88 @param arguments arguments to supply to programFile.
89 */
90 void setProcedureAlarm(const QString &programFile, const QString &arguments = QString::null);
91 /** Set the program file to execute when the alarm is triggered.
92 Ignored if the alarm is not a procedure alarm.
93 */
94 void setProgramFile(const QString &programFile);
95 /** Return the name of the program file to execute when the alarm is triggered.
96 @return the program file name, or QString::null if not a procedure alarm.
97 */
98 QString programFile() const;
99 /** Set the arguments to the program to execute when the alarm is triggered.
100 Ignored if the alarm is not a procedure alarm.
101 */
102 void setProgramArguments(const QString &arguments);
103 /** Return the arguments to the program to run when the alarm is triggered.
104 @return the program arguments, or QString::null if not a procedure alarm.
105 */
106 QString programArguments() const;
107
108 /** Set the alarm to be an email alarm.
109 @param subject subject line of email.
110 @param text body of email.
111 @param addressees email addresses of recipient(s).
112 @param attachments optional names of files to attach to the email.
113 */
114 void setEmailAlarm(const QString &subject, const QString &text, const QValueList<Person> &addressees,
115 const QStringList &attachments = QStringList());
116
117 /** Send mail to this address when the alarm is triggered.
118 Ignored if the alarm is not an email alarm.
119 */
120 void setMailAddress(const Person &mailAlarmAddress);
121 /** Send mail to these addresses when the alarm is triggered.
122 Ignored if the alarm is not an email alarm.
123 */
124 void setMailAddresses(const QValueList<Person> &mailAlarmAddresses);
125 /** Add this address to the list of addresses to send mail to when the alarm is triggered.
126 Ignored if the alarm is not an email alarm.
127 */
128 void addMailAddress(const Person &mailAlarmAddress);
129 /** return the addresses to send mail to when an alarm goes off */
130 QValueList<Person> mailAddresses() const;
131
132 /** Set the subject line of the mail.
133 Ignored if the alarm is not an email alarm.
134 */
135 void setMailSubject(const QString &mailAlarmSubject);
136 /** return the subject line of the mail */
137 QString mailSubject() const;
138
139 /** Attach this filename to the email.
140 Ignored if the alarm is not an email alarm.
141 */
142 void setMailAttachment(const QString &mailAttachFile);
143 /** Attach these filenames to the email.
144 Ignored if the alarm is not an email alarm.
145 */
146 void setMailAttachments(const QStringList &mailAttachFiles);
147 /** Add this filename to the list of files to attach to the email.
148 Ignored if the alarm is not an email alarm.
149 */
150 void addMailAttachment(const QString &mailAttachFile);
151 /** return the filenames to attach to the email */
152 QStringList mailAttachments() const;
153
154 /** Set the email body text.
155 Ignored if the alarm is not an email alarm.
156 */
157 void setMailText(const QString &text);
158 /** Return the email body text.
159 @return the body text, or QString::null if not an email alarm.
160 */
161 QString mailText() const;
162
163 /** set the time to trigger an alarm */
164 void setTime(const QDateTime &alarmTime);
165 /** return the date/time when an alarm goes off */
166 QDateTime time() const;
167 /** Return true, if the alarm has an explicit date/time. */
168 bool hasTime() const;
169
170 /** Set offset of alarm in time relative to the start of the event. */
171 void setStartOffset(const Duration &);
172 /** Return offset of alarm in time relative to the start of the event.
173 * If the alarm's time is not defined in terms of an offset relative
174 * to the start of the event, returns zero.
175 */
176 Duration startOffset() const;
177 /** Return whether the alarm is defined in terms of an offset relative
178 * to the start of the event.
179 */
180 bool hasStartOffset() const;
181
182 /** Set offset of alarm in time relative to the end of the event. */
183 void setEndOffset(const Duration &);
184 /** Return offset of alarm in time relative to the end of the event.
185 * If the alarm's time is not defined in terms of an offset relative
186 * to the end of the event, returns zero.
187 */
188 Duration endOffset() const;
189 /** Return whether the alarm is defined in terms of an offset relative
190 * to the end of the event.
191 */
192 bool hasEndOffset() const;
193
194 /** Set the interval between snoozes for the alarm.
195 @param snoozeTime the time in minutes between snoozes.
196 */
197 void setSnoozeTime(int alarmSnoozeTime);
198 /** Get how long the alarm snooze interval is.
199 @return the number of minutes between snoozes.
200 */
201 int snoozeTime() const;
202
203 /** set how many times an alarm is to repeat itself (w/snoozes) */
204 void setRepeatCount(int alarmRepeatCount);
205 /** get how many times an alarm repeats */
206 int repeatCount() const;
207
208 /** toggles the value of alarm to be either on or off.
209 set's the alarm time to be x minutes before dtStart time. */
210 void toggleAlarm();
211
212 /** set the alarm enabled status */
213 void setEnabled(bool enable);
214 /** get the alarm enabled status */
215 bool enabled() const;
216
217 /** Set the alarm's parent incidence */
218 void setParent( Incidence * );
219 /** get the alarm's parent incidence */
220 Incidence *parent() const { return mParent; }
221
222 private:
223 Incidence *mParent; // the incidence which this alarm belongs to
224 Type mType; // type of alarm
225 QString mDescription; // text to display/email body/procedure arguments
226 QString mFile; // procedure program to run/optional audio file to play
227 QStringList mMailAttachFiles; // filenames to attach to email
228 QValueList<Person> mMailAddresses; // who to mail for reminder
229 QString mMailSubject; // subject of email
230
231 int mAlarmSnoozeTime; // number of minutes after alarm to
232 // snooze before ringing again
233 int mAlarmRepeatCount; // number of times for alarm to repeat
234 // after the initial time
235
236 QDateTime mAlarmTime; // time at which to trigger the alarm
237 Duration mOffset; // time relative to incidence DTSTART to trigger the alarm
238 bool mEndOffset; // if true, mOffset relates to DTEND, not DTSTART
239 bool mHasTime; // use mAlarmTime, not mOffset
240 bool mAlarmEnabled;
241};
242
243}
244
245#endif