diff options
Diffstat (limited to 'libkcal/alarm.h')
| -rw-r--r-- | libkcal/alarm.h | 370 |
1 files changed, 370 insertions, 0 deletions
diff --git a/libkcal/alarm.h b/libkcal/alarm.h new file mode 100644 index 000000000..64970e639 --- /dev/null +++ b/libkcal/alarm.h @@ -0,0 +1,370 @@ +/* + This file is part of libkcal. + + Copyright (c) 2001-2003 Cornelius Schumacher <schumacher@kde.org> + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. +*/ + +#ifndef KCAL_ALARM_H +#define KCAL_ALARM_H + +#include <qstring.h> +#include <qstringlist.h> +#include <qvaluelist.h> + +#include "customproperties.h" +#include "duration.h" +#include "person.h" +#include "listbase.h" +#include "libkcal_export.h" + +#include <kdepimmacros.h> + +namespace KCal { + +class Incidence; + +/** + This class represents an alarm notification. +*/ +class LIBKCAL_EXPORT Alarm : public CustomProperties +{ + public: + enum Type { Invalid, Display, Procedure, Email, Audio }; + + typedef ListBase<Alarm> List; + + /** + Construct a new alarm with variables initialized to "sane" values. + */ + explicit Alarm( Incidence *parent ); + /** + Destruct Alarm object. + */ + ~Alarm(); + + /** + Compare this alarm with another one. + */ + bool operator==( const Alarm & ) const; + bool operator!=( const Alarm &a ) const { return !operator==( a ); } + + /** + Set the type of the alarm. + If the specified type is different from the current type of the alarm, + the alarm's type-specific properties are initialised to null. + + @param type type of alarm. + */ + void setType( Type type ); + /** + Return the type of the alarm. + */ + Type type() const; + + /** + Set the alarm to be a display alarm. + + @param text text to display when the alarm is triggered. + */ + void setDisplayAlarm( const QString &text = QString::null ); + /** + Set the text to be displayed when the alarm is triggered. + Ignored if the alarm is not a display alarm. + */ + void setText( const QString &text ); + /** + Return the text string that displays when the alarm is triggered. + */ + QString text() const; + + /** + Set the alarm to be an audio alarm. + + @param audioFile optional file to play when the alarm is triggered. + */ + void setAudioAlarm( const QString &audioFile = QString::null ); + /** + Set the file to play when the audio alarm is triggered. + Ignored if the alarm is not an audio alarm. + */ + void setAudioFile( const QString &audioFile ); + /** + Return the name of the audio file for the alarm. + + @return The audio file for the alarm, or QString::null if not an audio alarm. + */ + QString audioFile() const; + + /** + Set the alarm to be a procedure alarm. + + @param programFile program to execute when the alarm is triggered. + @param arguments arguments to supply to programFile. + */ + void setProcedureAlarm( const QString &programFile, + const QString &arguments = QString::null ); + /** + Set the program file to execute when the alarm is triggered. + Ignored if the alarm is not a procedure alarm. + */ + void setProgramFile( const QString &programFile ); + /** + Return the name of the program file to execute when the alarm is triggered. + + @return the program file name, or QString::null if not a procedure alarm. + */ + QString programFile() const; + /** + Set the arguments to the program to execute when the alarm is triggered. + Ignored if the alarm is not a procedure alarm. + */ + void setProgramArguments( const QString &arguments ); + /** + Return the arguments to the program to run when the alarm is triggered. + + @return the program arguments, or QString::null if not a procedure alarm. + */ + QString programArguments() const; + + /** + Set the alarm to be an email alarm. + + @param subject subject line of email. + @param text body of email. + @param addressees email addresses of recipient(s). + @param attachments optional names of files to attach to the email. + */ + void setEmailAlarm( const QString &subject, const QString &text, + const QValueList<Person> &addressees, + const QStringList &attachments = QStringList() ); + + /** + Send mail to this address when the alarm is triggered. + Ignored if the alarm is not an email alarm. + */ + void setMailAddress( const Person &mailAlarmAddress ); + /** + Send mail to these addresses when the alarm is triggered. + Ignored if the alarm is not an email alarm. + */ + void setMailAddresses( const QValueList<Person> &mailAlarmAddresses ); + /** + Add this address to the list of addresses to send mail to when the alarm is triggered. + Ignored if the alarm is not an email alarm. + */ + void addMailAddress( const Person &mailAlarmAddress ); + /** + Return the addresses to send mail to when an alarm goes off. + */ + QValueList<Person> mailAddresses() const; + + /** + Set the subject line of the mail. + Ignored if the alarm is not an email alarm. + */ + void setMailSubject( const QString &mailAlarmSubject ); + /** + Return the subject line of the mail. + */ + QString mailSubject() const; + + /** + Attach this filename to the email. + Ignored if the alarm is not an email alarm. + */ + void setMailAttachment( const QString &mailAttachFile ); + /** + Attach these filenames to the email. + Ignored if the alarm is not an email alarm. + */ + void setMailAttachments( const QStringList &mailAttachFiles ); + /** + Add this filename to the list of files to attach to the email. + Ignored if the alarm is not an email alarm. + */ + void addMailAttachment( const QString &mailAttachFile ); + /** + Return the filenames to attach to the email. + */ + QStringList mailAttachments() const; + + /** + Set the email body text. + Ignored if the alarm is not an email alarm. + */ + void setMailText( const QString &text ); + /** + Return the email body text. + + @return the body text, or QString::null if not an email alarm. + */ + QString mailText() const; + + /** + Set the time to trigger an alarm. + */ + void setTime( const QDateTime &alarmTime ); + /** + Return the date/time when an alarm goes off. + */ + QDateTime time() const; + /** + Return the date/time when the last repetition of the alarm goes off. + If the alarm does not repeat, this is equivalent to calling time(). + */ + QDateTime endTime() const; + /** + Return true, if the alarm has an explicit date/time. + */ + bool hasTime() const; + + /** + Set offset of alarm in time relative to the start of the event. + */ + void setStartOffset( const Duration & ); + /** + Return offset of alarm in time relative to the start of the event. + If the alarm's time is not defined in terms of an offset relative + to the start of the event, returns zero. + */ + Duration startOffset() const; + /** + Return whether the alarm is defined in terms of an offset relative + to the start of the event. + */ + bool hasStartOffset() const; + + /** + Set offset of alarm in time relative to the end of the event. + */ + void setEndOffset( const Duration & ); + /** + Return offset of alarm in time relative to the end of the event. + If the alarm's time is not defined in terms of an offset relative + to the end of the event, returns zero. + */ + Duration endOffset() const; + /** + Return whether the alarm is defined in terms of an offset relative + to the end of the event. + */ + bool hasEndOffset() const; + + /** + Set the interval between snoozes for the alarm. + + @param alarmSnoozeTime the time in minutes between snoozes. + */ + void setSnoozeTime( int alarmSnoozeTime ); + + /** + Get how long the alarm snooze interval is. + + @return the number of minutes between snoozes. + */ + int snoozeTime() const; + + /** + Set how many times an alarm is to repeat itself after its initial + occurrence (w/snoozes). + */ + void setRepeatCount( int alarmRepeatCount ); + /** + Get how many times an alarm repeats, after its initial occurrence. + */ + int repeatCount() const; + /** + Get the time of the alarm's initial occurrence or its next repetition, + after a given time. + @param preTime the date and time after which to find the next repetition. + @return the date and time of the next repetition, or an invalid date/time if + the specified time is at or after the alarm's last repetition. + */ + QDateTime nextRepetition(const QDateTime& preTime) const; + /** + Get the time of the alarm's latest repetition, or its initial occurrence if + none, before a given time. + @param afterTime the date and time before which to find the latest repetition. + @return the date and time of the latest repetition, or an invalid date/time if + the specified time is at or before the alarm's initial occurrence. + */ + QDateTime previousRepetition(const QDateTime& afterTime) const; + /** + Get how long between the alarm's initial occurrence and its final repetition. + @return the number of seconds between the initial occurrence and final repetition. + */ + int duration() const; + + /** + Toggles the value of alarm to be either on or off. + Set's the alarm time to be x minutes before dtStart time. + */ + void toggleAlarm(); + + /** + Set the alarm enabled status. + */ + void setEnabled(bool enable); + /** + Get the alarm enabled status. + */ + bool enabled() const; + + /** + Set the alarm's parent incidence. + */ + void setParent( Incidence * ); + /** + Get the alarm's parent incidence. + */ + Incidence *parent() const { return mParent; } + + protected: + /** + @copydoc + CustomProperties::customPropertyUpdated() + */ + virtual void customPropertyUpdated(); + + private: + Incidence *mParent; // the incidence which this alarm belongs to + Type mType; // type of alarm + QString mDescription; // text to display/email body/procedure arguments + QString mFile; // procedure program to run/optional audio file to play + QStringList mMailAttachFiles; // filenames to attach to email + QValueList<Person> mMailAddresses; // who to mail for reminder + QString mMailSubject; // subject of email + + int mAlarmSnoozeTime; // number of minutes after alarm to + // snooze before ringing again + int mAlarmRepeatCount; // number of times for alarm to repeat + // after the initial time + + QDateTime mAlarmTime; // time at which to trigger the alarm + Duration mOffset; // time relative to incidence DTSTART to trigger the alarm + bool mEndOffset; // if true, mOffset relates to DTEND, not DTSTART + bool mHasTime; // use mAlarmTime, not mOffset + bool mAlarmEnabled; + + class Private; + Private *d; +}; + +} + +#endif |