KCalCore Library

calendar.h

00001 /*
00002   This file is part of the kcalcore library.
00003 
00004   Copyright (c) 1998 Preston Brown <pbrown@kde.org>
00005   Copyright (c) 2001,2003,2004 Cornelius Schumacher <schumacher@kde.org>
00006   Copyright (C) 2003-2004 Reinhold Kainhofer <reinhold@kainhofer.com>
00007   Copyright (c) 2006 David Jarvie <software@astrojar.org.uk>
00008 
00009   This library is free software; you can redistribute it and/or
00010   modify it under the terms of the GNU Library General Public
00011   License as published by the Free Software Foundation; either
00012   version 2 of the License, or (at your option) any later version.
00013 
00014   This library is distributed in the hope that it will be useful,
00015   but WITHOUT ANY WARRANTY; without even the implied warranty of
00016   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00017   Library General Public License for more details.
00018 
00019   You should have received a copy of the GNU Library General Public License
00020   along with this library; see the file COPYING.LIB.  If not, write to
00021   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
00022   Boston, MA 02110-1301, USA.
00023 */
00035 #ifndef KCALCORE_CALENDAR_H
00036 #define KCALCORE_CALENDAR_H
00037 
00038 #include "kcalcore_export.h"
00039 #include "event.h"
00040 #include "customproperties.h"
00041 #include "incidence.h"
00042 #include "journal.h"
00043 #include "todo.h"
00044 
00045 #include <QtCore/QObject>
00046 
00047 namespace KCalCore {
00048 
00049 class CalFilter;
00050 class Person;
00051 class ICalTimeZones;
00052 
00056 enum SortDirection {
00057   SortDirectionAscending,  
00058   SortDirectionDescending  
00059 };
00060 
00064 enum EventSortField {
00065   EventSortUnsorted,       
00066   EventSortStartDate,      
00067   EventSortEndDate,        
00068   EventSortSummary         
00069 };
00070 
00074 enum TodoSortField {
00075   TodoSortUnsorted,        
00076   TodoSortStartDate,       
00077   TodoSortDueDate,         
00078   TodoSortPriority,        
00079   TodoSortPercentComplete, 
00080   TodoSortSummary,         
00081   TodoSortCreated          
00082 };
00083 
00087 enum JournalSortField {
00088   JournalSortUnsorted,     
00089   JournalSortDate,         
00090   JournalSortSummary       
00091 };
00092 
00115 class KCALCORE_EXPORT Calendar : public QObject, public CustomProperties,
00116                                  public IncidenceBase::IncidenceObserver
00117 {
00118   Q_OBJECT
00119 
00120   public:
00121 
00125     typedef QSharedPointer<Calendar> Ptr;
00126 
00137     explicit Calendar( const KDateTime::Spec &timeSpec );
00138 
00152     explicit Calendar( const QString &timeZoneId );
00153 
00157     virtual ~Calendar();
00158 
00166     void setProductId( const QString &id );
00167 
00173     QString productId() const;
00174 
00182     void setOwner( const Person::Ptr &owner );
00183 
00191     Person::Ptr owner() const;
00192 
00201     void setTimeSpec( const KDateTime::Spec &timeSpec );
00202 
00209     KDateTime::Spec timeSpec() const;
00210 
00224     void setTimeZoneId( const QString &timeZoneId );
00225 
00233     QString timeZoneId() const;
00234 
00249     void setViewTimeSpec( const KDateTime::Spec &timeSpec ) const;
00250 
00269     void setViewTimeZoneId( const QString &timeZoneId ) const;
00270 
00277     KDateTime::Spec viewTimeSpec() const;
00278 
00285     QString viewTimeZoneId() const;
00286 
00303     void shiftTimes( const KDateTime::Spec &oldSpec, const KDateTime::Spec &newSpec );
00304 
00312     ICalTimeZones *timeZones() const;
00313 
00320     void setTimeZones( ICalTimeZones *zones );
00321 
00330     void setModified( bool modified );
00331 
00339     bool isModified() const;
00340 
00344     virtual void close() = 0;
00345 
00352     virtual bool save();
00353 
00361     virtual bool reload();
00362 
00368     virtual bool isSaving() const;
00369 
00375     QStringList categories() const;
00376 
00377   // Incidence Specific Methods //
00378 
00385     virtual void startBatchAdding();
00386 
00392     virtual void endBatchAdding();
00393 
00397     bool batchAdding() const;
00398 
00408     virtual bool addIncidence( const Incidence::Ptr &incidence );
00409 
00419     virtual bool deleteIncidence( const Incidence::Ptr &incidence );
00420 
00426     virtual Incidence::List incidences() const;
00427 
00435     virtual Incidence::List incidences( const QDate &date ) const;
00436 
00442     virtual Incidence::List rawIncidences() const;
00443 
00451     virtual Incidence::List instances( const Incidence::Ptr &incidence ) const;
00452 
00453     // Notebook Specific Methods //
00454 
00459     virtual void clearNotebookAssociations();
00460 
00469     virtual bool setNotebook( const Incidence::Ptr &incidence, const QString &notebook );
00470 
00478     virtual QString notebook( const Incidence::Ptr &incidence ) const;
00479 
00487     virtual QString notebook( const QString &uid ) const;
00488 
00494     virtual QStringList notebooks() const;
00495 
00503     bool hasValidNotebook( const QString &notebook ) const;
00504 
00514     bool addNotebook( const QString &notebook, bool isVisible );
00515 
00525     bool updateNotebook( const QString &notebook, bool isVisible );
00526 
00535     bool deleteNotebook( const QString &notebook );
00536 
00543     bool setDefaultNotebook( const QString &notebook );
00544 
00550     QString defaultNotebook() const;
00551 
00557     bool isVisible( const Incidence::Ptr &incidence ) const;
00558 
00565     virtual Incidence::List incidences( const QString &notebook ) const;
00566 
00573     virtual Incidence::List duplicates( const Incidence::Ptr &incidence );
00574 
00584     Incidence::Ptr incidence( const QString &uid,
00585                               const KDateTime &recurrenceId = KDateTime() ) const;
00586 
00596     Incidence::Ptr deleted( const QString &uid, const KDateTime &recurrenceId = KDateTime() ) const;
00597 
00604     virtual bool deleteIncidenceInstances( const Incidence::Ptr &incidence ) = 0;
00605 
00614     virtual Incidence::Ptr incidenceFromSchedulingID( const QString &sid ) const;
00615 
00622     virtual Incidence::List incidencesFromSchedulingID( const QString &sid ) const;
00623 
00633     static Incidence::List mergeIncidenceList( const Event::List &events,
00634                                                const Todo::List &todos,
00635                                                const Journal::List &journals );
00636 
00641     virtual bool beginChange( const Incidence::Ptr &incidence );
00642 
00647     virtual bool endChange( const Incidence::Ptr &incidence );
00648 
00666     Incidence::Ptr dissociateOccurrence( const Incidence::Ptr &incidence, const QDate &date,
00667                                          const KDateTime::Spec &spec,
00668                                          bool single = true );
00669 
00670   // Event Specific Methods //
00671 
00681     virtual bool addEvent( const Event::Ptr &event ) = 0;
00682 
00692     virtual bool deleteEvent( const Event::Ptr &event ) = 0;
00693 
00700     virtual bool deleteEventInstances( const Event::Ptr &event ) = 0;
00701 
00706     virtual void deleteAllEvents() = 0;
00707 
00717     static Event::List sortEvents( const Event::List &eventList,
00718                                    EventSortField sortField,
00719                                    SortDirection sortDirection );
00728     virtual Event::List events( EventSortField sortField = EventSortUnsorted,
00729                                 SortDirection sortDirection = SortDirectionAscending ) const;
00730 
00738     Event::List events( const KDateTime &dt ) const;
00739 
00753     Event::List events( const QDate &start, const QDate &end,
00754                         const KDateTime::Spec &timeSpec = KDateTime::Spec(),
00755                         bool inclusive = false ) const;
00756 
00770     Event::List events( const QDate &date,
00771                         const KDateTime::Spec &timeSpec = KDateTime::Spec(),
00772                         EventSortField sortField = EventSortUnsorted,
00773                         SortDirection sortDirection = SortDirectionAscending ) const;
00774 
00783     virtual Event::List rawEvents(
00784       EventSortField sortField = EventSortUnsorted,
00785       SortDirection sortDirection = SortDirectionAscending ) const = 0;
00786 
00796     virtual Event::List rawEventsForDate( const KDateTime &dt ) const = 0;
00797 
00811     virtual Event::List rawEvents( const QDate &start, const QDate &end,
00812                                    const KDateTime::Spec &timeSpec = KDateTime::Spec(),
00813                                    bool inclusive = false ) const = 0;
00814 
00828     virtual Event::List rawEventsForDate(
00829       const QDate &date,
00830       const KDateTime::Spec &timeSpec = KDateTime::Spec(),
00831       EventSortField sortField = EventSortUnsorted,
00832       SortDirection sortDirection = SortDirectionAscending ) const = 0;
00833 
00843     virtual Event::Ptr event( const QString &uid,
00844                               const KDateTime &recurrenceId = KDateTime() ) const = 0;
00845 
00855     virtual Event::Ptr deletedEvent( const QString &uid,
00856                                      const KDateTime &recurrenceId = KDateTime() ) const = 0;
00857 
00866     virtual Event::List deletedEvents(
00867       EventSortField sortField = EventSortUnsorted,
00868       SortDirection sortDirection = SortDirectionAscending ) const = 0;
00869 
00879     virtual Event::List eventInstances(
00880       const Incidence::Ptr &event,
00881       EventSortField sortField = EventSortUnsorted,
00882       SortDirection sortDirection = SortDirectionAscending ) const = 0;
00883 
00884   // Todo Specific Methods //
00885 
00895     virtual bool addTodo( const Todo::Ptr &todo ) = 0;
00896 
00906     virtual bool deleteTodo( const Todo::Ptr &todo ) = 0;
00907 
00913     virtual bool deleteTodoInstances( const Todo::Ptr &todo ) = 0;
00914 
00919     virtual void deleteAllTodos() = 0;
00920 
00930     static Todo::List sortTodos( const Todo::List &todoList,
00931                                  TodoSortField sortField,
00932                                  SortDirection sortDirection );
00933 
00942     virtual Todo::List todos( TodoSortField sortField = TodoSortUnsorted,
00943                               SortDirection sortDirection = SortDirectionAscending ) const;
00944 
00952     virtual Todo::List todos( const QDate &date ) const;
00953 
00967     virtual Todo::List todos( const QDate &start, const QDate &end,
00968                               const KDateTime::Spec &timespec = KDateTime::Spec(),
00969                               bool inclusive = false ) const;
00970 
00979     virtual Todo::List rawTodos(
00980       TodoSortField sortField = TodoSortUnsorted,
00981       SortDirection sortDirection = SortDirectionAscending ) const = 0;
00982 
00990     virtual Todo::List rawTodosForDate( const QDate &date ) const = 0;
00991 
01005     virtual Todo::List rawTodos( const QDate &start, const QDate &end,
01006                                  const KDateTime::Spec &timespec = KDateTime::Spec(),
01007                                  bool inclusive = false ) const = 0;
01008 
01018     virtual Todo::Ptr todo( const QString &uid,
01019                             const KDateTime &recurrenceId = KDateTime() ) const = 0;
01020 
01030     virtual Todo::Ptr deletedTodo( const QString &uid,
01031                                    const KDateTime &recurrenceId = KDateTime() ) const = 0;
01032 
01041     virtual Todo::List deletedTodos(
01042       TodoSortField sortField = TodoSortUnsorted,
01043       SortDirection sortDirection = SortDirectionAscending ) const = 0;
01044 
01054     virtual Todo::List todoInstances(
01055       const Incidence::Ptr &todo,
01056       TodoSortField sortField = TodoSortUnsorted,
01057       SortDirection sortDirection = SortDirectionAscending ) const = 0;
01058 
01059   // Journal Specific Methods //
01060 
01070     virtual bool addJournal( const Journal::Ptr &journal ) = 0;
01071 
01081     virtual bool deleteJournal( const Journal::Ptr &journal ) = 0;
01082 
01089     virtual bool deleteJournalInstances( const Journal::Ptr &journal ) = 0;
01090 
01095     virtual void deleteAllJournals() = 0;
01096 
01106     static Journal::List sortJournals( const Journal::List &journalList,
01107                                        JournalSortField sortField,
01108                                        SortDirection sortDirection );
01117     virtual Journal::List journals(
01118       JournalSortField sortField = JournalSortUnsorted,
01119       SortDirection sortDirection = SortDirectionAscending ) const;
01120 
01128     virtual Journal::List journals( const QDate &date ) const;
01129 
01138     virtual Journal::List rawJournals(
01139       JournalSortField sortField = JournalSortUnsorted,
01140       SortDirection sortDirection = SortDirectionAscending ) const = 0;
01141 
01149     virtual Journal::List rawJournalsForDate( const QDate &date ) const = 0;
01150 
01160     virtual Journal::Ptr journal( const QString &uid,
01161                                   const KDateTime &recurrenceId = KDateTime() ) const = 0;
01162 
01172     virtual Journal::Ptr deletedJournal( const QString &uid,
01173                                          const KDateTime &recurrenceId = KDateTime() ) const = 0;
01174 
01183     virtual Journal::List deletedJournals(
01184       JournalSortField sortField = JournalSortUnsorted,
01185       SortDirection sortDirection = SortDirectionAscending ) const = 0;
01186 
01196     virtual Journal::List journalInstances(
01197       const Incidence::Ptr &journal,
01198       JournalSortField sortField = JournalSortUnsorted,
01199       SortDirection sortDirection = SortDirectionAscending ) const = 0;
01200 
01201   // Relations Specific Methods //
01202 
01207     virtual void setupRelations( const Incidence::Ptr &incidence );
01208 
01214     virtual void removeRelations( const Incidence::Ptr &incidence );
01215 
01222     bool isAncestorOf( const Incidence::Ptr &ancestor,
01223                        const Incidence::Ptr &incidence ) const;
01224 
01231     Incidence::List relations( const QString &uid ) const;
01232 
01233   // Filter Specific Methods //
01234 
01244     void setFilter( CalFilter *filter );
01245 
01254     CalFilter *filter() const;
01255 
01256   // Alarm Specific Methods //
01257 
01266     virtual Alarm::List alarms( const KDateTime &from, const KDateTime &to ) const = 0;
01267 
01268   // Observer Specific Methods //
01269 
01275     class KCALCORE_EXPORT CalendarObserver //krazy:exclude=dpointer
01276     {
01277       public:
01281         virtual ~CalendarObserver();
01282 
01290         virtual void calendarModified( bool modified, Calendar *calendar );
01291 
01296         virtual void calendarIncidenceAdded( const Incidence::Ptr &incidence );
01297 
01302         virtual void calendarIncidenceChanged( const Incidence::Ptr &incidence );
01303 
01308         virtual void calendarIncidenceDeleted( const Incidence::Ptr &incidence );
01309 
01314         virtual void calendarIncidenceAdditionCanceled( const Incidence::Ptr &incidence );
01315     };
01316 
01325     void registerObserver( CalendarObserver *observer );
01326 
01335     void unregisterObserver( CalendarObserver *observer );
01336 
01337     using QObject::event;   // prevent warning about hidden virtual method
01338 
01339   protected:
01345     void incidenceUpdated( const QString &uid, const KDateTime &recurrenceId );
01346 
01352     virtual void doSetTimeSpec( const KDateTime::Spec &timeSpec );
01353 
01358     void notifyIncidenceAdded( const Incidence::Ptr &incidence );
01359 
01364     void notifyIncidenceChanged( const Incidence::Ptr &incidence );
01365 
01370     void notifyIncidenceDeleted( const Incidence::Ptr &incidence );
01371 
01376     void notifyIncidenceAdditionCanceled( const Incidence::Ptr &incidence );
01377 
01382     virtual void customPropertyUpdated();
01383 
01390     void setObserversEnabled( bool enabled );
01391 
01401     void appendAlarms( Alarm::List &alarms, const Incidence::Ptr &incidence,
01402                        const KDateTime &from, const KDateTime &to ) const;
01403 
01413     void appendRecurringAlarms( Alarm::List &alarms, const Incidence::Ptr &incidence,
01414                                 const KDateTime &from, const KDateTime &to ) const;
01415 
01420     virtual void virtual_hook( int id, void *data );
01421 
01422   private:
01423     //@cond PRIVATE
01424     class Private;
01425     Private *const d;
01426     //@endcond
01427 
01428     Q_DISABLE_COPY( Calendar )
01429 };
01430 
01431 }
01432 
01433 #endif
KCalCore Library

calendar.h

KCalCore Library

KDE-PIM Libraries
