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 <qdatetime.h>
00028 
00029 #include "incidence.h"
00030 #include "calendarlocal.h"
00031 #include "journal.h"
00032 
00033 #include "taskview.h"
00034 
00035 class Preferences;
00036 class Task;
00037 class TaskView;
00038 class HistoryEvent;
00039 
00062 class KarmStorage
00063 {
00064   public:
00065     /*
00066      * Return reference to storage singleton.
00067      *
00068      * The constructors are made private, so in order to create this class
00069      * you must use this function.
00070      */
00071     static KarmStorage *instance();
00072 
00073     /*
00074      * Load the list view with tasks read from iCalendar file.
00075      *
00076      * Parses iCalendar file, builds list view items in the proper
00077      * hierarchy, and loads them into the list view widget.
00078      *
00079      * If the file name passed in is the same as the last file name that was
00080      * loaded, this method does nothing.
00081      *
00082      * This method considers any of the following conditions errors:
00083      *
00084      *    @li the iCalendar file does not exist
00085      *    @li the iCalendar file is not readable
00086      *    @li the list group currently has list items
00087      *    @li an iCalendar todo has no related to attribute
00088      *    @li a todo is related to another todo which does not exist
00089      *
00090      * @param taskview     The list group used in the TaskView
00091      * @param preferences  The current KArm preferences.
00092      *
00093      * @return empty string if success, error message if error.
00094      *
00095      */
00096     QString load(TaskView* taskview, const Preferences* preferences);
00097 
00098     /*
00099      * Save all tasks and their totals to an iCalendar file.
00100      *
00101      * All tasks must have an associated VTODO object already created in the
00102      * calendar file; that is, the task->uid() must refer to a valid VTODO in
00103      * the calender.
00104      *
00105      * @param taskview    The list group used in the TaskView
00106      */
00107     void save(TaskView* taskview);
00108 
00122     QString loadFromFlatFile(TaskView* taskview, const QString& filename);
00123 
00132     QString loadFromFlatFileCumulative(TaskView* taskview,
00133         const QString& filename);
00134 
00135     /*
00136      * Log the change in a task's time.
00137      *
00138      * We create an iCalendar event to store each change.  The event start
00139      * date is set to the current datetime.  If time is added to the task, the
00140      * task end date is set to start time + delta.  If the time is negative,
00141      * the end date is set to the start time.
00142      *
00143      * In both cases (postive or negative delta), we create a custom iCalendar
00144      * property that stores the delta (in seconds).  This property is called
00145      * X-KDE-karm-duration.
00146      *
00147      * Note that the KArm UI allows the user to change both the session and
00148      * the total task time, and this routine does not account for all posibile
00149      * cases.  For example, it is possible for the user to do something crazy
00150      * like add 10 minutes to the session time and subtract 50 minutes from
00151      * the total time.  Although this change violates a basic law of physics,
00152      * it is allowed.
00153      *
00154      * For now, you should pass in the change to the total task time.
00155      * Eventually, the UI should be changed.
00156      *
00157      * @param task   The task the change is for.
00158      * @param delta  Change in task time, in seconds.  Can be negative.
00159      */
00160     void changeTime(const Task* task, const long deltaSeconds);
00161 
00173     void setName(const Task* /* task */ , const QString& /* oldname */) {}
00174 
00175 
00184     void startTimer(const Task* /* task */ ) {}
00185 
00195     void stopTimer(const Task* task);
00196 
00206     void addComment(const Task* task, const QString& comment);
00207 
00208 
00217     bool removeTask(Task* task);
00218 
00231     QString addTask(const Task* task, const Task* parent);
00232 
00238     bool isEmpty();
00239 
00250     bool isNewStorage(const Preferences* preferences) const;
00251 
00253     QValueList<HistoryEvent> getHistory(const QDate& from, const QDate& to);
00254 
00255   private:
00256     static KarmStorage *_instance;
00257     KCal::CalendarLocal _calendar;
00258     QString _icalfile;
00259 
00260     KarmStorage();
00261     void adjustFromLegacyFileFormat(Task* task);
00262     bool parseLine(QString line, long *time, QString *name, int *level,
00263         DesktopList* desktopList);
00264     void writeTaskAsTodo(Task* task, const int level,
00265         QPtrStack< KCal::Todo >& parents);
00266 
00267     KCal::Event* baseEvent(const Task*);
00268 
00269 };
00270 
00278 class HistoryEvent
00279 {
00280   public:
00282     HistoryEvent() {}
00283     HistoryEvent(QString uid, QString name, long duration,
00284         QDateTime start, QDateTime stop, QString todoUid);
00285     QString uid() {return _uid; }
00286     QString name() {return _name; }
00288     long duration() {return _duration; }
00289     QDateTime start() {return _start; }
00290     QDateTime stop() { return _stop; }
00291     QString todoUid() {return _todoUid; }
00292 
00293   private:
00294     QString _uid;
00295     QString _todoUid;
00296     QString _name;
00297     long _duration;
00298     QDateTime _start;
00299     QDateTime _stop;
00300 };
00301 
00302 #endif // KARM_STORAGE_H
KDE Logo
This file is part of the documentation for karm Library Version 3.2.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Sat May 1 11:37:52 2004 by doxygen 1.2.15 written by Dimitri van Heesch, © 1997-2003