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, 413 insertions, 0 deletions

diff --git a/libkcal/resourcecalendar.h b/libkcal/resourcecalendar.h
new file mode 100644
index 000000000..4cd4d91e7
--- /dev/null
+++ b/libkcal/resourcecalendar.h
@@ -0,0 +1,413 @@
+/*
+    This file is part of libkcal.
+
+    Copyright (c) 1998 Preston Brown <pbrown@kde.org>
+    Copyright (c) 2001,2003 Cornelius Schumacher <schumacher@kde.org>
+    Copyright (c) 2002 Jan-Pascal van Best <janpascal@vanbest.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.
+*/
+
+#ifndef KCAL_RESOURCECALENDAR_H
+#define KCAL_RESOURCECALENDAR_H
+
+#include <qstring.h>
+#include <qdatetime.h>
+#include <qptrlist.h>
+
+#include <kconfig.h>
+
+#include "alarm.h"
+#include "todo.h"
+#include "event.h"
+#include "journal.h"
+#include "calendar.h"
+
+#include <kresources/resource.h>
+#include <kresources/manager.h>
+#include <kabc/lock.h>
+#include <kdepimmacros.h>
+
+namespace KCal {
+
+class CalFormat;
+
+/**
+  This class provides the interfaces for a calendar resource. It makes use of
+  the kresources framework.
+
+  \warning This code is still under heavy development. Don't expect source or
+  binary compatibility in future versions.
+*/
+class LIBKCAL_EXPORT ResourceCalendar : public KRES::Resource
+{
+    Q_OBJECT
+  public:
+    ResourceCalendar( const KConfig * );
+    virtual ~ResourceCalendar();
+
+    void setResolveConflict( bool b);
+
+    virtual void writeConfig( KConfig* config );
+
+    /**
+      Return rich text with info about the resource. Adds standard info and
+      then calls addInfoText() to add info about concrete resources.
+    */
+    virtual QString infoText() const;
+
+    /**
+      Load resource data. After calling this function all data is accessible by
+      calling the incidence/event/todo/etc. accessor functions.
+
+      Whether data is actually loaded within this function or the loading is delayed
+      until it is accessed by another function depends on the implementation of
+      the resource.
+
+      If loading the data takes significant time, the resource should return
+      cached values if available, and return the results via the resourceChanged
+      signal. When the resource has finished loading, the resourceLoaded() signal
+      is emitted.
+
+      Calling this function multiple times should have the same effect as
+      calling it once, given that the data isn't changed between calls.
+
+      This function calls doLoad() which has to be reimplented by the resource
+      to do the actual loading.
+    */
+    bool load();
+
+    /**
+      Save resource data. After calling this function it is safe to close the
+      resource without losing data.
+
+      Whether data is actually saved within this function or saving is delayed
+      depends on the implementation of the resource.
+
+      If saving the data takes significant time, the resource should return from
+      the function, do the saving in the background and notify the end of the
+      save by emitting the signal resourceSaved().
+
+      This function calls doSave() which has to be reimplented by the resource
+      to do the actual saving.
+
+      @param incidence if given as 0, doSave() is called to save all incidences,
+             else doSave(incidence) is called to save only the given one
+    */
+    bool save( Incidence *incidence = 0 );
+
+    /**
+      Return true if a save operation is still in progress, otherwise return
+      false.
+    */
+    virtual bool isSaving() { return false; }
+
+    /**
+      Return object for locking the resource.
+    */
+    virtual KABC::Lock *lock() = 0;
+
+    /**
+      Add incidence to resource.
+    */
+    virtual bool addIncidence( Incidence * );
+
+    /**
+      Delete incidence from resource.
+    */
+    virtual bool deleteIncidence( Incidence * );
+
+    /**
+      Return incidence with given unique id. If there is no incidence with that
+      uid, return 0.
+    */
+    Incidence *incidence( const QString &uid );
+
+    /**
+      Add event to resource.
+    */
+    virtual bool addEvent( Event *event ) = 0;
+
+    /**
+      Delete event from this resource.
+    */
+    virtual bool deleteEvent( Event * ) = 0;
+
+    /**
+      Retrieves an event on the basis of the unique string ID.
+    */
+    virtual Event *event( const QString &uid ) = 0;
+
+    /**
+      Return unfiltered list of all events in calendar. Use with care,
+      this can be a bad idea for server-based calendars.
+    */
+    virtual Event::List rawEvents( EventSortField sortField = EventSortUnsorted, SortDirection sortDirection = SortDirectionAscending ) = 0;
+
+    /**
+      Builds and then returns a list of all events that match the
+      date specified. Useful for dayView, etc. etc.
+    */
+    virtual Event::List rawEventsForDate( const QDate &date, EventSortField sortField = EventSortUnsorted, SortDirection sortDirection = SortDirectionAscending ) = 0;
+
+    /**
+      Get unfiltered events for date \a qdt.
+    */
+    virtual Event::List rawEventsForDate( const QDateTime &qdt ) = 0;
+
+    /**
+      Get unfiltered events in a range of dates. If inclusive is set to true,
+      only events which are completely included in the range are returned.
+    */
+    virtual Event::List rawEvents( const QDate &start, const QDate &end,
+                                   bool inclusive = false ) = 0;
+
+    /**
+      Sets a particular value of the resource's configuration. The possible
+      keys are resource specific.
+
+      This method is provided to make it possible
+      to set resource-type specific settings without actually linking to
+      the resource's library. Its use is discouraged, but in
+      some situations the only possibility to avoid unwanted compiling and
+      linking dependencies. E.g. if you don't want to link to the remote
+      resource, but need to create a remote resource at the URL given in
+      yourURL, you can use code like the following:
+        KCal::ResourceCalendar *res = manager->createResource( "remote" );
+        if ( res ) {
+          res->setTimeZoneId( timezone );
+          res->setResourceName( i18n("Test resource") );
+          res->setValue( "DownloadURL", yourURL );
+          manager->add( res );
+        }
+    */
+    virtual bool setValue( const QString &key, const QString &value );
+
+  signals:
+    /**
+      This signal is emitted when the data in the resource has changed. The
+      resource has to make sure that this signal is emitted whenever any
+      pointers to incidences which the resource has previously given to the
+      calling code, become invalid.
+    */
+    void resourceChanged( ResourceCalendar * );
+
+    /**
+      This signal is emitted when loading data into the resource has been
+      finished.
+    */
+    void resourceLoaded( ResourceCalendar * );
+    /**
+      This signal is emitted when saving the data of the resource has been
+      finished.
+    */
+    void resourceSaved( ResourceCalendar * );
+
+    /**
+      This signal is emitted when an error occurs during loading.
+    */
+    void resourceLoadError( ResourceCalendar *, const QString &error );
+    /**
+      This signal is emitted when an error occurs during saving.
+    */
+    void resourceSaveError( ResourceCalendar *, const QString &error );
+
+    /**
+     This signal is emitted when a subresource is added.
+    */
+    void signalSubresourceAdded( ResourceCalendar *, const QString& type,
+                                 const QString& subresource, const QString& label );
+
+    /**
+     This signal is emitted when a subresource is removed.
+    */
+    void signalSubresourceRemoved( ResourceCalendar *, const QString &,
+                                   const QString & );
+
+  public:
+    /**
+      Add a todo to the todolist.
+    */
+    virtual bool addTodo( Todo *todo ) = 0;
+    /**
+      Remove a todo from the todolist.
+    */
+    virtual bool deleteTodo( Todo * ) = 0;
+    /**
+      Searches todolist for an event with this unique id.
+
+      @return pointer to todo or 0 if todo wasn't found
+    */
+    virtual Todo *todo( const QString &uid ) = 0;
+    /**
+      Return list of all todos.
+    */
+    virtual Todo::List rawTodos( TodoSortField sortField = TodoSortUnsorted, SortDirection sortDirection = SortDirectionAscending ) = 0;
+    /**
+      Returns list of todos due on the specified date.
+    */
+    virtual Todo::List rawTodosForDate( const QDate &date ) = 0;
+
+
+    /**
+      Add a Journal entry to the resource.
+    */
+    virtual bool addJournal( Journal * ) = 0;
+
+    /**
+      Remove a Journal entry from calendar.
+    */
+    virtual bool deleteJournal( Journal * ) = 0;
+
+    /**
+      Return Journal with given unique id.
+    */
+    virtual Journal *journal( const QString &uid ) = 0;
+    /**
+      Return list of all journals.
+    */
+    virtual Journal::List rawJournals( JournalSortField sortField = JournalSortUnsorted, SortDirection sortDirection = SortDirectionAscending ) = 0;
+    /**
+      Returns list of journals for the given date.
+    */
+    virtual Journal::List rawJournalsForDate( const QDate &date ) = 0;
+
+    /**
+      Return all alarms which occur in the given time interval.
+    */
+    virtual Alarm::List alarms( const QDateTime &from,
+                                const QDateTime &to ) = 0;
+
+    /**
+      Return all alarms which occur before given date.
+    */
+    virtual Alarm::List alarmsTo( const QDateTime &to ) = 0;
+
+
+    /** Returns a list of all incideces */
+    Incidence::List rawIncidences();
+
+    /**
+      Set time zone id used by this resource, e.g. "Europe/Berlin".
+    */
+    virtual void setTimeZoneId( const QString &timeZoneId ) = 0;
+
+    /**
+      If this resource has subresources, return a QStringList of them.
+      In most cases, resources do not have subresources, so this is
+      by default just empty.
+    */
+    virtual QStringList subresources() const { return QStringList(); }
+
+    /**
+      Is this subresource capable of having subresources or not?
+    */
+    virtual bool canHaveSubresources() const { return false; }
+
+    /**
+      Is this subresource active or not?
+    */
+    virtual bool subresourceActive( const QString& ) const { return true; }
+
+    /**
+      What is the label for this subresource?
+     */
+    virtual const QString labelForSubresource( const QString& resource ) const
+    {
+       // the resource identifier is a sane fallback
+       return resource;
+    };
+
+    /**
+      Get the identifier of the subresource associated with a specified
+      incidence.
+
+      @return the identifier of the subresource or an empty string.
+    */
+    virtual QString subresourceIdentifier( Incidence *incidence )
+    { Q_UNUSED( incidence ); return QString(); }
+
+
+
+    /**
+     * Remove a subresource with the id @param resource
+     */
+    virtual bool removeSubresource( const QString& resource );
+
+    /**
+     * Add a subresource with the name @param resource and the parent
+     * id @param parent.
+     */
+    virtual bool addSubresource( const QString& resource, const QString& parent );
+
+    /**
+     * Returns the type of the subresource: "event", "todo" or "journal",
+     * QString() if unknown/mixed.
+     */
+    virtual QString subresourceType( const QString &resource );
+
+  public slots:
+    /**
+      (De-)activate a subresource.
+    */
+    virtual void setSubresourceActive( const QString &, bool active );
+
+  protected:
+
+    bool mResolveConflict;
+    /**
+      Do the actual loading of the resource data. Called by load().
+    */
+    virtual bool doLoad() = 0;
+    /**
+      Do the actual saving of the resource data. Called by save().
+    */
+    virtual bool doSave() = 0;
+
+    /**
+      Do the actual saving of the resource data. Called by save().
+      Save one Incidence. The default implementation calls doSave() to save everything
+    */
+    virtual bool doSave( Incidence * );
+
+    /**
+      Add info text for concrete resources. Called by infoText().
+    */
+    virtual void addInfoText( QString & ) const {};
+
+    /**
+      A resource should call this function if a load error happens.
+    */
+    void loadError( const QString &errorMessage = QString::null );
+    /**
+      A resource should call this function if a save error happens.
+    */
+    void saveError( const QString &errorMessage = QString::null );
+
+  private:
+    bool mReceivedLoadError;
+    bool mReceivedSaveError;
+
+    class Private;
+    Private *d;
+};
+
+typedef KRES::Manager<ResourceCalendar> CalendarResourceManager;
+
+}
+
+#endif