calendar.h

Go to the documentation of this file.

/*
  This file is part of the kcalcore library.

  SPDX-FileCopyrightText: 1998 Preston Brown <[email protected]>
  SPDX-FileCopyrightText 2001, 2003, 2004 Cornelius Schumacher <[email protected]>
  SPDX-FileCopyrightText: 2003-2004 Reinhold Kainhofer <[email protected]>
  SPDX-FileCopyrightText: 2006 David Jarvie <[email protected]>

  SPDX-License-Identifier: LGPL-2.0-or-later
*/
/*

TODO: KDE5:

This API needs serious cleaning up:
- Most (all) methods aren't async ( deleteIncidence(), addIncidence(), load(), save(), ... )
  so it's not very easy to make a derived class that loads from akonadi.

- It has too many methods. Why do we need fooEvent()/fooJournal()/fooTodo() when fooIncidence()
  should be enough.

*/

#ifndef KCALCORE_CALENDAR_H
#define KCALCORE_CALENDAR_H

#include "kcalendarcore_export.h"
#include "event.h"
#include "customproperties.h"
#include "incidence.h"
#include "journal.h"
#include "todo.h"

#include <QObject>
#include <QDateTime>
#include <QTimeZone>

namespace KCalendarCore
{

class CalFilter;
class Person;
class ICalFormat;

enum SortDirection {
    SortDirectionAscending,  
    SortDirectionDescending  
};

enum EventSortField {
    EventSortUnsorted,       
    EventSortStartDate,      
    EventSortEndDate,        
    EventSortSummary         
};

enum TodoSortField {
    TodoSortUnsorted,        
    TodoSortStartDate,       
    TodoSortDueDate,         
    TodoSortPriority,        
    TodoSortPercentComplete, 
    TodoSortSummary,         
    TodoSortCreated          
};

enum JournalSortField {
    JournalSortUnsorted,     
    JournalSortDate,         
    JournalSortSummary       
};

class KCALENDARCORE_EXPORT Calendar : public QObject, public CustomProperties,
    public IncidenceBase::IncidenceObserver
{
    Q_OBJECT
    Q_PROPERTY(QString productId READ productId WRITE setProductId) //clazy:exclude=qproperty-without-notify
    Q_PROPERTY(KCalendarCore::Person owner READ owner WRITE setOwner)

public:

    typedef QSharedPointer<Calendar> Ptr;

    explicit Calendar(const QTimeZone &timeZone);

    explicit Calendar(const QByteArray &timeZoneId);

    ~Calendar() override;

    void setProductId(const QString &id);

    Q_REQUIRED_RESULT QString productId() const;

    void setOwner(const Person &owner);

    Q_REQUIRED_RESULT Person owner() const;

    void setTimeZone(const QTimeZone &timeZone);

    Q_REQUIRED_RESULT QTimeZone timeZone() const;

    void setTimeZoneId(const QByteArray &timeZoneId);

    Q_REQUIRED_RESULT QByteArray timeZoneId() const;

    void shiftTimes(const QTimeZone &oldZone, const QTimeZone &newZone);

    void setModified(bool modified);

    Q_REQUIRED_RESULT bool isModified() const;

    virtual void close() = 0;

    virtual bool save();

    virtual bool reload();

    virtual bool isSaving() const;

    Q_REQUIRED_RESULT QStringList categories() const;

    // Incidence Specific Methods //

    virtual void startBatchAdding();

    virtual void endBatchAdding();

    Q_REQUIRED_RESULT bool batchAdding() const;

    virtual bool addIncidence(const Incidence::Ptr &incidence);

    virtual bool deleteIncidence(const Incidence::Ptr &incidence);

    virtual Incidence::List incidences() const;

    virtual Incidence::List incidences(const QDate &date) const;

    virtual Incidence::List rawIncidences() const;

    virtual Incidence::List instances(const Incidence::Ptr &incidence) const;

    // Notebook Specific Methods //

    virtual void clearNotebookAssociations();

    virtual bool setNotebook(const Incidence::Ptr &incidence, const QString &notebook);

    virtual QString notebook(const Incidence::Ptr &incidence) const;

    virtual QString notebook(const QString &uid) const;

    virtual QStringList notebooks() const;

    Q_REQUIRED_RESULT bool hasValidNotebook(const QString &notebook) const;

    Q_REQUIRED_RESULT bool addNotebook(const QString &notebook, bool isVisible);

    Q_REQUIRED_RESULT bool updateNotebook(const QString &notebook, bool isVisible);

    Q_REQUIRED_RESULT bool deleteNotebook(const QString &notebook);

    Q_REQUIRED_RESULT bool setDefaultNotebook(const QString &notebook);

    Q_REQUIRED_RESULT QString defaultNotebook() const;

    Q_REQUIRED_RESULT bool isVisible(const Incidence::Ptr &incidence) const;

    Q_REQUIRED_RESULT bool isVisible(const QString &notebook) const;

    virtual Incidence::List incidences(const QString &notebook) const;

    virtual Incidence::List duplicates(const Incidence::Ptr &incidence);

    Incidence::Ptr incidence(const QString &uid,
                             const QDateTime &recurrenceId = {}) const;

    Incidence::Ptr deleted(const QString &uid, const QDateTime &recurrenceId = {}) const;

    virtual bool deleteIncidenceInstances(const Incidence::Ptr &incidence) = 0;

    virtual Incidence::Ptr incidenceFromSchedulingID(const QString &sid) const;

    virtual Incidence::List incidencesFromSchedulingID(const QString &sid) const;

    static Incidence::List mergeIncidenceList(const Event::List &events,
            const Todo::List &todos,
            const Journal::List &journals);

    virtual bool beginChange(const Incidence::Ptr &incidence);

    virtual bool endChange(const Incidence::Ptr &incidence);

    static Incidence::Ptr createException(const Incidence::Ptr &incidence,
                                          const QDateTime &recurrenceId,
                                          bool thisAndFuture = false);

    // Event Specific Methods //

    virtual bool addEvent(const Event::Ptr &event) = 0;

    virtual bool deleteEvent(const Event::Ptr &event) = 0;

    virtual bool deleteEventInstances(const Event::Ptr &event) = 0;

    static Event::List sortEvents(const Event::List &eventList,
                                  EventSortField sortField,
                                  SortDirection sortDirection);
    virtual Event::List events(EventSortField sortField = EventSortUnsorted,
                               SortDirection sortDirection = SortDirectionAscending) const;

    Q_REQUIRED_RESULT Event::List events(const QDateTime &dt) const;

    Q_REQUIRED_RESULT Event::List events(const QDate &start, const QDate &end,
                       const QTimeZone &timeZone = {},
                       bool inclusive = false) const;

    Q_REQUIRED_RESULT Event::List events(const QDate &date,
                       const QTimeZone &timeZone = {},
                       EventSortField sortField = EventSortUnsorted,
                       SortDirection sortDirection = SortDirectionAscending) const;

    virtual Event::List rawEvents(
        EventSortField sortField = EventSortUnsorted,
        SortDirection sortDirection = SortDirectionAscending) const = 0;

    virtual Event::List rawEventsForDate(const QDateTime &dt) const = 0;

    virtual Event::List rawEvents(const QDate &start, const QDate &end,
                                  const QTimeZone &timeZone = {},
                                  bool inclusive = false) const = 0;

    virtual Event::List rawEventsForDate(
        const QDate &date,
        const QTimeZone &timeZone = {},
        EventSortField sortField = EventSortUnsorted,
        SortDirection sortDirection = SortDirectionAscending) const = 0;

    virtual Event::Ptr event(const QString &uid,
                             const QDateTime &recurrenceId = {}) const = 0;

    virtual Event::Ptr deletedEvent(const QString &uid,
                                    const QDateTime &recurrenceId = {}) const = 0;

    virtual Event::List deletedEvents(
        EventSortField sortField = EventSortUnsorted,
        SortDirection sortDirection = SortDirectionAscending) const = 0;

    virtual Event::List eventInstances(
        const Incidence::Ptr &event,
        EventSortField sortField = EventSortUnsorted,
        SortDirection sortDirection = SortDirectionAscending) const = 0;

    // Todo Specific Methods //

    virtual bool addTodo(const Todo::Ptr &todo) = 0;

    virtual bool deleteTodo(const Todo::Ptr &todo) = 0;

    virtual bool deleteTodoInstances(const Todo::Ptr &todo) = 0;

    static Todo::List sortTodos(const Todo::List &todoList,
                                TodoSortField sortField,
                                SortDirection sortDirection);

    virtual Todo::List todos(TodoSortField sortField = TodoSortUnsorted,
                             SortDirection sortDirection = SortDirectionAscending) const;

    virtual Todo::List todos(const QDate &date) const;

    virtual Todo::List todos(const QDate &start, const QDate &end,
                             const QTimeZone &timeZone = {},
                             bool inclusive = false) const;

    virtual Todo::List rawTodos(
        TodoSortField sortField = TodoSortUnsorted,
        SortDirection sortDirection = SortDirectionAscending) const = 0;

    virtual Todo::List rawTodosForDate(const QDate &date) const = 0;

    virtual Todo::List rawTodos(const QDate &start, const QDate &end,
                                const QTimeZone &timeZone = {},
                                bool inclusive = false) const = 0;

    virtual Todo::Ptr todo(const QString &uid,
                           const QDateTime &recurrenceId = {}) const = 0;

    virtual Todo::Ptr deletedTodo(const QString &uid,
                                  const QDateTime &recurrenceId = {}) const = 0;

    virtual Todo::List deletedTodos(
        TodoSortField sortField = TodoSortUnsorted,
        SortDirection sortDirection = SortDirectionAscending) const = 0;

    virtual Todo::List todoInstances(
        const Incidence::Ptr &todo,
        TodoSortField sortField = TodoSortUnsorted,
        SortDirection sortDirection = SortDirectionAscending) const = 0;

    // Journal Specific Methods //

    virtual bool addJournal(const Journal::Ptr &journal) = 0;

    virtual bool deleteJournal(const Journal::Ptr &journal) = 0;

    virtual bool deleteJournalInstances(const Journal::Ptr &journal) = 0;

    static Journal::List sortJournals(const Journal::List &journalList,
                                      JournalSortField sortField,
                                      SortDirection sortDirection);
    virtual Journal::List journals(
        JournalSortField sortField = JournalSortUnsorted,
        SortDirection sortDirection = SortDirectionAscending) const;

    virtual Journal::List journals(const QDate &date) const;

    virtual Journal::List rawJournals(
        JournalSortField sortField = JournalSortUnsorted,
        SortDirection sortDirection = SortDirectionAscending) const = 0;

    virtual Journal::List rawJournalsForDate(const QDate &date) const = 0;

    virtual Journal::Ptr journal(const QString &uid,
                                 const QDateTime &recurrenceId = {}) const = 0;

    virtual Journal::Ptr deletedJournal(const QString &uid,
                                        const QDateTime &recurrenceId = {}) const = 0;

    virtual Journal::List deletedJournals(
        JournalSortField sortField = JournalSortUnsorted,
        SortDirection sortDirection = SortDirectionAscending) const = 0;

    virtual Journal::List journalInstances(
        const Incidence::Ptr &journal,
        JournalSortField sortField = JournalSortUnsorted,
        SortDirection sortDirection = SortDirectionAscending) const = 0;

    // Relations Specific Methods //

    virtual void setupRelations(const Incidence::Ptr &incidence);

    virtual void removeRelations(const Incidence::Ptr &incidence);

    bool isAncestorOf(const Incidence::Ptr &ancestor,
                      const Incidence::Ptr &incidence) const;

    Incidence::List relations(const QString &uid) const;

    // Filter Specific Methods //

    void setFilter(CalFilter *filter);

    CalFilter *filter() const;

    // Alarm Specific Methods //

    virtual Alarm::List alarms(const QDateTime &from, const QDateTime &to, bool excludeBlockedAlarms = false) const = 0;

    Q_REQUIRED_RESULT Alarm::List alarmsTo(const QDateTime &to) const;


    // Observer Specific Methods //

    class KCALENDARCORE_EXPORT CalendarObserver //krazy:exclude=dpointer
    {
    public:
        virtual ~CalendarObserver();

        virtual void calendarModified(bool modified, Calendar *calendar);

        virtual void calendarIncidenceAdded(const Incidence::Ptr &incidence);

        virtual void calendarIncidenceChanged(const Incidence::Ptr &incidence);

        virtual void calendarIncidenceAboutToBeDeleted(const Incidence::Ptr &incidence);

        virtual void calendarIncidenceDeleted(const Incidence::Ptr &incidence, const Calendar *calendar);

        virtual void calendarIncidenceAdditionCanceled(const Incidence::Ptr &incidence);
    };

    void registerObserver(CalendarObserver *observer);

    void unregisterObserver(CalendarObserver *observer);

    using QObject::event;   // prevent warning about hidden virtual method

protected:
    void incidenceUpdated(const QString &uid, const QDateTime &recurrenceId) override;

    virtual void doSetTimeZone(const QTimeZone &timeZone);

    void notifyIncidenceAdded(const Incidence::Ptr &incidence);

    void notifyIncidenceChanged(const Incidence::Ptr &incidence);

    void notifyIncidenceAboutToBeDeleted(const Incidence::Ptr &incidence);

    void notifyIncidenceDeleted(const Incidence::Ptr &incidence);

    void notifyIncidenceAdditionCanceled(const Incidence::Ptr &incidence);

    void customPropertyUpdated() override;

    void setObserversEnabled(bool enabled);

    void appendAlarms(Alarm::List &alarms, const Incidence::Ptr &incidence,
                      const QDateTime &from, const QDateTime &to) const;

    void appendRecurringAlarms(Alarm::List &alarms, const Incidence::Ptr &incidence,
                               const QDateTime &from, const QDateTime &to) const;

    void setDeletionTracking(bool enable);

    bool deletionTracking() const;

    virtual void virtual_hook(int id, void *data);

Q_SIGNALS:
    void filterChanged();

private:
    friend class ICalFormat;

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

    Q_DISABLE_COPY(Calendar)
};

}

Q_DECLARE_METATYPE(KCalendarCore::Calendar::Ptr)

#endif