calendar.h

Go to the documentation of this file.

/*
  This file is part of the kcalcore library.

  Copyright (c) 1998 Preston Brown <pbrown@kde.org>
  Copyright (c) 2001,2003,2004 Cornelius Schumacher <schumacher@kde.org>
  Copyright (C) 2003-2004 Reinhold Kainhofer <reinhold@kainhofer.com>
  Copyright (c) 2006 David Jarvie <software@astrojar.org.uk>

  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 KCALCORE_CALENDAR_H
#define KCALCORE_CALENDAR_H

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

#include <QtCore/QObject>

namespace KCalCore {

class CalFilter;
class Person;
class ICalTimeZones;

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 KCALCORE_EXPORT Calendar : public QObject, public CustomProperties,
    public IncidenceBase::IncidenceObserver
{
    Q_OBJECT

public:

    typedef QSharedPointer<Calendar> Ptr;

    explicit Calendar(const KDateTime::Spec &timeSpec);

    explicit Calendar(const QString &timeZoneId);

    virtual ~Calendar();

    void setProductId(const QString &id);

    QString productId() const;

    void setOwner(const Person::Ptr &owner);

    Person::Ptr owner() const;

    void setTimeSpec(const KDateTime::Spec &timeSpec);

    KDateTime::Spec timeSpec() const;

    void setTimeZoneId(const QString &timeZoneId);

    QString timeZoneId() const;

    void setViewTimeSpec(const KDateTime::Spec &timeSpec) const;

    void setViewTimeZoneId(const QString &timeZoneId) const;

    KDateTime::Spec viewTimeSpec() const;

    QString viewTimeZoneId() const;

    void shiftTimes(const KDateTime::Spec &oldSpec, const KDateTime::Spec &newSpec);

    ICalTimeZones *timeZones() const;

    void setTimeZones(ICalTimeZones *zones);

    void setModified(bool modified);

    bool isModified() const;

    virtual void close() = 0;

    virtual bool save();

    virtual bool reload();

    virtual bool isSaving() const;

    QStringList categories() const;

    // Incidence Specific Methods //

    virtual void startBatchAdding();

    virtual void endBatchAdding();

    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;

    bool hasValidNotebook(const QString &notebook) const;

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

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

    bool deleteNotebook(const QString &notebook);

    bool setDefaultNotebook(const QString &notebook);

    QString defaultNotebook() const;

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

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

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

    Incidence::Ptr incidence(const QString &uid,
                             const KDateTime &recurrenceId = KDateTime()) const;

    Incidence::Ptr deleted(const QString &uid, const KDateTime &recurrenceId = KDateTime()) 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);

    KCALCORE_DEPRECATED Incidence::Ptr dissociateOccurrence(
        const Incidence::Ptr &incidence, const QDate &date,
        const KDateTime::Spec &spec, bool single = true);
    static Incidence::Ptr createException(const Incidence::Ptr &incidence,
                                          const KDateTime &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;

    virtual void deleteAllEvents() = 0;

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

    Event::List events(const KDateTime &dt) const;

    Event::List events(const QDate &start, const QDate &end,
                       const KDateTime::Spec &timeSpec = KDateTime::Spec(),
                       bool inclusive = false) const;

    Event::List events(const QDate &date,
                       const KDateTime::Spec &timeSpec = KDateTime::Spec(),
                       EventSortField sortField = EventSortUnsorted,
                       SortDirection sortDirection = SortDirectionAscending) const;

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

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

    virtual Event::List rawEvents(const QDate &start, const QDate &end,
                                  const KDateTime::Spec &timeSpec = KDateTime::Spec(),
                                  bool inclusive = false) const = 0;

    virtual Event::List rawEventsForDate(
        const QDate &date,
        const KDateTime::Spec &timeSpec = KDateTime::Spec(),
        EventSortField sortField = EventSortUnsorted,
        SortDirection sortDirection = SortDirectionAscending) const = 0;

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

    virtual Event::Ptr deletedEvent(const QString &uid,
                                    const KDateTime &recurrenceId = KDateTime()) 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;

    virtual void deleteAllTodos() = 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 KDateTime::Spec &timespec = KDateTime::Spec(),
                             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 KDateTime::Spec &timespec = KDateTime::Spec(),
                                bool inclusive = false) const = 0;

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

    virtual Todo::Ptr deletedTodo(const QString &uid,
                                  const KDateTime &recurrenceId = KDateTime()) 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;

    virtual void deleteAllJournals() = 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 KDateTime &recurrenceId = KDateTime()) const = 0;

    virtual Journal::Ptr deletedJournal(const QString &uid,
                                        const KDateTime &recurrenceId = KDateTime()) 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 KDateTime &from, const KDateTime &to) const = 0;

    // Observer Specific Methods //

    class KCALCORE_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 calendarIncidenceDeleted(const Incidence::Ptr &incidence);

        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 KDateTime &recurrenceId);

    virtual void doSetTimeSpec(const KDateTime::Spec &timeSpec);

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

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

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

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

    virtual void customPropertyUpdated();

    void setObserversEnabled(bool enabled);

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

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

    void setDeletionTracking(bool enable);

    bool deletionTracking() const;

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

Q_SIGNALS:
    void filterChanged();

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

    Q_DISABLE_COPY(Calendar)
};

}

#endif