kaevent.h

/*
 *  kaevent.h  -  represents calendar events
 *  This file is part of kalarmcal library, which provides access to KAlarm
 *  calendar data.
 *  Copyright © 2001-2013 by David Jarvie <djarvie@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 KAEVENT_H
#define KAEVENT_H

#include "kalarmcal_export.h"

#include "datetime.h"
#include "karecurrence.h"
#include "kacalendar.h"
#include "repetition.h"

#ifndef KALARMCAL_USE_KRESOURCES
#include <akonadi/collection.h>
#include <akonadi/item.h>
#include <kcalcore/person.h>
#include <kcalcore/calendar.h>
#else
#include <kcal/person.h>
#endif

#include <QtCore/QBitArray>
#include <QColor>
#include <QFont>
#include <QtCore/QVector>
#ifdef KALARMCAL_USE_KRESOURCES
#include <QtCore/QList>
#endif
#include <QtCore/QSharedDataPointer>
#include <QtCore/QMetaType>

namespace KHolidays { class HolidayRegion; }
#ifdef KALARMCAL_USE_KRESOURCES
namespace KCal {
    class CalendarLocal;
    class Event;
}
class AlarmResource;
#endif

namespace KAlarmCal
{

class KALARMCAL_EXPORT KAAlarm
{
    public:
        enum Action
        {
            MESSAGE,   
            FILE,      
            COMMAND,   
            EMAIL,     
            AUDIO      
        };

        enum Type
        {
            INVALID_ALARM       = 0,     
            MAIN_ALARM          = 1,     
            REMINDER_ALARM      = 0x02,  
            DEFERRED_ALARM      = 0x04,  
            DEFERRED_REMINDER_ALARM = REMINDER_ALARM | DEFERRED_ALARM,  
            // The following values must be greater than the preceding ones, to
            // ensure that in ordered processing they are processed afterwards.
            AT_LOGIN_ALARM      = 0x10,  
            DISPLAYING_ALARM    = 0x20   

            // IMPORTANT: if any values are added to this list, ensure that the
            //            KAEventPrivate::AlarmType enum is adjusted similarly.
        };

        KAAlarm();

        KAAlarm(const KAAlarm& other);

        ~KAAlarm();

        KAAlarm& operator=(const KAAlarm& other);

        Action action() const;

        bool isValid() const;

        Type type() const;

        DateTime dateTime(bool withRepeats = false) const;

        QDate date() const;

        QTime time() const;

        void setTime(const DateTime& dt);
        void setTime(const KDateTime& dt);

        bool repeatAtLogin() const;

        bool isReminder() const;

        bool deferred() const;

        bool timedDeferral() const;

        static const char* debugType(Type);

    private:
        //@cond PRIVATE
        class Private;
        Private* const d;
        //@endcond

    friend class KAEvent;
    friend class KAEventPrivate;
};

class KAEventPrivate;

class KALARMCAL_EXPORT KAEvent
{
    public:
        typedef QVector<KAEvent*> List;

        enum Flag
        {
            BEEP            = 0x02,    
            REPEAT_AT_LOGIN = 0x04,    
            ANY_TIME        = 0x08,    
            CONFIRM_ACK     = 0x10,    
            EMAIL_BCC       = 0x20,    
            DEFAULT_FONT    = 0x40,    
            REPEAT_SOUND    = 0x80,    
            DISABLED        = 0x100,   
            AUTO_CLOSE      = 0x200,   
            SCRIPT          = 0x400,   
            EXEC_IN_XTERM   = 0x800,   
            SPEAK           = 0x1000,  
            COPY_KORGANIZER = 0x2000,  
            EXCL_HOLIDAYS   = 0x4000,  
            WORK_TIME_ONLY  = 0x8000,  
            DISPLAY_COMMAND = 0x10000, 
            REMINDER_ONCE   = 0x20000  

            // IMPORTANT: if any values are added to this list, ensure that the
            //            additional enum values in KAEventPrivate are also adjusted.
        };
        Q_DECLARE_FLAGS(Flags, Flag)

        
        enum Actions
        {
            ACT_NONE            = 0,      
            ACT_DISPLAY         = 0x01,   
            ACT_COMMAND         = 0x02,   
            ACT_EMAIL           = 0x04,   
            ACT_AUDIO           = 0x08,   
            ACT_DISPLAY_COMMAND = ACT_DISPLAY | ACT_COMMAND,  
            ACT_ALL             = ACT_DISPLAY | ACT_COMMAND | ACT_EMAIL | ACT_AUDIO   
        };

        enum SubAction
        {
            MESSAGE = KAAlarm::MESSAGE,    
            FILE    = KAAlarm::FILE,       
            COMMAND = KAAlarm::COMMAND,    
            EMAIL   = KAAlarm::EMAIL,      
            AUDIO   = KAAlarm::AUDIO       
        };

        enum OccurType
        {
            NO_OCCURRENCE            = 0,      
            FIRST_OR_ONLY_OCCURRENCE = 0x01,   
            RECURRENCE_DATE          = 0x02,   
            RECURRENCE_DATE_TIME     = 0x03,   
            LAST_RECURRENCE          = 0x04,   
            OCCURRENCE_REPEAT        = 0x10,   
            FIRST_OR_ONLY_OCCURRENCE_REPEAT = OCCURRENCE_REPEAT | FIRST_OR_ONLY_OCCURRENCE, 
            RECURRENCE_DATE_REPEAT          = OCCURRENCE_REPEAT | RECURRENCE_DATE,          
            RECURRENCE_DATE_TIME_REPEAT     = OCCURRENCE_REPEAT | RECURRENCE_DATE_TIME,     
            LAST_RECURRENCE_REPEAT          = OCCURRENCE_REPEAT | LAST_RECURRENCE           
        };

        enum OccurOption
        {
            IGNORE_REPETITION,    
            RETURN_REPETITION,    
            ALLOW_FOR_REPETITION  
        };

        enum DeferLimitType
        {
            LIMIT_NONE,        
            LIMIT_MAIN,        
            LIMIT_RECURRENCE,  
            LIMIT_REPETITION,  
            LIMIT_REMINDER     
        };

        enum TriggerType
        {
            ALL_TRIGGER,       
            MAIN_TRIGGER,      
            WORK_TRIGGER,      
            ALL_WORK_TRIGGER,  
            DISPLAY_TRIGGER    
        };

        enum CmdErrType
        {
            CMD_NO_ERROR   = 0,      
            CMD_ERROR      = 0x01,   
            CMD_ERROR_PRE  = 0x02,   
            CMD_ERROR_POST = 0x04,   
            CMD_ERROR_PRE_POST = CMD_ERROR_PRE | CMD_ERROR_POST
        };

        enum ExtraActionOption
        {
            CancelOnPreActError  = 0x01,   
            DontShowPreActError  = 0x02,   
            ExecPreActOnDeferral = 0x04    
        };
        Q_DECLARE_FLAGS(ExtraActionOptions, ExtraActionOption)

        
        enum UidAction
        {
            UID_IGNORE,        
            UID_CHECK,         
            UID_SET            
        };

        KAEvent();

        KAEvent(const KDateTime&, const QString& text, const QColor& bg, const QColor& fg,
                const QFont& f, SubAction, int lateCancel, Flags flags, bool changesPending = false);
#ifndef KALARMCAL_USE_KRESOURCES

        explicit KAEvent(const KCalCore::Event::Ptr&);

        void set(const KCalCore::Event::Ptr&);
#else

        explicit KAEvent(const KCal::Event*);

        void set(const KCal::Event*);
#endif

        KAEvent(const KAEvent& other);
        ~KAEvent();

        KAEvent& operator=(const KAEvent& other);

        void set(const KDateTime& dt, const QString& text, const QColor& bg,
                 const QColor& fg, const QFont& font, SubAction action, int lateCancel,
                 Flags flags, bool changesPending = false);

#ifndef KALARMCAL_USE_KRESOURCES

        bool updateKCalEvent(const KCalCore::Event::Ptr& event, UidAction u, bool setCustomProperties = true) const;
#else

        bool updateKCalEvent(KCal::Event* event, UidAction u) const;
#endif

        bool isValid() const;

        void setEnabled(bool enable);
        bool enabled() const;

#ifndef KALARMCAL_USE_KRESOURCES

        void setReadOnly(bool ro);
        bool isReadOnly() const;
#endif

        void setArchive();
        bool toBeArchived() const;

        bool mainExpired() const;
        bool expired() const;

        Flags flags() const;

        void setCategory(CalEvent::Type type);

        CalEvent::Type category() const;

        void setEventId(const QString& id);

        QString id() const;

        void incrementRevision();
        int revision() const;

#ifndef KALARMCAL_USE_KRESOURCES

        void setCollectionId(Akonadi::Collection::Id id);
        void setCollectionId_const(Akonadi::Collection::Id id) const;
        Akonadi::Collection::Id  collectionId() const;

        void setItemId(Akonadi::Item::Id id);
        Akonadi::Item::Id  itemId() const;

        bool setItemPayload(Akonadi::Item&, const QStringList& collectionMimeTypes) const;

        void setCompatibility(KACalendar::Compat c);
        KACalendar::Compat compatibility() const;

        QMap<QByteArray, QString> customProperties() const;
#else

        void setResource(AlarmResource* r);

        AlarmResource* resource() const;
#endif

        SubAction actionSubType() const;

        Actions actionTypes() const;

        void setLateCancel(int minutes);

        int lateCancel() const;

        void setAutoClose(bool autoclose);

        bool autoClose() const;

        void               setKMailSerialNumber(unsigned long n);
        unsigned long      kmailSerialNumber() const;

        QString cleanText() const;
        QString message() const;
        QString displayMessage() const;
        QString fileName() const;

        QColor bgColour() const;
        QColor fgColour() const;

        static void setDefaultFont(const QFont& font);
        bool useDefaultFont() const;
        QFont font() const;

        QString command() const;
        bool commandScript() const;
        bool commandXterm() const;
        bool commandDisplay() const;
#ifndef KALARMCAL_USE_KRESOURCES

        void setCommandError(CmdErrType error) const;
#else

        void setCommandError(CmdErrType error, bool writeConfig = true) const;
        void setCommandError(const QString& configString);
        static QString commandErrorConfigGroup();
#endif

        CmdErrType commandError() const;

        void setLogFile(const QString& logfile);
        QString logFile() const;

        bool confirmAck() const;

        bool copyToKOrganizer() const;

#ifndef KALARMCAL_USE_KRESOURCES
        void setEmail(uint from, const KCalCore::Person::List&, const QString& subject,
                      const QStringList& attachments);
#else
        void setEmail(uint from, const QList<KCal::Person>&, const QString& subject,
                      const QStringList& attachments);
#endif

        QString emailMessage() const;

        uint emailFromId() const;

#ifndef KALARMCAL_USE_KRESOURCES
        KCalCore::Person::List emailAddressees() const;
#else
        QList<KCal::Person> emailAddressees() const;
#endif

        QStringList emailAddresses() const;

        QString emailAddresses(const QString& sep) const;

#ifndef KALARMCAL_USE_KRESOURCES
        static QString joinEmailAddresses(const KCalCore::Person::List& addresses, const QString& sep);
#else
        static QString joinEmailAddresses(const QList<KCal::Person>& addresses, const QString& sep);
#endif

        QStringList emailPureAddresses() const;

        QString emailPureAddresses(const QString& sep) const;

        QString emailSubject() const;

        QStringList emailAttachments() const;

        QString emailAttachments(const QString& sep) const;

        bool emailBcc() const;

        void setAudioFile(const QString& filename, float volume, float fadeVolume,
                          int fadeSeconds, int repeatPause = -1, bool allowEmptyFile = false);

        QString audioFile() const;

        float soundVolume() const;

        float fadeVolume() const;

        int fadeSeconds() const;

        bool repeatSound() const;

        int repeatSoundPause() const;

        bool beep() const;

        bool speak() const;

        void setTemplate(const QString& name, int afterTime = -1);

        bool isTemplate() const;

        QString templateName() const;

        bool usingDefaultTime() const;

        int templateAfterTime() const;

        void setActions(const QString& pre, const QString& post, ExtraActionOptions options);

        void setActions(const QString& pre, const QString& post, bool cancelOnError, bool dontShowError);

        QString preAction() const;

        QString postAction() const;

        ExtraActionOptions extraActionOptions() const;

        bool cancelOnPreActionError() const;

        bool dontShowPreActionError() const;

        void setReminder(int minutes, bool onceOnly);

        void activateReminderAfter(const DateTime& mainAlarmTime);

        int reminderMinutes() const;
        bool reminderActive() const;
        bool reminderOnceOnly() const;
        bool reminderDeferral() const;

        void defer(const DateTime& dt, bool reminder, bool adjustRecurrence = false);

        void cancelDefer();
        void setDeferDefaultMinutes(int minutes, bool dateOnly = false);
        bool deferred() const;
        DateTime deferDateTime() const;

        DateTime deferralLimit(DeferLimitType* limitType = 0) const;

        int deferDefaultMinutes() const;
        bool deferDefaultDateOnly() const;

        DateTime startDateTime() const;
        void setTime(const KDateTime& dt);
        DateTime mainDateTime(bool withRepeats = false) const;

        QTime mainTime() const;
        DateTime mainEndRepeatTime() const;

        static void setStartOfDay(const QTime&);

        static void adjustStartOfDay(const KAEvent::List& events);

        DateTime nextTrigger(TriggerType type) const;

        void setCreatedDateTime(const KDateTime& dt);
        KDateTime createdDateTime() const;

        void setRepeatAtLogin(bool repeat);

        bool repeatAtLogin(bool includeArchived = false) const;

        void setExcludeHolidays(bool exclude);
        bool holidaysExcluded() const;

        static void setHolidays(const KHolidays::HolidayRegion& region);

        void setWorkTimeOnly(bool wto);
        bool workTimeOnly() const;

        bool isWorkingTime(const KDateTime& dt) const;

        static void setWorkTime(const QBitArray& days, const QTime& start, const QTime& end);

        void setNoRecur();

        void setRecurrence(const KARecurrence& r);

        bool setRecurMinutely(int freq, int count, const KDateTime& end);

        bool setRecurDaily(int freq, const QBitArray& days, int count, const QDate& end);

        bool setRecurWeekly(int freq, const QBitArray& days, int count, const QDate& end);

        bool setRecurMonthlyByDate(int freq, const QVector<int>& days, int count, const QDate& end);

        struct MonthPos
        {
            MonthPos() : days(7) {}    //krazy:exclude=inline (need default constructor)
            int        weeknum;     
            QBitArray  days;        
        };

        bool setRecurMonthlyByPos(int freq, const QVector<MonthPos>& pos, int count, const QDate& end);

        bool setRecurAnnualByDate(int freq, const QVector<int>& months, int day, KARecurrence::Feb29Type, int count, const QDate& end);

        bool setRecurAnnualByPos(int freq, const QVector<MonthPos>& pos, const QVector<int>& months, int count, const QDate& end);

        bool recurs() const;
        KARecurrence::Type recurType() const;
        KARecurrence* recurrence() const;

        int recurInterval() const;

#ifndef KALARMCAL_USE_KRESOURCES
        KCalCore::Duration longestRecurrenceInterval() const;
#else
        KCal::Duration longestRecurrenceInterval() const;
#endif

        void setFirstRecurrence();

        QString recurrenceText(bool brief = false) const;

        bool setRepetition(const Repetition& r);

        Repetition repetition() const;

        int nextRepetition() const;

        QString repetitionText(bool brief = false) const;

        bool occursAfter(const KDateTime& preDateTime, bool includeRepetitions) const;

        OccurType setNextOccurrence(const KDateTime& preDateTime);

        OccurType nextOccurrence(const KDateTime& preDateTime, DateTime& result, OccurOption option = IGNORE_REPETITION) const;

        OccurType previousOccurrence(const KDateTime& afterDateTime, DateTime& result, bool includeRepetitions = false) const;

#ifndef KALARMCAL_USE_KRESOURCES
        bool setDisplaying(const KAEvent& event, KAAlarm::Type type, Akonadi::Collection::Id colId, const KDateTime& repeatAtLoginTime, bool showEdit, bool showDefer);
#else
        bool setDisplaying(const KAEvent& event, KAAlarm::Type type, const QString& resourceID, const KDateTime& repeatAtLoginTime, bool showEdit, bool showDefer);
#endif

#ifndef KALARMCAL_USE_KRESOURCES

        void reinstateFromDisplaying(const KCalCore::Event::Ptr& event, Akonadi::Collection::Id& colId, bool& showEdit, bool& showDefer);
#else
        void reinstateFromDisplaying(const KCal::Event* event, QString& resourceID, bool& showEdit, bool& showDefer);
#endif

        KAAlarm convertDisplayingAlarm() const;

        bool displaying() const;

        KAAlarm alarm(KAAlarm::Type type) const;

        KAAlarm firstAlarm() const;

        KAAlarm nextAlarm(const KAAlarm& previousAlarm) const;
        KAAlarm nextAlarm(KAAlarm::Type previousType) const;

        int alarmCount() const;

        void removeExpiredAlarm(KAAlarm::Type type);

        void startChanges();
        void endChanges();

        static int currentCalendarVersion();

        static QByteArray currentCalendarVersionString();

#ifndef KALARMCAL_USE_KRESOURCES
        static bool convertKCalEvents(const KCalCore::Calendar::Ptr&, int calendarVersion);
#else
        static bool convertKCalEvents(KCal::CalendarLocal&, int calendarVersion);
#endif

#ifndef KALARMCAL_USE_KRESOURCES

        static List ptrList(QVector<KAEvent>& events);
#endif

        void dumpDebug() const;

    private:
        QSharedDataPointer<KAEventPrivate> d;
};

} // namespace KAlarmCal

Q_DECLARE_OPERATORS_FOR_FLAGS(KAlarmCal::KAEvent::Flags)
Q_DECLARE_METATYPE(KAlarmCal::KAEvent)

#endif // KAEVENT_H

// vim: et sw=4: