karm Library API Documentation

karmstorage.h

00001 /*
00002  *   This file only:
00003  *     Copyright (C) 2003  Mark Bucciarelli <mark@hubcapconsutling.com>
00004  *
00005  *   This program is free software; you can redistribute it and/or modify
00006  *   it under the terms of the GNU General Public License as published by
00007  *   the Free Software Foundation; either version 2 of the License, or
00008  *   (at your option) any later version.
00009  *
00010  *   This program is distributed in the hope that it will be useful,
00011  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
00012  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00013  *   GNU General Public License for more details.
00014  *
00015  *   You should have received a copy of the GNU General Public License along
00016  *   with this program; if not, write to the
00017  *      Free Software Foundation, Inc.
00018  *      59 Temple Place - Suite 330
00019  *      Boston, MA  02111-1307  USA.
00020  *
00021  */
00022 
00023 #ifndef KARM_STORAGE_H
00024 #define KARM_STORAGE_H
00025 
00026 #include <qdict.h>
00027 #include <qptrstack.h>
00028 
00029 #include "journal.h"
00030 #include "reportcriteria.h"
00031 
00032 #include "desktoplist.h"
00033 
00034 #include <calendarresources.h>
00035 
00036 class QDateTime;
00037 class Preferences;
00038 class Task;
00039 class TaskView;
00040 class HistoryEvent;
00041 class KCal::Todo;
00042 
00065 class KarmStorage
00066 {
00067   public:
00068     /*
00069      * Return reference to storage singleton.
00070      *
00071      * The constructors are made private, so in order to create this class
00072      * you must use this function.
00073      */
00074     static KarmStorage *instance();
00075 
00076     /*
00077      * Load the list view with tasks read from iCalendar file.
00078      *
00079      * Parses iCalendar file, builds list view items in the proper
00080      * hierarchy, and loads them into the list view widget.
00081      *
00082      * If the file name passed in is the same as the last file name that was
00083      * loaded, this method does nothing.
00084      *
00085      * This method considers any of the following conditions errors:
00086      *
00087      *    @li the iCalendar file does not exist
00088      *    @li the iCalendar file is not readable
00089      *    @li the list group currently has list items
00090      *    @li an iCalendar todo has no related to attribute
00091      *    @li a todo is related to another todo which does not exist
00092      *
00093      * @param taskview     The list group used in the TaskView
00094      * @param preferences  The current KArm preferences.
00095      *
00096      * @return empty string if success, error message if error.
00097      *
00098      */
00099     QString load(TaskView* taskview, const Preferences* preferences);
00100 
00101     /* Close calendar and clear view.  Release lock if holding one. */
00102     void closeStorage(TaskView* view);
00103 
00104     /*
00105      * Save all tasks and their totals to an iCalendar file.
00106      *
00107      * All tasks must have an associated VTODO object already created in the
00108      * calendar file; that is, the task->uid() must refer to a valid VTODO in
00109      * the calender.
00110      *
00111      * @param taskview    The list group used in the TaskView
00112      */
00113     void save(TaskView* taskview);
00114 
00128     QString loadFromFlatFile(TaskView* taskview, const QString& filename);
00129 
00138     QString loadFromFlatFileCumulative(TaskView* taskview,
00139         const QString& filename);
00140 
00144     QString report( TaskView *taskview, const ReportCriteria &rc );
00145 
00146     /*
00147      * Log the change in a task's time.
00148      *
00149      * We create an iCalendar event to store each change.  The event start
00150      * date is set to the current datetime.  If time is added to the task, the
00151      * task end date is set to start time + delta.  If the time is negative,
00152      * the end date is set to the start time.
00153      *
00154      * In both cases (postive or negative delta), we create a custom iCalendar
00155      * property that stores the delta (in seconds).  This property is called
00156      * X-KDE-karm-duration.
00157      *
00158      * Note that the KArm UI allows the user to change both the session and
00159      * the total task time, and this routine does not account for all posibile
00160      * cases.  For example, it is possible for the user to do something crazy
00161      * like add 10 minutes to the session time and subtract 50 minutes from
00162      * the total time.  Although this change violates a basic law of physics,
00163      * it is allowed.
00164      *
00165      * For now, you should pass in the change to the total task time.
00166      * Eventually, the UI should be changed.
00167      *
00168      * @param task   The task the change is for.
00169      * @param delta  Change in task time, in seconds.  Can be negative.
00170      */
00171     void changeTime(const Task* task, const long deltaSeconds);
00172 
00184     void setName(const Task* /* task */ , const QString& /* oldname */) {}
00185 
00186 
00195     void startTimer(const Task* /* task */ ) {}
00196 
00206     void stopTimer(const Task* task);
00207 
00217     void addComment(const Task* task, const QString& comment);
00218 
00219 
00228     bool removeTask(Task* task);
00229 
00242     QString addTask(const Task* task, const Task* parent);
00243 
00249     bool isEmpty();
00250 
00261     bool isNewStorage(const Preferences* preferences) const;
00262 
00264     QValueList<HistoryEvent> getHistory(const QDate& from, const QDate& to);
00265 
00269     bool isReadOnly() const { return !_lock; }
00270 
00271   private:
00272     static KarmStorage                *_instance;
00273     KCal::CalendarResources           *_calendar;
00274     QString                           _icalfile;
00275     KCal::CalendarResources::Ticket   *_lock;
00276 
00277     KarmStorage();
00278     void adjustFromLegacyFileFormat(Task* task);
00279     bool parseLine(QString line, long *time, QString *name, int *level,
00280         DesktopList* desktopList);
00281     void writeTaskAsTodo
00282       (Task* task, const int level, QPtrStack< KCal::Todo >& parents);
00283 
00284     KCal::Event* baseEvent(const Task*);
00285 
00293     QString exportcsvFile( TaskView *taskview, const ReportCriteria &rc );
00294 
00298     QString exportActivityReport (
00299             TaskView* taskview, 
00300             const QDate& from, 
00301             const QDate& to, 
00302             const ReportCriteria &rc
00303             );
00304 
00305     void printTaskHistory (
00306             const Task *task, 
00307             const QMap<QString,long>& taskdaytotals, 
00308             QMap<QString,long>& daytotals, 
00309             const QDate& from,
00310             const QDate& to, 
00311             const int level, QString& s,
00312             const ReportCriteria &rc
00313             );
00314 };
00315 
00323 class HistoryEvent
00324 {
00325   public:
00327     HistoryEvent() {}
00328     HistoryEvent(QString uid, QString name, long duration,
00329         QDateTime start, QDateTime stop, QString todoUid);
00330     QString uid() {return _uid; }
00331     QString name() {return _name; }
00333     long duration() {return _duration; }
00334     QDateTime start() {return _start; }
00335     QDateTime stop() { return _stop; }
00336     QString todoUid() {return _todoUid; }
00337 
00338   private:
00339     QString _uid;
00340     QString _todoUid;
00341     QString _name;
00342     long _duration;
00343     QDateTime _start;
00344     QDateTime _stop;
00345 };
00346 
00347 #endif // KARM_STORAGE_H
KDE Logo
This file is part of the documentation for karm Library Version 3.3.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Wed Mar 23 22:42:26 2005 by doxygen 1.3.9.1 written by Dimitri van Heesch, © 1997-2003