kalarm Library API Documentation

msgevent.h

00001 /*
00002  *  msgevent.h  -  the event object for messages
00003  *  Program:  kalarm
00004  *  (C) 2001, 2002 by David Jarvie  software@astrojar.org.uk
00005  *
00006  *  This program is free software; you can redistribute it and/or modify
00007  *  it under the terms of the GNU General Public License as published by
00008  *  the Free Software Foundation; either version 2 of the License, or
00009  *  (at your option) any later version.
00010  *
00011  *  This program is distributed in the hope that it will be useful,
00012  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00013  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
00014  *  GNU General Public License for more details.
00015  *
00016  *  You should have received a copy of the GNU General Public License
00017  *  along with this program; if not, write to the Free Software
00018  *  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00019  */
00020 
00021 #ifndef KALARMEVENT_H
00022 #define KALARMEVENT_H
00023 
00024 #include <libkcal/event.h>
00025 #include <libkcal/recurrence.h>
00026 
00027 struct AlarmData;
00028 
00029 /*
00030  * KAlarm events are stored as alarms in the calendar file, as follows:
00031  * In the alarm object:
00032  *   next time/date - stored as the alarm time (alarm TRIGGER field)
00033  *   message text - stored as the alarm description, with prefix TEXT: (alarm DESCRIPTION field)
00034  *   file name to display text from - stored as the alarm description, with prefix FILE: (alarm DESCRIPTION field)
00035  *   command to execute - stored as the alarm description, with prefix CMD: (alarm DESCRIPTION field)
00036  *   late cancel, repeat at login, deferral - stored in prefix to the alarm description (alarm DESCRIPTION field)
00037  * In the event object:
00038  *   colour - stored as a hex string prefixed by #, as the first category (event CATEGORIES field)
00039  *   elapsed repeat count - stored as the revision number (event SEQUENCE field)
00040  *   beep - stored as a "BEEP" category (event CATEGORIES field)
00041  *   confirmAck - stored as a "ACKCONF" category (event CATEGORIES field)
00042  */
00043 
00044 // KAlarmAlarm corresponds to a single KCal::Alarm instance
00045 class KAlarmAlarm
00046 {
00047         public:
00048                 enum Type  { MESSAGE, FILE, COMMAND, AUDIO };
00049 
00050                 KAlarmAlarm()    : mAlarmSeq(-1), mBeep(false), mRepeatAtLogin(false), mDeferral(false), mLateCancel(false), mConfirmAck(false) { }
00051                 ~KAlarmAlarm()  { }
00052                 void             set(int flags);
00053                 bool             valid() const              { return mAlarmSeq > 0; }
00054                 Type             type() const               { return mType; }
00055                 int              id() const                 { return mAlarmSeq; }
00056                 int              sequence() const           { return mAlarmSeq; }
00057                 const QString&   eventID() const            { return mEventID; }
00058                 const QDateTime& dateTime() const           { return mDateTime; }
00059                 QDate            date() const               { return mDateTime.date(); }
00060                 QTime            time() const               { return mDateTime.time(); }
00061                 const QString&   cleanText() const          { return mCleanText; }
00062                 QString          message() const            { return (mType == MESSAGE) ? mCleanText : QString::null; }
00063                 QString          fileName() const           { return (mType == FILE) ? mCleanText : QString::null; }
00064                 QString          command() const            { return (mType == COMMAND) ? mCleanText : QString::null; }
00065                 QString          audioFile() const          { return (mType == AUDIO) ? mCleanText : QString::null; }
00066                 void             commandArgs(QStringList&) const;
00067                 const QColor&    colour() const             { return mColour; }
00068                 bool             confirmAck() const         { return mConfirmAck; }
00069                 bool             lateCancel() const         { return mLateCancel; }
00070                 bool             repeatAtLogin() const      { return mRepeatAtLogin; }
00071                 bool             deferred() const           { return mDeferral; }
00072                 bool             beep() const               { return mBeep; }
00073                 int              flags() const;
00074 #ifdef NDEBUG
00075                 void             dumpDebug() const  { }
00076 #else
00077                 void             dumpDebug() const;
00078 #endif
00079                 static QString   commandFromArgs(const QStringList&);
00080 
00081                 QString          mEventID;          // KCal::Event unique ID
00082                 QString          mCleanText;        // message text, file URL, command or audio file
00083                 QDateTime        mDateTime;         // next time to display the alarm
00084                 QColor           mColour;           // background colour of alarm message
00085                 Type             mType;             // message/file/command
00086                 int              mAlarmSeq;         // sequence number of this alarm
00087                 bool             mRecurs;           // there is a recurrence rule for the alarm
00088                 bool             mBeep;             // whether to beep when the alarm is displayed
00089                 bool             mRepeatAtLogin;    // whether to repeat the alarm at every login
00090                 bool             mDeferral;         // whether the alarm is an extra deferred alarm
00091                 bool             mLateCancel;       // whether to cancel the alarm if it can't be displayed on time
00092                 bool             mConfirmAck;       // alarm acknowledgement requires confirmation by user
00093 };
00094 
00095 
00096 // KAlarmEvent corresponds to a KCal::Event instance
00097 class KAlarmEvent
00098 {
00099         public:
00100                 enum            // flags for use in DCOP calls, etc.
00101                 {
00102                         // *** DON'T CHANGE THESE VALUES ***
00103                         // because they are part of KAlarm's external DCOP interface.
00104                         // (But it's alright to add new values.)
00105                         LATE_CANCEL     = 0x01,
00106                         BEEP            = 0x02,
00107                         REPEAT_AT_LOGIN = 0x04,
00108                         ANY_TIME        = 0x08,    // only a date is specified, not a time
00109                         CONFIRM_ACK     = 0x10,
00110                         // The following values are read-only
00111                         DEFERRAL        = 0x80
00112                 };
00113                 enum RecurType
00114                 {
00115                         // *** DON'T CHANGE THESE VALUES ***
00116                         // because they are part of KAlarm's external DCOP interface.
00117                         // (But it's alright to add new values.)
00118                         NO_RECUR    = KCal::Recurrence::rNone,
00119                         MINUTELY    = KCal::Recurrence::rMinutely,
00120                         DAILY       = KCal::Recurrence::rDaily,
00121                         WEEKLY      = KCal::Recurrence::rWeekly,
00122                         MONTHLY_DAY = KCal::Recurrence::rMonthlyDay,
00123                         MONTHLY_POS = KCal::Recurrence::rMonthlyPos,
00124                         ANNUAL_DATE = KCal::Recurrence::rYearlyMonth,
00125                         ANNUAL_POS  = KCal::Recurrence::rYearlyPos,
00126                         // The following values are not implemented in KAlarm
00127                         ANNUAL_DAY  = KCal::Recurrence::rYearlyDay
00128                 };
00129                 enum OccurType
00130                 {
00131                         NO_OCCURRENCE,        // no occurrence is due
00132                         FIRST_OCCURRENCE,     // the first occurrence is due (takes precedence over LAST_OCCURRENCE)
00133                         RECURRENCE_DATE,      // a recurrence is due with only a date, not a time
00134                         RECURRENCE_DATE_TIME, // a recurrence is due with a date and time
00135                         LAST_OCCURRENCE       // the last occurrence is due
00136                 };
00137 
00138                 KAlarmEvent()    : mRevision(0), mRecurrence(0L), mMainAlarmID(1) { }
00139                 KAlarmEvent(const QDateTime& dt, const QString& message, const QColor& c, KAlarmAlarm::Type type, int flags)
00140                                                             : mRecurrence(0L) { set(dt, message, c, type, flags); }
00141                 explicit KAlarmEvent(const KCal::Event& e)  : mRecurrence(0L) { set(e); }
00142                 KAlarmEvent(const KAlarmEvent& e)           : mRecurrence(0L) { copy(e); }
00143                 ~KAlarmEvent()    { delete mRecurrence; }
00144                 KAlarmEvent&      operator=(const KAlarmEvent& e)   { if (&e != this) copy(e);  return *this; }
00145                 void              set(const KCal::Event&);
00146                 void              set(const QDate& d, const QString& message, const QColor& c, KAlarmAlarm::Type type, int flags)
00147                                            { set(d, message, c, type, flags | ANY_TIME); }
00148                 void              set(const QDateTime&, const QString& message, const QColor&, KAlarmAlarm::Type, int flags);
00149                 void              setMessage(const QDate& d, const QString& message, const QColor& c, int flags)
00150                                            { set(d, message, c, KAlarmAlarm::MESSAGE, flags | ANY_TIME); }
00151                 void              setMessage(const QDateTime& dt, const QString& message, const QColor& c, int flags)
00152                                            { set(dt, message, c, KAlarmAlarm::MESSAGE, flags); }
00153                 void              setFileName(const QDate& d, const QString& filename, const QColor& c, int flags)
00154                                            { set(d, filename, c, KAlarmAlarm::FILE, flags | ANY_TIME); }
00155                 void              setFileName(const QDateTime& dt, const QString& filename, const QColor& c, int flags)
00156                                            { set(dt, filename, c, KAlarmAlarm::FILE, flags); }
00157                 void              setCommand(const QDate& d, const QString& command, int flags)
00158                                            { set(d, command, QColor(), KAlarmAlarm::COMMAND, flags | ANY_TIME); }
00159                 void              setCommand(const QDateTime& dt, const QString& command, int flags = 0)
00160                                            { set(dt, command, QColor(), KAlarmAlarm::COMMAND, flags); }
00161                 void              setAudioFile(const QString& filename)             { mAudioFile = filename; }
00162                 OccurType         setNextOccurrence(const QDateTime& preDateTime);
00163                 void              setFirstRecurrence();
00164                 void              setEventID(const QString& id)                     { mEventID = id; }
00165                 void              setDate(const QDate& d)                           { mDateTime = d; mAnyTime = true; }
00166                 void              setTime(const QDateTime& dt)                      { mDateTime = dt; mAnyTime = false; }
00167                 void              setLateCancel(bool lc)                            { mLateCancel = lc; }
00168                 void              set(int flags);
00169                 void              defer(const QDateTime&);
00170                 void              cancelDefer();
00171                 KCal::Event*      event() const;    // convert to new Event
00172                 KAlarmAlarm       alarm(int alarmID) const;
00173                 KAlarmAlarm       firstAlarm() const;
00174                 KAlarmAlarm       nextAlarm(const KAlarmAlarm&) const;
00175                 bool              updateEvent(KCal::Event&) const;
00176                 void              removeAlarm(int alarmID);
00177                 void              incrementRevision()          { ++mRevision; }
00178                 void              setUpdated()                 { mUpdated = true; }
00179                 bool              updated() const              { return mUpdated; }
00180 
00181                 bool              operator==(const KAlarmEvent&);
00182                 bool              operator!=(const KAlarmEvent& e)  { return !operator==(e); }
00183                 KAlarmAlarm::Type type() const                 { return mType; }
00184                 const QString&    id() const                   { return mEventID; }
00185                 int               alarmCount() const           { return mAlarmCount; }
00186                 const QDateTime&  mainDateTime() const         { return mDateTime; }
00187                 QDate             mainDate() const             { return mDateTime.date(); }
00188                 QTime             mainTime() const             { return mDateTime.time(); }
00189                 bool              anyTime() const              { return mAnyTime; }
00190                 const QDateTime&  deferDateTime() const        { return mDeferralTime; }
00191                 QDateTime         dateTime() const             { return mDeferral ? QMIN(mDeferralTime, mDateTime) : mDateTime; }
00192                 const QString&    cleanText() const            { return mCleanText; }
00193                 QString           message() const              { return (mType == KAlarmAlarm::MESSAGE) ? mCleanText : QString::null; }
00194                 QString           fileName() const             { return (mType == KAlarmAlarm::FILE) ? mCleanText : QString::null; }
00195                 QString           command() const              { return (mType == KAlarmAlarm::COMMAND) ? mCleanText : QString::null; }
00196                 QString           messageFileOrCommand() const { return mCleanText; }
00197                 QString           audioFile() const            { return mAudioFile; }
00198                 const QColor&     colour() const               { return mColour; }
00199                 bool              confirmAck() const           { return mConfirmAck; }
00200                 RecurType         recurs() const;
00201                 KCal::Recurrence* recurrence() const           { return mRecurrence; }
00202                 bool              recursFeb29() const          { return mRecursFeb29; }
00203                 int               recurInterval() const;    // recurrence period in units of the recurrence period type (minutes, days, etc)
00204                 int               repeatCount() const          { return mRepeatDuration; }
00205                 OccurType         nextOccurrence(const QDateTime& preDateTime, QDateTime& result) const;
00206                 OccurType         previousOccurrence(const QDateTime& afterDateTime, QDateTime& result) const;
00207                 bool              lateCancel() const           { return mLateCancel; }
00208                 bool              repeatAtLogin() const        { return mRepeatAtLogin; }
00209                 bool              deferred() const             { return mDeferral; }
00210                 bool              beep() const                 { return mBeep; }
00211                 int               flags() const;
00212 
00213                 struct MonthPos
00214                 {
00215                         MonthPos() : days(7) { }
00216                         int        weeknum;     // week in month, or < 0 to count from end of month
00217                         QBitArray  days;        // days in week
00218                 };
00219                 void              setRecurMinutely(int freq, int count)                                            { setRecurMinutely(freq, count, QDateTime()); }
00220                 void              setRecurMinutely(int freq, const QDateTime& end)                                 { setRecurMinutely(freq, 0, end); }
00221                 void              setRecurDaily(int freq, int count)                                               { setRecurDaily(freq, count, QDate()); }
00222                 void              setRecurDaily(int freq, const QDate& end)                                        { setRecurDaily(freq, 0, end); }
00223                 void              setRecurWeekly(int freq, const QBitArray& days, int count)                       { setRecurWeekly(freq, days, count, QDate()); }
00224                 void              setRecurWeekly(int freq, const QBitArray& days, const QDate& end)                { setRecurWeekly(freq, days, 0, end); }
00225                 void              setRecurMonthlyByDate(int freq, const QValueList<int>& days, int count)          { setRecurMonthlyByDate(freq, days, count, QDate()); }
00226                 void              setRecurMonthlyByDate(int freq, const QValueList<int>& days, const QDate& end)   { setRecurMonthlyByDate(freq, days, 0, end); }
00227                 void              setRecurMonthlyByPos(int freq, const QValueList<MonthPos>& mp, int count)        { setRecurMonthlyByPos(freq, mp, count, QDate()); }
00228                 void              setRecurMonthlyByPos(int freq, const QValueList<MonthPos>& mp, const QDate& end) { setRecurMonthlyByPos(freq, mp, 0, end); }
00229                 void              setRecurMonthlyByPos(int freq, const QPtrList<KCal::Recurrence::rMonthPos>& mp, int count)   { setRecurMonthlyByPos(freq, mp, count, QDate()); }
00230                 void              setRecurMonthlyByPos(int freq, const QPtrList<KCal::Recurrence::rMonthPos>& mp, const QDate& end) { setRecurMonthlyByPos(freq, mp, 0, end); }
00231                 void              setRecurAnnualByDate(int freq, const QValueList<int>& months, int count)         { setRecurAnnualByDate(freq, months, -1, count, QDate()); }
00232                 void              setRecurAnnualByDate(int freq, const QValueList<int>& months, const QDate& end)  { setRecurAnnualByDate(freq, months, -1, 0, end); }
00233                 void              setRecurAnnualByDate(int freq, const QValueList<int>& months, bool feb29, int count)         { setRecurAnnualByDate(freq, months, feb29, count, QDate()); }
00234                 void              setRecurAnnualByDate(int freq, const QValueList<int>& months, bool feb29, const QDate& end)  { setRecurAnnualByDate(freq, months, feb29, 0, end); }
00235                 void              setRecurAnnualByPos(int freq, const QValueList<MonthPos>& mp, const QValueList<int>& months, int count)     { setRecurAnnualByPos(freq, mp, months, count, QDate()); }
00236                 void              setRecurAnnualByPos(int freq, const QValueList<MonthPos>& mp, const QValueList<int>& months, const QDate& end)  { setRecurAnnualByPos(freq, mp, months, 0, end); }
00237                 void              setRecurAnnualByDay(int freq, const QValueList<int>& days, int count)            { setRecurAnnualByDay(freq, days, count, QDate()); }
00238                 void              setRecurAnnualByDay(int freq, const QValueList<int>& days, const QDate& end)     { setRecurAnnualByDay(freq, days, 0, end); }
00239 
00240                 void              setRecurMinutely(int freq, int count, const QDateTime& end);
00241                 void              setRecurDaily(int freq, int count, const QDate& end);
00242                 void              setRecurWeekly(int freq, const QBitArray& days, int count, const QDate& end);
00243                 void              setRecurMonthlyByDate(int freq, const QValueList<int>& days, int count, const QDate& end);
00244                 void              setRecurMonthlyByDate(int freq, const QPtrList<int>& days, int count, const QDate& end);
00245                 void              setRecurMonthlyByPos(int freq, const QValueList<MonthPos>&, int count, const QDate& end);
00246                 void              setRecurMonthlyByPos(int freq, const QPtrList<KCal::Recurrence::rMonthPos>&, int count, const QDate& end);
00247                 void              setRecurAnnualByDate(int freq, const QValueList<int>& months, bool feb29, int count, const QDate& end);
00248                 void              setRecurAnnualByDate(int freq, const QPtrList<int>& months, bool feb29, int count, const QDate& end);
00249                 void              setRecurAnnualByPos(int freq, const QValueList<MonthPos>&, const QValueList<int>& months, int count, const QDate& end);
00250                 void              setRecurAnnualByPos(int freq, const QPtrList<KCal::Recurrence::rMonthPos>&, const QPtrList<int>& months, int count, const QDate& end);
00251                 void              setRecurAnnualByDay(int freq, const QValueList<int>& days, int count, const QDate& end);
00252                 void              setRecurAnnualByDay(int freq, const QPtrList<int>& days, int count, const QDate& end);
00253 #ifdef NDEBUG
00254                 void              dumpDebug() const  { }
00255 #else
00256                 void              dumpDebug() const;
00257 #endif
00258                 static bool       adjustStartOfDay(const QPtrList<KCal::Event>&);
00259                 static void       convertKCalEvents();
00260 
00261                 static const int  MAIN_ALARM_ID;            // alarm ID for main alarm
00262                 static const int  AUDIO_ALARM_ID;           // alarm ID for audio alarm
00263                 static const int  REPEAT_AT_LOGIN_OFFSET;   // alarm ID offset for repeat-at-login alarm
00264                 static const int  DEFERRAL_OFFSET;          // alarm ID offset for deferral alarm
00265         private:
00266                 void              copy(const KAlarmEvent&);
00267                 bool              initRecur(bool endDate, int count = 0, bool feb29 = false);
00268                 RecurType         checkRecur() const;
00269                 OccurType         nextRecurrence(const QDateTime& preDateTime, QDateTime& result, int& remainingCount) const;
00270                 OccurType         previousRecurrence(const QDateTime& afterDateTime, QDateTime& result) const;
00271                 static int        readAlarm(const KCal::Alarm&, AlarmData&);
00272 
00273                 QString           mEventID;          // KCal::Event unique ID
00274                 QString           mCleanText;        // message text, file URL or command
00275                 QString           mAudioFile;        // audio file to play
00276                 QDateTime         mDateTime;         // next time to display the alarm (except deferrals)
00277                 QDateTime         mRepeatAtLoginDateTime;  // repeat at login time
00278                 QDateTime         mDeferralTime;     // extra time to trigger alarm (if alarm deferred)
00279                 QColor            mColour;           // background colour of alarm message
00280                 KAlarmAlarm::Type mType;             // message/file/command (not audio)
00281                 int               mRevision;         // revision number of the original alarm, or 0
00282                 KCal::Recurrence* mRecurrence;       // recurrence specification, or 0 if none
00283                 int               mRepeatDuration;   // remaining number of alarm repetitions including initial time, -1 to repeat indefinitely
00284                 int               mAlarmCount;       // number of alarms
00285                 int               mMainAlarmID;      // sequence number of main alarm
00286                 int               mRepeatAtLoginAlarmID; // sequence number of repeat-at-login alarm (only if read from calendar file)
00287                 int               mDeferralAlarmID;  // sequence number of deferral alarm (only if read from calendar file)
00288                 bool              mRecursFeb29;      // the recurrence is yearly on February 29th
00289                 bool              mAnyTime;          // event has only a date, not a time
00290                 bool              mBeep;             // whether to beep when the alarm is displayed
00291                 bool              mRepeatAtLogin;    // whether to repeat the alarm at every login
00292                 bool              mDeferral;         // whether the alarm has an extra deferred time
00293                 bool              mLateCancel;       // whether to cancel the alarm if it can't be displayed on time
00294                 bool              mConfirmAck;       // alarm acknowledgement requires confirmation by user
00295                 bool              mUpdated;          // event has been updated but not written to calendar file
00296 };
00297 
00298 #endif // KALARMEVENT_H
KDE Logo
This file is part of the documentation for kdelibs Version 3.1.4.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Sat Oct 18 02:47:26 2003 by doxygen 1.3.4 written by Dimitri van Heesch, © 1997-2001