• Skip to content
  • Skip to link menu
KDE 4.8 API Reference
  • KDE API Reference
  • KDE-PIM Libraries
  • KDE Home
  • Contact Us
 

KAlarm Library

kaevent.h
00001 /*
00002  *  kaevent.h  -  represents calendar events
00003  *  This file is part of kalarmcal library, which provides access to KAlarm
00004  *  calendar data.
00005  *  Copyright © 2001-2011 by David Jarvie <djarvie@kde.org>
00006  *
00007  *  This library is free software; you can redistribute it and/or modify
00008  *  it under the terms of the GNU Library General Public License as published
00009  *  by the Free Software Foundation; either version 2 of the License, or (at
00010  *  your option) any later version.
00011  *
00012  *  This library is distributed in the hope that it will be useful, but WITHOUT
00013  *  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00014  *  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00015  *  License for more details.
00016  *
00017  *  You should have received a copy of the GNU Library General Public License
00018  *  along with this library; see the file COPYING.LIB.  If not, write to the
00019  *  Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
00020  *  MA 02110-1301, USA.
00021  */
00022 
00023 #ifndef KAEVENT_H
00024 #define KAEVENT_H
00025 
00026 #include "kalarmcal_export.h"
00027 
00028 #include "datetime.h"
00029 #include "karecurrence.h"
00030 #include "kacalendar.h"
00031 #include "repetition.h"
00032 
00033 #ifndef USE_KRESOURCES
00034 #include <akonadi/collection.h>
00035 #include <akonadi/item.h>
00036 #include <kcalcore/person.h>
00037 #include <kcalcore/calendar.h>
00038 #else
00039 #include <kcal/person.h>
00040 #endif
00041 
00042 #include <QtCore/QBitArray>
00043 #include <QtGui/QColor>
00044 #include <QtGui/QFont>
00045 #include <QtCore/QVector>
00046 #ifdef USE_KRESOURCES
00047 #include <QtCore/QList>
00048 #endif
00049 #include <QtCore/QSharedDataPointer>
00050 #include <QtCore/QMetaType>
00051 
00052 namespace KHolidays { class HolidayRegion; }
00053 #ifdef USE_KRESOURCES
00054 namespace KCal {
00055     class CalendarLocal;
00056     class Event;
00057 }
00058 class AlarmResource;
00059 #endif
00060 class AlarmData;
00061 
00062 namespace KAlarmCal
00063 {
00064 
00078 class KALARMCAL_EXPORT KAAlarm
00079 {
00080     public:
00082         enum Action
00083         {
00084             MESSAGE,   
00085             FILE,      
00086             COMMAND,   
00087             EMAIL,     
00088             AUDIO      
00089         };
00090 
00095         enum Type
00096         {
00097             INVALID_ALARM       = 0,     
00098             MAIN_ALARM          = 1,     
00099             REMINDER_ALARM      = 0x02,  
00100             DEFERRED_ALARM      = 0x04,  
00101             DEFERRED_REMINDER_ALARM = REMINDER_ALARM | DEFERRED_ALARM,  
00102             // The following values must be greater than the preceding ones, to
00103             // ensure that in ordered processing they are processed afterwards.
00104             AT_LOGIN_ALARM      = 0x10,  
00105             DISPLAYING_ALARM    = 0x20   
00106 
00107             // IMPORTANT: if any values are added to this list, ensure that the
00108             //            KAEvent::Private::AlarmType enum is adjusted similarly.
00109         };
00110 
00112         KAAlarm();
00113 
00115         KAAlarm(const KAAlarm& other);
00116 
00118         ~KAAlarm();
00119 
00121         KAAlarm& operator=(const KAAlarm& other);
00122 
00124         Action action() const;
00125 
00127         bool isValid() const;
00128 
00130         Type type() const;
00131 
00138         DateTime dateTime(bool withRepeats = false) const;
00139 
00144         QDate date() const;
00145 
00152         QTime time() const;
00153 
00155         void setTime(const DateTime& dt);
00157         void setTime(const KDateTime& dt);
00158 
00160         bool repeatAtLogin() const;
00161 
00163         bool isReminder() const;
00164 
00166         bool deferred() const;
00167 
00172         bool timedDeferral() const;
00173 
00177         static const char* debugType(Type);
00178 
00179     private:
00180         //@cond PRIVATE
00181         class Private;
00182         Private* const d;
00183         //@endcond
00184 
00185     friend class KAEvent;
00186 };
00187 
00188 
00209 class KALARMCAL_EXPORT KAEvent
00210 {
00211     public:
00213         typedef QVector<KAEvent*> List;
00214 
00216         enum Flag
00217         {
00218             BEEP            = 0x02,    
00219             REPEAT_AT_LOGIN = 0x04,    
00220             ANY_TIME        = 0x08,    
00221             CONFIRM_ACK     = 0x10,    
00222             EMAIL_BCC       = 0x20,    
00223             DEFAULT_FONT    = 0x40,    
00224             REPEAT_SOUND    = 0x80,    
00225             DISABLED        = 0x100,   
00226             AUTO_CLOSE      = 0x200,   
00227             SCRIPT          = 0x400,   
00228             EXEC_IN_XTERM   = 0x800,   
00229             SPEAK           = 0x1000,  
00230             COPY_KORGANIZER = 0x2000,  
00231             EXCL_HOLIDAYS   = 0x4000,  
00232             WORK_TIME_ONLY  = 0x8000,  
00233             DISPLAY_COMMAND = 0x10000, 
00234             REMINDER_ONCE   = 0x20000  
00235 
00236             // IMPORTANT: if any values are added to this list, ensure that the
00237             //            additional enum values in KAEvent::Private are also adjusted.
00238         };
00239         Q_DECLARE_FLAGS(Flags, Flag)
00240 
00241         
00243         enum Actions
00244         {
00245             ACT_NONE            = 0,      
00246             ACT_DISPLAY         = 0x01,   
00247             ACT_COMMAND         = 0x02,   
00248             ACT_EMAIL           = 0x04,   
00249             ACT_AUDIO           = 0x08,   
00250             ACT_DISPLAY_COMMAND = ACT_DISPLAY | ACT_COMMAND,  
00251             ACT_ALL             = ACT_DISPLAY | ACT_COMMAND | ACT_EMAIL | ACT_AUDIO   
00252         };
00253 
00255         enum SubAction
00256         {
00257             MESSAGE = KAAlarm::MESSAGE,    
00258             FILE    = KAAlarm::FILE,       
00259             COMMAND = KAAlarm::COMMAND,    
00260             EMAIL   = KAAlarm::EMAIL,      
00261             AUDIO   = KAAlarm::AUDIO       
00262         };
00263 
00265         enum OccurType
00266         {
00267             NO_OCCURRENCE            = 0,      
00268             FIRST_OR_ONLY_OCCURRENCE = 0x01,   
00269             RECURRENCE_DATE          = 0x02,   
00270             RECURRENCE_DATE_TIME     = 0x03,   
00271             LAST_RECURRENCE          = 0x04,   
00272             OCCURRENCE_REPEAT        = 0x10,   
00273             FIRST_OR_ONLY_OCCURRENCE_REPEAT = OCCURRENCE_REPEAT | FIRST_OR_ONLY_OCCURRENCE, 
00274             RECURRENCE_DATE_REPEAT          = OCCURRENCE_REPEAT | RECURRENCE_DATE,          
00275             RECURRENCE_DATE_TIME_REPEAT     = OCCURRENCE_REPEAT | RECURRENCE_DATE_TIME,     
00276             LAST_RECURRENCE_REPEAT          = OCCURRENCE_REPEAT | LAST_RECURRENCE           
00277         };
00278 
00280         enum OccurOption
00281         {
00282             IGNORE_REPETITION,    
00283             RETURN_REPETITION,    
00284             ALLOW_FOR_REPETITION  
00285         };
00286 
00288         enum DeferLimitType
00289         {
00290             LIMIT_NONE,        
00291             LIMIT_MAIN,        
00292             LIMIT_RECURRENCE,  
00293             LIMIT_REPETITION,  
00294             LIMIT_REMINDER     
00295         };
00296 
00298         enum TriggerType
00299         {
00300             ALL_TRIGGER,       
00301             MAIN_TRIGGER,      
00302             WORK_TRIGGER,      
00303             ALL_WORK_TRIGGER,  
00304             DISPLAY_TRIGGER    
00305         };
00306 
00308         enum CmdErrType
00309         {
00310             CMD_NO_ERROR   = 0,      
00311             CMD_ERROR      = 0x01,   
00312             CMD_ERROR_PRE  = 0x02,   
00313             CMD_ERROR_POST = 0x04,   
00314             CMD_ERROR_PRE_POST = CMD_ERROR_PRE | CMD_ERROR_POST
00315         };
00316 
00318         enum UidAction
00319         {
00320             UID_IGNORE,        
00321             UID_CHECK,         
00322             UID_SET            
00323         };
00324 
00326         KAEvent();
00327 
00346         KAEvent(const KDateTime&, const QString& text, const QColor& bg, const QColor& fg,
00347                 const QFont& f, SubAction, int lateCancel, Flags flags, bool changesPending = false);
00348 #ifndef USE_KRESOURCES
00349 
00350         explicit KAEvent(const KCalCore::Event::Ptr&);
00351 
00353         void set(const KCalCore::Event::Ptr&);
00354 #else
00355 
00356         explicit KAEvent(const KCal::Event*);
00357 
00359         void set(const KCal::Event*);
00360 #endif
00361 
00362         KAEvent(const KAEvent& other);
00363         ~KAEvent();
00364 
00365         KAEvent& operator=(const KAEvent& other);
00366 
00384         void set(const KDateTime& dt, const QString& text, const QColor& bg,
00385                  const QColor& fg, const QFont& font, SubAction action, int lateCancel,
00386                  Flags flags, bool changesPending = false);
00387 
00388 #ifndef USE_KRESOURCES
00389 
00398         bool updateKCalEvent(const KCalCore::Event::Ptr& e, UidAction u, bool setCustomProperties = true) const;
00399 #else
00400 
00404         bool updateKCalEvent(KCal::Event* e, UidAction u) const;
00405 #endif
00406 
00408         bool isValid() const;
00409 
00411         void setEnabled(bool enable);
00413         bool enabled() const;
00414 
00415 #ifndef USE_KRESOURCES
00416 
00417         void setReadOnly(bool ro);
00419         bool isReadOnly() const;
00420 #endif
00421 
00425         void setArchive();
00427         bool toBeArchived() const;
00428 
00430         bool mainExpired() const;
00435         bool expired() const;
00436 
00438         Flags flags() const;
00439 
00441         void setCategory(CalEvent::Type type);
00442 
00444         CalEvent::Type category() const;
00445 
00449         void setEventId(const QString& id);
00450 
00454         QString id() const;
00455 
00457         void incrementRevision();
00459         int revision() const;
00460 
00461 #ifndef USE_KRESOURCES
00462 
00463         void setItemId(Akonadi::Item::Id id);
00465         Akonadi::Item::Id  itemId() const;
00466 
00472         bool setItemPayload(Akonadi::Item&, const QStringList& collectionMimeTypes) const;
00473 
00475         void setCompatibility(KACalendar::Compat c);
00477         KACalendar::Compat compatibility() const;
00478 
00480         QMap<QByteArray, QString> customProperties() const;
00481 #else
00482 
00486         void setResource(AlarmResource* r);
00487 
00491         AlarmResource* resource() const;
00492 #endif
00493 
00500         SubAction actionSubType() const;
00501 
00507         Actions actionTypes() const;
00508 
00514         void setLateCancel(int minutes);
00515 
00521         int lateCancel() const;
00522 
00529         void setAutoClose(bool autoclose);
00530 
00538         bool autoClose() const;
00539 
00540         void               setKMailSerialNumber(unsigned long n);
00541         unsigned long      kmailSerialNumber() const;
00542 
00547         QString cleanText() const;
00551         QString message() const;
00554         QString displayMessage() const;
00557         QString fileName() const;
00558 
00560         QColor bgColour() const;
00562         QColor fgColour() const;
00563 
00565         static void setDefaultFont(const QFont& font);
00568         bool useDefaultFont() const;
00570         QFont font() const;
00571 
00574         QString command() const;
00576         bool commandScript() const;
00578         bool commandXterm() const;
00580         bool commandDisplay() const;
00581 #ifndef USE_KRESOURCES
00582 
00583         void setCommandError(CmdErrType error) const;
00584 #else
00585 
00588         void setCommandError(CmdErrType error, bool writeConfig = true) const;
00592         void setCommandError(const QString& configString);
00594         static QString commandErrorConfigGroup();
00595 #endif
00596 
00597         CmdErrType commandError() const;
00598 
00602         void setLogFile(const QString& logfile);
00605         QString logFile() const;
00606 
00608         bool confirmAck() const;
00609 
00611         bool copyToKOrganizer() const;
00612 
00614 #ifndef USE_KRESOURCES
00615         void setEmail(uint from, const KCalCore::Person::List&, const QString& subject,
00616                       const QStringList& attachments);
00617 #else
00618         void setEmail(uint from, const QList<KCal::Person>&, const QString& subject,
00619                       const QStringList& attachments);
00620 #endif
00621 
00625         QString emailMessage() const;
00626 
00630         uint emailFromId() const;
00631 
00633 #ifndef USE_KRESOURCES
00634         KCalCore::Person::List emailAddressees() const;
00635 #else
00636         QList<KCal::Person> emailAddressees() const;
00637 #endif
00638 
00640         QStringList emailAddresses() const;
00641 
00645         QString emailAddresses(const QString& sep) const;
00646 
00650 #ifndef USE_KRESOURCES
00651         static QString joinEmailAddresses(const KCalCore::Person::List& addresses, const QString& sep);
00652 #else
00653         static QString joinEmailAddresses(const QList<KCal::Person>& addresses, const QString& sep);
00654 #endif
00655 
00657         QStringList emailPureAddresses() const;
00658 
00662         QString emailPureAddresses(const QString& sep) const;
00663 
00665         QString emailSubject() const;
00666 
00668         QStringList emailAttachments() const;
00669 
00673         QString emailAttachments(const QString& sep) const;
00674 
00676         bool emailBcc() const;
00677 
00687         void setAudioFile(const QString& filename, float volume, float fadeVolume,
00688                           int fadeSeconds, int repeatPause = -1, bool allowEmptyFile = false);
00689 
00693         QString audioFile() const;
00694 
00699         float soundVolume() const;
00700 
00705         float fadeVolume() const;
00706 
00710         int fadeSeconds() const;
00711 
00713         bool repeatSound() const;
00714 
00718         int repeatSoundPause() const;
00719 
00721         bool beep() const;
00722 
00724         bool speak() const;
00725 
00732         void setTemplate(const QString& name, int afterTime = -1);
00733 
00737         bool isTemplate() const;
00738 
00743         QString templateName() const;
00744 
00749         bool usingDefaultTime() const;
00750 
00758         int templateAfterTime() const;
00759 
00767         void setActions(const QString& pre, const QString& post, bool cancelOnError, bool dontShowError);
00768 
00770         QString preAction() const;
00771 
00775         QString postAction() const;
00776 
00780         bool cancelOnPreActionError() const;
00781 
00786         bool dontShowPreActionError() const;
00787 
00795         void setReminder(int minutes, bool onceOnly);
00796 
00802         void activateReminderAfter(const DateTime& mainAlarmTime);
00803 
00810         int reminderMinutes() const;
00815         bool reminderActive() const;
00819         bool reminderOnceOnly() const;
00821         bool reminderDeferral() const;
00822 
00832         void defer(const DateTime& dt, bool reminder, bool adjustRecurrence = false);
00833 
00837         void cancelDefer();
00843         void setDeferDefaultMinutes(int minutes, bool dateOnly = false);
00847         bool deferred() const;
00852         DateTime deferDateTime() const;
00853 
00859         DateTime deferralLimit(DeferLimitType* limitType = 0) const;
00860 
00864         int deferDefaultMinutes() const;
00866         bool deferDefaultDateOnly() const;
00867 
00872         DateTime startDateTime() const;
00877         void setTime(const KDateTime& dt);
00882         DateTime mainDateTime(bool withRepeats = false) const;
00883 
00886         QTime mainTime() const;
00892         DateTime mainEndRepeatTime() const;
00893 
00898         static void setStartOfDay(const QTime&);
00899 
00905         static void adjustStartOfDay(const KAEvent::List& events);
00906 
00911         DateTime nextTrigger(TriggerType type) const;
00912 
00916         void setCreatedDateTime(const KDateTime& dt);
00920         KDateTime createdDateTime() const;
00921 
00927         void setRepeatAtLogin(bool repeat);
00928 
00934         bool repeatAtLogin(bool includeArchived = false) const;
00935 
00942         void setExcludeHolidays(bool exclude);
00946         bool holidaysExcluded() const;
00947 
00958         static void setHolidays(const KHolidays::HolidayRegion& region);
00959 
00965         void setWorkTimeOnly(bool wto);
00969         bool workTimeOnly() const;
00970 
00973         bool isWorkingTime(const KDateTime& dt) const;
00974 
00981         static void setWorkTime(const QBitArray& days, const QTime& start, const QTime& end);
00982 
00986         void setNoRecur();
00987 
00992         void setRecurrence(const KARecurrence& r);
00993 
01002         bool setRecurMinutely(int freq, int count, const KDateTime& end);
01003 
01013         bool setRecurDaily(int freq, const QBitArray& days, int count, const QDate& end);
01014 
01024         bool setRecurWeekly(int freq, const QBitArray& days, int count, const QDate& end);
01025 
01035         bool setRecurMonthlyByDate(int freq, const QVector<int>& days, int count, const QDate& end);
01036 
01039         struct MonthPos
01040         {
01041             MonthPos() : days(7) {}    //krazy:exclude=inline (need default constructor)
01042             int        weeknum;     
01043             QBitArray  days;        
01044         };
01045 
01056         bool setRecurMonthlyByPos(int freq, const QVector<MonthPos>& pos, int count, const QDate& end);
01057 
01071         bool setRecurAnnualByDate(int freq, const QVector<int>& months, int day, KARecurrence::Feb29Type, int count, const QDate& end);
01072 
01084         bool setRecurAnnualByPos(int freq, const QVector<MonthPos>& pos, const QVector<int>& months, int count, const QDate& end);
01085 
01089         bool recurs() const;
01094         KARecurrence::Type recurType() const;
01099         KARecurrence* recurrence() const;
01100 
01105         int recurInterval() const;
01106 
01110 #ifndef USE_KRESOURCES
01111         KCalCore::Duration longestRecurrenceInterval() const;
01112 #else
01113         KCal::Duration longestRecurrenceInterval() const;
01114 #endif
01115 
01120         void setFirstRecurrence();
01121 
01123         QString recurrenceText(bool brief = false) const;
01124 
01131         bool setRepetition(const Repetition& r);
01132 
01136         Repetition repetition() const;
01137 
01142         int nextRepetition() const;
01143 
01145         QString repetitionText(bool brief = false) const;
01146 
01153         bool occursAfter(const KDateTime& preDateTime, bool includeRepetitions) const;
01154 
01163         OccurType setNextOccurrence(const KDateTime& preDateTime);
01164 
01171         OccurType nextOccurrence(const KDateTime& preDateTime, DateTime& result, OccurOption option = IGNORE_REPETITION) const;
01172 
01182         OccurType previousOccurrence(const KDateTime& afterDateTime, DateTime& result, bool includeRepetitions = false) const;
01183 
01192 #ifndef USE_KRESOURCES
01193         bool setDisplaying(const KAEvent& e, KAAlarm::Type t, Akonadi::Collection::Id colId, const KDateTime& dt, bool showEdit, bool showDefer);
01194 #else
01195         bool setDisplaying(const KAEvent& e, KAAlarm::Type t, const QString& resourceID, const KDateTime& dt, bool showEdit, bool showDefer);
01196 #endif
01197 
01198 #ifndef USE_KRESOURCES
01199 
01204         void reinstateFromDisplaying(const KCalCore::Event::Ptr& event, Akonadi::Collection::Id& colId, bool& showEdit, bool& showDefer);
01205 #else
01206         void reinstateFromDisplaying(const KCal::Event* event, QString& resourceID, bool& showEdit, bool& showDefer);
01207 #endif
01208 
01215         KAAlarm convertDisplayingAlarm() const;
01216 
01218         bool displaying() const;
01219 
01224         KAAlarm alarm(KAAlarm::Type type) const;
01225 
01233         KAAlarm firstAlarm() const;
01234 
01238         KAAlarm nextAlarm(const KAAlarm& previousAlarm) const;
01242         KAAlarm nextAlarm(KAAlarm::Type previousType) const;
01243 
01251         int alarmCount() const;
01252 
01257         void removeExpiredAlarm(KAAlarm::Type type);
01258 
01265         void startChanges();
01269         void endChanges();
01270 
01275         static int currentCalendarVersion();
01276 
01281         static QByteArray currentCalendarVersionString();
01282 
01295 #ifndef USE_KRESOURCES
01296         static bool convertKCalEvents(const KCalCore::Calendar::Ptr&, int calendarVersion);
01297 #else
01298         static bool convertKCalEvents(KCal::CalendarLocal&, int calendarVersion);
01299 #endif
01300 
01301 #ifndef USE_KRESOURCES
01302 
01303         static List ptrList(QVector<KAEvent>& events);
01304 #endif
01305 
01307         void dumpDebug() const;
01308 
01309     private:
01310         class Private;
01311         QSharedDataPointer<Private> d;
01312 };
01313 
01314 } // namespace KAlarmCal
01315 
01316 Q_DECLARE_OPERATORS_FOR_FLAGS(KAlarmCal::KAEvent::Flags)
01317 Q_DECLARE_METATYPE(KAlarmCal::KAEvent)
01318 
01319 #endif // KAEVENT_H
01320 
01321 // vim: et sw=4:

KAlarm Library

Skip menu "KAlarm Library"
  • Main Page
  • Namespace List
  • Namespace Members
  • Alphabetical List
  • Class List
  • Class Hierarchy
  • Class Members
  • File List
  • Related Pages

KDE-PIM Libraries

Skip menu "KDE-PIM Libraries"
  • akonadi
  •   contact
  •   kmime
  • kabc
  • kalarmcal
  • kblog
  • kcal
  • kcalcore
  • kcalutils
  • kholidays
  • kimap
  • kioslave
  •   imap4
  •   mbox
  •   nntp
  • kldap
  • kmbox
  • kmime
  • kontactinterface
  • kpimidentities
  • kpimtextedit
  •   richtextbuilders
  • kpimutils
  • kresources
  • ktnef
  • kxmlrpcclient
  • mailtransport
  • microblog
  • qgpgme
  • syndication
  •   atom
  •   rdf
  •   rss2
Generated for KDE-PIM Libraries by doxygen 1.7.6.1
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal