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