Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdepim@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 696 insertions, 0 deletions

diff --git a/libkcal/calendarresources.h b/libkcal/calendarresources.h
new file mode 100644
index 00000000..a9e0fa80
--- /dev/null
+++ b/libkcal/calendarresources.h
@@ -0,0 +1,696 @@
+/*
+    This file is part of libkcal.
+
+    Copyright (c) 2003 Cornelius Schumacher <schumacher@kde.org>
+    Copyright (C) 2003-2004 Reinhold Kainhofer <reinhold@kainhofer.com>
+
+    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.
+*/
+/**
+   @file calendarresources.h
+   Provides a Calendar composed of several Calendar Resources.
+
+   @author Cornelius Schumacher
+   @author Reinhold Kainhofer
+ */
+#ifndef KCAL_CALENDARRESOURCES_H
+#define KCAL_CALENDARRESOURCES_H
+
+#include <qintdict.h>
+#include <qmap.h>
+
+#include "calendar.h"
+#include "resourcecalendar.h"
+
+#include "libkcal_export.h"
+
+#include <kresources/manager.h>
+
+class QWidget;
+
+/**
+   @namespace KCal
+   Namespace KCal is for global classes, objects and/or functions in libkcal.
+*/
+namespace KCal {
+
+class CalFormat;
+
+/**
+   @class CalendarResources
+
+   This class provides a Calendar which is composed of other Calendars
+   known as "Resources".
+
+   Examples of Calendar Resources are:
+     - Calendars stored as local ICS formatted files
+     - a set of incidences (one-per-file) within a local directory
+     - birthdays and anniversaries contained in an addressbook
+
+*/
+class LIBKCAL_EXPORT CalendarResources :
+      public Calendar,
+      public KRES::ManagerObserver<ResourceCalendar>
+{
+  Q_OBJECT
+  public:
+    /**
+       @class DestinationPolicy
+    */
+    class DestinationPolicy
+    {
+      public:
+        DestinationPolicy( CalendarResourceManager *manager,
+                              QWidget *parent = 0  ) :
+          mManager( manager ), mParent( parent ) {}
+
+        virtual ResourceCalendar *destination( Incidence *incidence ) = 0;
+        virtual QWidget *parent() { return mParent; }
+        virtual void setParent( QWidget *newparent ) { mParent = newparent; }
+
+      protected:
+        CalendarResourceManager *resourceManager()
+         { return mManager; }
+
+      private:
+        CalendarResourceManager *mManager;
+        QWidget *mParent;
+    };
+
+    /**
+       @class StandardDestinationPolicy
+    */
+    class StandardDestinationPolicy : public DestinationPolicy
+    {
+      public:
+        StandardDestinationPolicy( CalendarResourceManager *manager,
+                              QWidget *parent = 0  ) :
+          DestinationPolicy( manager, parent ) {}
+
+        ResourceCalendar *destination( Incidence *incidence );
+
+      private:
+        class Private;
+        Private *d;
+    };
+
+    /**
+       @class AskDestinationPolicy
+    */
+    class AskDestinationPolicy : public DestinationPolicy
+    {
+      public:
+        AskDestinationPolicy( CalendarResourceManager *manager,
+                              QWidget *parent = 0 ) :
+          DestinationPolicy( manager, parent ) {}
+
+        ResourceCalendar *destination( Incidence *incidence );
+
+      private:
+        class Private;
+        Private *d;
+    };
+
+    /**
+       @class Ticket
+    */
+    class Ticket
+    {
+        friend class CalendarResources;
+      public:
+        ResourceCalendar *resource() const
+          { return mResource; }
+
+      private:
+        Ticket( ResourceCalendar *r ) : mResource( r ) {}
+
+        ResourceCalendar *mResource;
+
+        class Private;
+        Private *d;
+    };
+
+    /**
+       Construct CalendarResource object using a Time Zone and a Family name.
+
+       @param timeZoneId is a string containing a Time Zone ID, which is
+       assumed to be valid. The Time Zone Id is used to set the time zone
+       for viewing Incidence dates.\n
+       On some systems, /usr/share/zoneinfo/zone.tab may be available for
+       reference.\n
+       @e Example: "Europe/Berlin"
+
+       @warning
+       Do Not pass an empty timeZoneId string as this may cause unintended
+       consequences when storing Incidences into the Calendar.
+
+       @param family is any QString representing a unique name.
+    */
+    CalendarResources(
+      const QString &timeZoneId,
+      const QString &family = QString::fromLatin1( "calendar" ) );
+
+    /**
+       Destructor
+    */
+    ~CalendarResources();
+
+    /**
+       Loads all Incidences from the Resources.  The Resources must be added
+       first using either readConfig(KConfig *config), which adds the system
+       Resources, or manually using resourceAdded(ResourceCalendar *resource).
+    */
+    void load();
+
+    /**
+     * Reloads all incidences from all resources.
+     * @par tz The timezone to set.
+     * @return success or failure
+     */
+    bool reload( const QString &tz );
+
+    /**
+       Clear out the current Calendar, freeing all used memory etc.
+    */
+    void close();
+
+    /**
+       Save this Calendar.
+       If the save is successfull, the Ticket is deleted.  Otherwise, the
+       caller must release the Ticket with releaseSaveTicket() to abandon
+       the save operation or call save() to try the save again.
+
+       @param ticket is a pointer to the Ticket object.
+       @param incidence is a pointer to the Incidence object.
+       If incidence is null, save the entire Calendar (all Resources)
+       else only the specified Incidence is saved.
+
+       @return true if the save was successful; false otherwise.
+    */
+    virtual bool save( Ticket *ticket, Incidence *incidence = 0 );
+
+    /**
+       Sync changes in memory to persistant storage.
+    */
+    void save();
+
+    /**
+       Determine if the Calendar is currently being saved.
+
+       @return true if the Calendar is currently being saved; false otherwise.
+    */
+    bool isSaving();
+
+    /**
+       Get the CalendarResourceManager used by this calendar.
+
+       @return a pointer to the CalendarResourceManage.
+    */
+    CalendarResourceManager *resourceManager() const
+      { return mManager; }
+
+    /**
+       Get the Resource associated with a specified Incidence.
+
+       @param incidence is a pointer to an Incidence whose Resource
+       is to be located.
+
+       @return a pointer to the Resource containing the Incidence.
+    */
+    ResourceCalendar *resource( Incidence *incidence );
+
+    /**
+       Read the Resources settings from a config file.
+
+       @param config The KConfig object which points to the config file.
+       If no object is given (null pointer) the standard config file is used.
+
+       @note Call this method <em>before</em> load().
+    */
+    void readConfig( KConfig *config = 0 );
+
+    /**
+       Set the destination policy such that Incidences are always added
+       to the standard Resource.
+    */
+    void setStandardDestinationPolicy();
+
+    /**
+       Set the destination policy such that Incidences are added to a
+       Resource which is queried.
+    */
+    void setAskDestinationPolicy();
+    
+    /** 
+       Returns the current parent for new dialogs. This is a bad hack, but we need
+       to properly set the parent for the resource selection dialog. Otherwise
+       the dialog will not be modal to the editor dialog in korganizer and 
+       the user can still work in the editor dialog (and thus crash korganizer).
+       Afterwards we need to reset it (to avoid pointers to widgets that are 
+       already deleted) so we also need the accessor
+    */
+    QWidget *dialogParentWidget();
+    /** 
+       Set the widget parent for new dialogs. This is a bad hack, but we need
+       to properly set the parent for the resource selection dialog. Otherwise
+       the dialog will not be modal to the editor dialog in korganizer and 
+       the user can still work in the editor dialog (and thus crash korganizer).
+    */
+    void setDialogParentWidget( QWidget *parent );
+
+    /**
+       Request ticket for saving the Calendar.  If a ticket is returned the
+       Calendar is locked for write access until save() or releaseSaveTicket()
+       is called.
+
+       @param resource is a pointer to the ResourceCalendar object.
+
+       @return a pointer to a Ticket object indicating that the Calendar
+       is locked for write access; otherwise a null pointer.
+    */
+    Ticket *requestSaveTicket( ResourceCalendar *resource );
+
+    /**
+       Release the save Ticket. The Calendar is unlocked without saving.
+
+       @param ticket is a pointer to a Ticket object.
+    */
+    virtual void releaseSaveTicket( Ticket *ticket );
+
+    /**
+       Add a Resource to the Calendar.
+       This method must be public, because in-process added Resources
+       do not emit the corresponding signal, so this methodd has to be
+       called manually!
+
+       @param resource is a pointer to the ResourceCalendar to add.
+    */
+    void resourceAdded( ResourceCalendar *resource );
+
+// Incidence Specific Methods //
+
+    /**
+       Insert an Incidence into the Calendar.
+
+       @param incidence is a pointer to the Incidence to insert.
+
+       @return true if the Incidence was successfully inserted; false otherwise.
+    */
+    bool addIncidence( Incidence *incidence );
+
+    /**
+       Insert an Incidence into a Calendar Resource.
+
+       @param incidence is a pointer to the Incidence to insert.
+       @param resource is a pointer to the ResourceCalendar to be added to.
+
+       @return true if the Incidence was successfully inserted; false otherwise.
+    */
+    bool addIncidence( Incidence *incidence, ResourceCalendar *resource );
+
+    /**
+       Flag that a change to a Calendar Incidence is starting.
+
+       @param incidence is a pointer to the Incidence that will be changing.
+    */
+    bool beginChange( Incidence *incidence );
+
+    /**
+       Flag that a change to a Calendar Incidence has completed.
+
+       @param incidence is a pointer to the Incidence that was changed.
+    */
+    bool endChange( Incidence *incidence );
+
+// Event Specific Methods //
+
+    /**
+       Insert an Event into the Calendar.
+
+       @param event is a pointer to the Event to insert.
+
+       @return true if the Event was successfully inserted; false otherwise.
+
+       @note In most cases use
+       addIncidence( Incidence *incidence ) instead.
+    */
+    bool addEvent( Event *event );
+
+    /**
+       Insert an Event into a Calendar Resource.
+
+       @param event is a pointer to the Event to insert.
+       @param resource is a pointer to the ResourceCalendar to be added to.
+
+       @return true if the Event was successfully inserted; false otherwise.
+
+       @note In most cases use
+       addIncidence( Incidence *incidence, ResourceCalendar *resource ) instead.
+    */
+    bool addEvent( Event *event, ResourceCalendar *resource );
+
+    /**
+       Remove an Event from the Calendar.
+
+       @param event is a pointer to the Event to remove.
+
+       @return true if the Event was successfully removed; false otherwise.
+
+       @note In most cases use
+       deleteIncidence( Incidence *incidence) instead.
+    */
+    bool deleteEvent( Event *event );
+
+    /**
+       Return a sorted, unfiltered list of all Events.
+
+       @param sortField specifies the EventSortField.
+       @param sortDirection specifies the SortDirection.
+
+       @return the list of all unfiltered Events sorted as specified.
+    */
+    Event::List rawEvents(
+      EventSortField sortField = EventSortUnsorted,
+      SortDirection sortDirection = SortDirectionAscending );
+
+    /**
+       Return an unfiltered list of all Events which occur on the given
+       timestamp.
+
+       @param qdt request unfiltered Event list for this QDateTime only.
+
+       @return the list of unfiltered Events occurring on the specified
+       timestamp.
+    */
+    Event::List rawEventsForDate( const QDateTime &qdt );
+
+    /**
+       Return an unfiltered list of all Events occurring within a date range.
+
+       @param start is the starting date.
+       @param end is the ending date.
+       @param inclusive if true only Events which are completely included
+       within the date range are returned.
+
+       @return the list of unfiltered Events occurring within the specified
+       date range.
+    */
+    Event::List rawEvents( const QDate &start, const QDate &end,
+                           bool inclusive = false );
+
+    /**
+       Return a sorted, unfiltered list of all Events which occur on the given
+       date.  The Events are sorted according to @a sortField and
+       @a sortDirection.
+
+       @param date request unfiltered Event list for this QDate only.
+       @param sortField specifies the EventSortField.
+       @param sortDirection specifies the SortDirection.
+
+       @return the list of sorted, unfiltered Events occurring on @a date.
+    */
+    Event::List rawEventsForDate(
+      const QDate &date,
+      EventSortField sortField = EventSortUnsorted,
+      SortDirection sortDirection = SortDirectionAscending );
+
+    /**
+       Returns the Event associated with the given unique identifier.
+
+       @param uid is a unique identifier string.
+
+       @return a pointer to the Event.
+       A null pointer is returned if no such Event exists.
+    */
+    Event *event( const QString &uid );
+
+// Todo Specific Methods //
+
+    /**
+       Insert a Todo into a Calendar Resource.
+
+       @param todo is a pointer to the Todo to insert.
+
+       @return true if the Todo was successfully inserted; false otherwise.
+
+       @note In most cases use
+       addIncidence( Incidence *incidence ) instead.
+    */
+    bool addTodo( Todo *todo );
+
+    /**
+       Insert an Todo into a Calendar Resource.
+
+       @param todo is a pointer to the Todo to insert.
+       @param resource is a pointer to the ResourceCalendar to be added to.
+
+       @return true if the Todo was successfully inserted; false otherwise.
+
+       @note In most cases use
+       addIncidence( Incidence *incidence, ResourceCalendar *resource ) instead.
+    */
+    bool addTodo( Todo *todo, ResourceCalendar *resource );
+
+    /**
+       Remove an Todo from the Calendar.
+
+       @param todo is a pointer to the Todo to remove.
+
+       @return true if the Todo was successfully removed; false otherwise.
+
+       @note In most cases use
+       deleteIncidence( Incidence *incidence ) instead.
+    */
+    bool deleteTodo( Todo *todo );
+
+    /**
+       Return a sorted, unfiltered list of all Todos for this Calendar.
+
+       @param sortField specifies the TodoSortField.
+       @param sortDirection specifies the SortDirection.
+
+       @return the list of all unfiltered Todos sorted as specified.
+    */
+    Todo::List rawTodos( TodoSortField sortField = TodoSortUnsorted,
+                         SortDirection sortDirection = SortDirectionAscending );
+
+    /**
+       Return an unfiltered list of all Todos which are due on the specified
+       date.
+
+       @param date request unfiltered Todos due on this QDate.
+
+       @return the list of unfiltered Todos due on the specified date.
+    */
+    Todo::List rawTodosForDate( const QDate &date );
+
+    /**
+       Returns the Todo associated with the given unique identifier.
+
+       @param uid is a unique identifier string.
+
+       @return a pointer to the Todo.
+       A null pointer is returned if no such Todo exists.
+    */
+    Todo *todo( const QString &uid );
+
+// Journal Specific Methods //
+
+    /**
+       Insert a Journal into the Calendar.
+
+       @param journal is a pointer to the Journal to insert.
+
+       @return true if the Journal was successfully inserted; false otherwise.
+
+       @note In most cases use
+       addIncidence( Incidence *incidence ) instead.
+    */
+    bool addJournal( Journal *journal );
+
+    /**
+       Insert a Journal into a Calendar Resource.
+
+       @param journal is a pointer to the Journal to insert.
+       @param resource is a pointer to the ResourceCalendar to be added to.
+
+       @return true if the Journal was successfully inserted; false otherwise.
+
+       @note In most cases use
+       addIncidence( Incidence *incidence, ResourceCalendar *resource ) instead.
+    */
+    bool addJournal( Journal *journal, ResourceCalendar *resource );
+
+    /**
+       Remove a Journal from the Calendar.
+
+       @param journal is a pointer to the Journal to remove.
+
+       @return true if the Journal was successfully removed; false otherwise.
+
+       @note In most cases use
+       deleteIncidence( Incidence *incidence ) instead.
+    */
+    bool deleteJournal( Journal *journal );
+
+    /**
+       Return a sorted, unfiltered list of all Journals for this Calendar.
+
+       @param sortField specifies the JournalSortField.
+       @param sortDirection specifies the SortDirection.
+
+       @return the list of all unfiltered Journals sorted as specified.
+    */
+    Journal::List rawJournals(
+      JournalSortField sortField = JournalSortUnsorted,
+      SortDirection sortDirection = SortDirectionAscending );
+
+    /**
+       Return an unfiltered list of all Journals for on the specifed date.
+
+       @param date request unfiltered Journals for this QDate only.
+
+       @return the list of unfiltered Journals for the specified date.
+    */
+    Journal::List rawJournalsForDate( const QDate &date );
+
+    /**
+       Returns the Journal associated with the given unique identifier.
+
+       @param uid is a unique identifier string.
+
+       @return a pointer to the Journal.
+       A null pointer is returned if no such Journal exists.
+    */
+    Journal *journal( const QString &uid );
+
+// Alarm Specific Methods //
+
+    /**
+       Return a list of Alarms within a time range for this Calendar.
+
+       @param from is the starting timestamp.
+       @param to is the ending timestamp.
+
+       @return the list of Alarms for the for the specified time range.
+    */
+    Alarm::List alarms( const QDateTime &from, const QDateTime &to );
+
+    /**
+       Return a list of Alarms that occur before the specified timestamp.
+
+       @param to is the ending timestamp.
+
+       @return the list of Alarms occurring before the specified QDateTime.
+    */
+    Alarm::List alarmsTo( const QDateTime &to );
+
+    /**
+     * Set the viewing time zone, which requires that all resources are saved,
+     * and then reloaded such that the event times are re-interpreted in the new
+     * timezone. Note that the absolute times of events do not change with this.
+     * If you want to change the times of the contents of the resources, use
+     * setTimeZoneId
+     */
+    void setTimeZoneIdViewOnly( const QString& tz );
+
+  signals:
+    /**
+       Signal that the Resource has been modified.
+    */
+    void signalResourceModified( ResourceCalendar *resource );
+
+    /**
+       Signal that an Incidence has been inserted to the Resource.
+    */
+    void signalResourceAdded( ResourceCalendar *resource );
+
+    /**
+       Signal that an Incidence has been removed from the Resource.
+    */
+    void signalResourceDeleted( ResourceCalendar *resource );
+
+    /**
+       Signal an error message.
+    */
+    void signalErrorMessage( const QString &err );
+
+  protected:
+    void connectResource( ResourceCalendar *resource );
+    void resourceModified( ResourceCalendar *resource );
+    void resourceDeleted( ResourceCalendar *resource );
+
+    /**
+       Let CalendarResource subclasses set the Time Zone ID.
+
+       First parameter is a string containing a Time Zone ID, which is
+       assumed to be valid. On some systems, /usr/share/zoneinfo/zone.tab
+       may be available for reference.\n
+       @e Example: "Europe/Berlin"
+
+       @warning
+       Do Not pass an empty timeZoneId string as this may cause unintended
+       consequences when storing Incidences into the Calendar.
+    */
+    virtual void doSetTimeZoneId( const QString &timeZoneId );
+
+    /**
+       Increment the number of times this Resource has been changed by 1.
+
+       @param resource is a pointer to the ResourceCalendar to be counted.
+
+       @return the new number of times this Resource has been changed.
+    */
+    int incrementChangeCount( ResourceCalendar *resource );
+
+    /**
+       Decrement the number of times this Resource has been changed by 1.
+
+       @param resource is a pointer to the ResourceCalendar to be counted.
+
+       @return the new number of times this Resource has been changed.
+    */
+    int decrementChangeCount( ResourceCalendar *resource );
+
+  protected slots:
+    void slotLoadError( ResourceCalendar *resource, const QString &err );
+    void slotSaveError( ResourceCalendar *resource, const QString &err );
+
+  private:
+    /**
+       Initialize the Resource object with starting values.
+    */
+    void init( const QString &family );
+
+    bool mOpen;
+
+    KRES::Manager<ResourceCalendar>* mManager;
+    QMap <Incidence*, ResourceCalendar*> mResourceMap;
+
+    DestinationPolicy *mDestinationPolicy;
+    StandardDestinationPolicy *mStandardPolicy;
+    AskDestinationPolicy *mAskPolicy;
+
+    QMap<ResourceCalendar *, Ticket *> mTickets;
+    QMap<ResourceCalendar *, int> mChangeCounts;
+
+    class Private;
+    Private *d;
+};
+
+}
+
+#endif