• Skip to content
  • Skip to link menu
  • KDE API Reference
  • kdepimlibs-4.8.3 API Reference
  • 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-2012 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 KALARMCAL_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 KALARMCAL_USE_KRESOURCES
00047 #include <QtCore/QList>
00048 #endif
00049 #include <QtCore/QSharedDataPointer>
00050 #include <QtCore/QMetaType>
00051 
00052 namespace KHolidays { class HolidayRegion; }
00053 #ifdef KALARMCAL_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 KALARMCAL_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 KALARMCAL_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 KALARMCAL_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 KALARMCAL_USE_KRESOURCES
00462 
00463         void setCollectionId(Akonadi::Collection::Id id);
00471         void setCollectionId_const(Akonadi::Collection::Id id) const;
00473         Akonadi::Collection::Id  collectionId() const;
00474 
00476         void setItemId(Akonadi::Item::Id id);
00478         Akonadi::Item::Id  itemId() const;
00479 
00485         bool setItemPayload(Akonadi::Item&, const QStringList& collectionMimeTypes) const;
00486 
00488         void setCompatibility(KACalendar::Compat c);
00490         KACalendar::Compat compatibility() const;
00491 
00493         QMap<QByteArray, QString> customProperties() const;
00494 #else
00495 
00499         void setResource(AlarmResource* r);
00500 
00504         AlarmResource* resource() const;
00505 #endif
00506 
00513         SubAction actionSubType() const;
00514 
00520         Actions actionTypes() const;
00521 
00527         void setLateCancel(int minutes);
00528 
00534         int lateCancel() const;
00535 
00542         void setAutoClose(bool autoclose);
00543 
00551         bool autoClose() const;
00552 
00553         void               setKMailSerialNumber(unsigned long n);
00554         unsigned long      kmailSerialNumber() const;
00555 
00560         QString cleanText() const;
00564         QString message() const;
00567         QString displayMessage() const;
00570         QString fileName() const;
00571 
00573         QColor bgColour() const;
00575         QColor fgColour() const;
00576 
00578         static void setDefaultFont(const QFont& font);
00581         bool useDefaultFont() const;
00583         QFont font() const;
00584 
00587         QString command() const;
00589         bool commandScript() const;
00591         bool commandXterm() const;
00593         bool commandDisplay() const;
00594 #ifndef KALARMCAL_USE_KRESOURCES
00595 
00596         void setCommandError(CmdErrType error) const;
00597 #else
00598 
00601         void setCommandError(CmdErrType error, bool writeConfig = true) const;
00605         void setCommandError(const QString& configString);
00607         static QString commandErrorConfigGroup();
00608 #endif
00609 
00610         CmdErrType commandError() const;
00611 
00615         void setLogFile(const QString& logfile);
00618         QString logFile() const;
00619 
00621         bool confirmAck() const;
00622 
00624         bool copyToKOrganizer() const;
00625 
00627 #ifndef KALARMCAL_USE_KRESOURCES
00628         void setEmail(uint from, const KCalCore::Person::List&, const QString& subject,
00629                       const QStringList& attachments);
00630 #else
00631         void setEmail(uint from, const QList<KCal::Person>&, const QString& subject,
00632                       const QStringList& attachments);
00633 #endif
00634 
00638         QString emailMessage() const;
00639 
00643         uint emailFromId() const;
00644 
00646 #ifndef KALARMCAL_USE_KRESOURCES
00647         KCalCore::Person::List emailAddressees() const;
00648 #else
00649         QList<KCal::Person> emailAddressees() const;
00650 #endif
00651 
00653         QStringList emailAddresses() const;
00654 
00658         QString emailAddresses(const QString& sep) const;
00659 
00663 #ifndef KALARMCAL_USE_KRESOURCES
00664         static QString joinEmailAddresses(const KCalCore::Person::List& addresses, const QString& sep);
00665 #else
00666         static QString joinEmailAddresses(const QList<KCal::Person>& addresses, const QString& sep);
00667 #endif
00668 
00670         QStringList emailPureAddresses() const;
00671 
00675         QString emailPureAddresses(const QString& sep) const;
00676 
00678         QString emailSubject() const;
00679 
00681         QStringList emailAttachments() const;
00682 
00686         QString emailAttachments(const QString& sep) const;
00687 
00689         bool emailBcc() const;
00690 
00700         void setAudioFile(const QString& filename, float volume, float fadeVolume,
00701                           int fadeSeconds, int repeatPause = -1, bool allowEmptyFile = false);
00702 
00706         QString audioFile() const;
00707 
00712         float soundVolume() const;
00713 
00718         float fadeVolume() const;
00719 
00723         int fadeSeconds() const;
00724 
00726         bool repeatSound() const;
00727 
00731         int repeatSoundPause() const;
00732 
00734         bool beep() const;
00735 
00737         bool speak() const;
00738 
00745         void setTemplate(const QString& name, int afterTime = -1);
00746 
00750         bool isTemplate() const;
00751 
00756         QString templateName() const;
00757 
00762         bool usingDefaultTime() const;
00763 
00771         int templateAfterTime() const;
00772 
00780         void setActions(const QString& pre, const QString& post, bool cancelOnError, bool dontShowError);
00781 
00783         QString preAction() const;
00784 
00788         QString postAction() const;
00789 
00793         bool cancelOnPreActionError() const;
00794 
00799         bool dontShowPreActionError() const;
00800 
00808         void setReminder(int minutes, bool onceOnly);
00809 
00815         void activateReminderAfter(const DateTime& mainAlarmTime);
00816 
00823         int reminderMinutes() const;
00828         bool reminderActive() const;
00832         bool reminderOnceOnly() const;
00834         bool reminderDeferral() const;
00835 
00845         void defer(const DateTime& dt, bool reminder, bool adjustRecurrence = false);
00846 
00850         void cancelDefer();
00856         void setDeferDefaultMinutes(int minutes, bool dateOnly = false);
00860         bool deferred() const;
00865         DateTime deferDateTime() const;
00866 
00872         DateTime deferralLimit(DeferLimitType* limitType = 0) const;
00873 
00877         int deferDefaultMinutes() const;
00879         bool deferDefaultDateOnly() const;
00880 
00885         DateTime startDateTime() const;
00890         void setTime(const KDateTime& dt);
00895         DateTime mainDateTime(bool withRepeats = false) const;
00896 
00899         QTime mainTime() const;
00905         DateTime mainEndRepeatTime() const;
00906 
00911         static void setStartOfDay(const QTime&);
00912 
00918         static void adjustStartOfDay(const KAEvent::List& events);
00919 
00924         DateTime nextTrigger(TriggerType type) const;
00925 
00929         void setCreatedDateTime(const KDateTime& dt);
00933         KDateTime createdDateTime() const;
00934 
00940         void setRepeatAtLogin(bool repeat);
00941 
00947         bool repeatAtLogin(bool includeArchived = false) const;
00948 
00955         void setExcludeHolidays(bool exclude);
00959         bool holidaysExcluded() const;
00960 
00971         static void setHolidays(const KHolidays::HolidayRegion& region);
00972 
00978         void setWorkTimeOnly(bool wto);
00982         bool workTimeOnly() const;
00983 
00986         bool isWorkingTime(const KDateTime& dt) const;
00987 
00994         static void setWorkTime(const QBitArray& days, const QTime& start, const QTime& end);
00995 
00999         void setNoRecur();
01000 
01005         void setRecurrence(const KARecurrence& r);
01006 
01015         bool setRecurMinutely(int freq, int count, const KDateTime& end);
01016 
01026         bool setRecurDaily(int freq, const QBitArray& days, int count, const QDate& end);
01027 
01037         bool setRecurWeekly(int freq, const QBitArray& days, int count, const QDate& end);
01038 
01048         bool setRecurMonthlyByDate(int freq, const QVector<int>& days, int count, const QDate& end);
01049 
01052         struct MonthPos
01053         {
01054             MonthPos() : days(7) {}    //krazy:exclude=inline (need default constructor)
01055             int        weeknum;     
01056             QBitArray  days;        
01057         };
01058 
01069         bool setRecurMonthlyByPos(int freq, const QVector<MonthPos>& pos, int count, const QDate& end);
01070 
01084         bool setRecurAnnualByDate(int freq, const QVector<int>& months, int day, KARecurrence::Feb29Type, int count, const QDate& end);
01085 
01097         bool setRecurAnnualByPos(int freq, const QVector<MonthPos>& pos, const QVector<int>& months, int count, const QDate& end);
01098 
01102         bool recurs() const;
01107         KARecurrence::Type recurType() const;
01112         KARecurrence* recurrence() const;
01113 
01118         int recurInterval() const;
01119 
01123 #ifndef KALARMCAL_USE_KRESOURCES
01124         KCalCore::Duration longestRecurrenceInterval() const;
01125 #else
01126         KCal::Duration longestRecurrenceInterval() const;
01127 #endif
01128 
01133         void setFirstRecurrence();
01134 
01136         QString recurrenceText(bool brief = false) const;
01137 
01144         bool setRepetition(const Repetition& r);
01145 
01149         Repetition repetition() const;
01150 
01155         int nextRepetition() const;
01156 
01158         QString repetitionText(bool brief = false) const;
01159 
01166         bool occursAfter(const KDateTime& preDateTime, bool includeRepetitions) const;
01167 
01176         OccurType setNextOccurrence(const KDateTime& preDateTime);
01177 
01184         OccurType nextOccurrence(const KDateTime& preDateTime, DateTime& result, OccurOption option = IGNORE_REPETITION) const;
01185 
01195         OccurType previousOccurrence(const KDateTime& afterDateTime, DateTime& result, bool includeRepetitions = false) const;
01196 
01211 #ifndef KALARMCAL_USE_KRESOURCES
01212         bool setDisplaying(const KAEvent& event, KAAlarm::Type type, Akonadi::Collection::Id colId, const KDateTime& repeatAtLoginTime, bool showEdit, bool showDefer);
01213 #else
01214         bool setDisplaying(const KAEvent& event, KAAlarm::Type type, const QString& resourceID, const KDateTime& repeatAtLoginTime, bool showEdit, bool showDefer);
01215 #endif
01216 
01217 #ifndef KALARMCAL_USE_KRESOURCES
01218 
01227         void reinstateFromDisplaying(const KCalCore::Event::Ptr& event, Akonadi::Collection::Id& colId, bool& showEdit, bool& showDefer);
01228 #else
01229         void reinstateFromDisplaying(const KCal::Event* event, QString& resourceID, bool& showEdit, bool& showDefer);
01230 #endif
01231 
01238         KAAlarm convertDisplayingAlarm() const;
01239 
01241         bool displaying() const;
01242 
01247         KAAlarm alarm(KAAlarm::Type type) const;
01248 
01256         KAAlarm firstAlarm() const;
01257 
01261         KAAlarm nextAlarm(const KAAlarm& previousAlarm) const;
01265         KAAlarm nextAlarm(KAAlarm::Type previousType) const;
01266 
01274         int alarmCount() const;
01275 
01280         void removeExpiredAlarm(KAAlarm::Type type);
01281 
01288         void startChanges();
01292         void endChanges();
01293 
01298         static int currentCalendarVersion();
01299 
01304         static QByteArray currentCalendarVersionString();
01305 
01318 #ifndef KALARMCAL_USE_KRESOURCES
01319         static bool convertKCalEvents(const KCalCore::Calendar::Ptr&, int calendarVersion);
01320 #else
01321         static bool convertKCalEvents(KCal::CalendarLocal&, int calendarVersion);
01322 #endif
01323 
01324 #ifndef KALARMCAL_USE_KRESOURCES
01325 
01326         static List ptrList(QVector<KAEvent>& events);
01327 #endif
01328 
01330         void dumpDebug() const;
01331 
01332     private:
01333         class Private;
01334         QSharedDataPointer<Private> d;
01335 };
01336 
01337 } // namespace KAlarmCal
01338 
01339 Q_DECLARE_OPERATORS_FOR_FLAGS(KAlarmCal::KAEvent::Flags)
01340 Q_DECLARE_METATYPE(KAlarmCal::KAEvent)
01341 
01342 #endif // KAEVENT_H
01343 
01344 // vim: et sw=4:
This file is part of the KDE documentation.
Documentation copyright © 1996-2012 The KDE developers.
Generated on Tue May 8 2012 00:11:42 by doxygen 1.8.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.

KAlarm Library

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

kdepimlibs-4.8.3 API Reference

Skip menu "kdepimlibs-4.8.3 API Reference"
  • 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
Report problems with this website to our bug tracking system.
Contact the specific authors with questions and comments about the page contents.

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal