calendar.h

Go to the documentation of this file.

/*
  This file is part of the kcal 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 KCAL_CALENDAR_H
#define KCAL_CALENDAR_H

#include <QtCore/QObject>
#include <QtCore/QString>
#include <QtCore/QList>
#include <QtCore/QMultiHash>

#include <kdatetime.h>

#include "customproperties.h"
#include "event.h"
#include "todo.h"
#include "journal.h"
#include "kcalversion.h"

namespace KCal {

class ICalTimeZone;
class ICalTimeZones;
class CalFilter;
class Person;

enum SortDirection {
  SortDirectionAscending,  
  SortDirectionDescending  
};

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

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

enum JournalSortField {
  JournalSortUnsorted,     
  JournalSortDate,         
  JournalSortSummary       
};

class KCAL_DEPRECATED_EXPORT Calendar : public QObject, public CustomProperties,
                             public IncidenceBase::IncidenceObserver
{
  Q_OBJECT

  public:

    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 &owner );

    Person 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( const ICalTimeZones &zones );

    void setModified( bool modified );

    bool isModified() const;

    virtual void close() = 0;

    virtual bool save() = 0;

    virtual bool reload() = 0;

    virtual bool isSaving();

    QStringList categories();

  // Incidence Specific Methods //

    virtual bool addIncidence( Incidence *incidence );

    virtual bool deleteIncidence( Incidence *incidence );

    virtual Incidence::List incidences();

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

    virtual Incidence::List rawIncidences();

    Incidence *incidence( const QString &uid );

    Incidence *incidenceFromSchedulingID( const QString &sid );

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

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

    virtual bool beginChange( Incidence *incidence );

    virtual bool endChange( Incidence *incidence );

    Incidence *dissociateOccurrence( Incidence *incidence, const QDate &date,
                                     const KDateTime::Spec &spec,
                                     bool single = true );

  // Event Specific Methods //

    virtual bool addEvent( Event *event ) = 0;

    virtual bool deleteEvent( Event *event ) = 0;

    virtual void deleteAllEvents() = 0;

    static Event::List sortEvents( Event::List *eventList,
                                   EventSortField sortField,
                                   SortDirection sortDirection );

    static Event::List sortEventsForDate( Event::List *eventList,
                                          const QDate &date,
                                          const KDateTime::Spec &timeSpec,
                                          EventSortField sortField,
                                          SortDirection sortDirection );

    virtual Event::List events(
      EventSortField sortField = EventSortUnsorted,
      SortDirection sortDirection = SortDirectionAscending );

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

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

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

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

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

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

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

    virtual Event *event( const QString &uid ) = 0;

  // Todo Specific Methods //

    virtual bool addTodo( Todo *todo ) = 0;

    virtual bool deleteTodo( Todo *todo ) = 0;

    virtual void deleteAllTodos() = 0;

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

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

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

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

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

    virtual Todo *todo( const QString &uid ) = 0;

  // Journal Specific Methods //

    virtual bool addJournal( Journal *journal ) = 0;

    virtual bool deleteJournal( Journal *journal ) = 0;

    virtual void deleteAllJournals() = 0;

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

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

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

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

    virtual Journal *journal( const QString &uid ) = 0;

    void beginBatchAdding();

    void endBatchAdding();

  // Relations Specific Methods //

    virtual void setupRelations( Incidence *incidence );

    virtual void removeRelations( Incidence *incidence );

    bool isAncestorOf( Incidence *ancestor, Incidence *incidence );

  // Filter Specific Methods //

    void setFilter( CalFilter *filter );

    CalFilter *filter();

  // Alarm Specific Methods //

    virtual Alarm::List alarms( const KDateTime &from,
                                const KDateTime &to ) = 0;

  // Observer Specific Methods //

    class KCAL_DEPRECATED_EXPORT CalendarObserver //krazy:exclude=dpointer
    {
      public:
        virtual ~CalendarObserver() {}

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

        virtual void calendarIncidenceAdded( Incidence *incidence );

        virtual void calendarIncidenceChanged( Incidence *incidence );

        virtual void calendarIncidenceDeleted( Incidence *incidence );
    };

    void registerObserver( CalendarObserver *observer );

    void unregisterObserver( CalendarObserver *observer );

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

  Q_SIGNALS:
    void calendarChanged();

    void calendarSaved();

    void calendarLoaded();

    void batchAddingBegins();

    void batchAddingEnds();

  protected:
    void incidenceUpdated( IncidenceBase *incidenceBase );

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

    void notifyIncidenceAdded( Incidence *incidence );

    void notifyIncidenceChanged( Incidence *incidence );

    void notifyIncidenceDeleted( Incidence *incidence );

    virtual void customPropertyUpdated();

    void setObserversEnabled( bool enabled );

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

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

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

    Q_DISABLE_COPY( Calendar )
};

}

#endif