summaryrefslogtreecommitdiffstats
path: root/libkcal/resourcecalendar.h
diff options
context:
space:
mode:
Diffstat (limited to 'libkcal/resourcecalendar.h')
-rw-r--r--libkcal/resourcecalendar.h413
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