karm

KarmStorage Class Reference

#include <karmstorage.h>

List of all members.


Detailed Description

Singleton to store/retrieve KArm data to/from persistent storage.Logic that gets and stores KArm data to disk.

The storage is an iCalendar file. Also included are methods to import KArm data from the two legacy file formats.

All logic that deals with getting and saving data should go here. The storage logic has changed at least twice already in KArm's history, and chances are good it will change again (for example, allowing KOrganizer and KArm to access the same iCalendar file simultaneously).

Prior to KDE 3.2, KArm just stored totals for each task--a session total and a task total. The session total was reset to zero each time KArm started up or after the user reset the session times to zero. With the release of KDE 3.2, KArm now stores these task totals as well as logging the history of each start/stop event; that is, every time you start a timer and then stop a timer on a task, KArm records this as an iCalendar event.

Author:
Mark Bucciarelli <mark@hubcapconsulting.com>

Definition at line 68 of file karmstorage.h.


Public Member Functions

QString load (TaskView *taskview, const Preferences *preferences, QString fileName="")
QString icalfile ()
QString buildTaskView (KCal::ResourceCalendar *rc, TaskView *view)
void closeStorage (TaskView *view)
QString save (TaskView *taskview)
QString loadFromFlatFile (TaskView *taskview, const QString &filename)
QString loadFromFlatFileCumulative (TaskView *taskview, const QString &filename)
QString report (TaskView *taskview, const ReportCriteria &rc)
void changeTime (const Task *task, const long deltaSeconds)
bool bookTime (const Task *task, const QDateTime &startDateTime, long durationInSeconds)
void setName (const Task *task, const QString &oldname)
void startTimer (const Task *task)
void stopTimer (const Task *task, QDateTime when=QDateTime::currentDateTime())
void addComment (const Task *task, const QString &comment)
bool removeTask (Task *task)
QString addTask (const Task *task, const Task *parent)
bool isEmpty ()
bool isNewStorage (const Preferences *preferences) const
QValueList< HistoryEventgetHistory (const QDate &from, const QDate &to)

Static Public Member Functions

static KarmStorageinstance ()

Member Function Documentation

QString KarmStorage::loadFromFlatFile ( TaskView taskview,
const QString &  filename 
)

Read tasks and their total times from a text file (legacy storage).

This reads from one of the two legacy file formats. In this version, the parent task times do not include the sum of all their children's times.

The format of the file is zero or more lines of: 1 task id (a number) time in minutes string task name [string] desktops, in which to count. e.g. "1,2,5" (optional)

Definition at line 384 of file karmstorage.cpp.

QString KarmStorage::loadFromFlatFileCumulative ( TaskView taskview,
const QString &  filename 
)

Reads tasks and their total times from text file (legacy).

This is the older legacy format, where the task totals included the children totals.

See also:
loadFromFlatFile

Definition at line 467 of file karmstorage.cpp.

QString KarmStorage::report ( TaskView taskview,
const ReportCriteria rc 
)

Output a report based on contents of ReportCriteria.

Definition at line 873 of file karmstorage.cpp.

void KarmStorage::changeTime ( const Task task,
const long  deltaSeconds 
)

Log the change in a task's time.

We create an iCalendar event to store each change. The event start date is set to the current datetime. If time is added to the task, the task end date is set to start time + delta. If the time is negative, the end date is set to the start time.

In both cases (postive or negative delta), we create a custom iCalendar property that stores the delta (in seconds). This property is called X-KDE-karm-duration.

Note that the KArm UI allows the user to change both the session and the total task time, and this routine does not account for all posibile cases. For example, it is possible for the user to do something crazy like add 10 minutes to the session time and subtract 50 minutes from the total time. Although this change violates a basic law of physics, it is allowed.

For now, you should pass in the change to the total task time. Eventually, the UI should be changed.

Parameters:
task The task the change is for.
delta Change in task time, in seconds. Can be negative.

Definition at line 1079 of file karmstorage.cpp.

bool KarmStorage::bookTime ( const Task task,
const QDateTime &  startDateTime,
long  durationInSeconds 
)

Book time to a task.

Creates an iCalendar event and adds it to the calendar. Does not write calender to disk, just adds event to calendar in memory. However, the resource framework does try to get a lock on the file. After a succesful lock, the calendar marks this incidence as modified and then releases the lock.

Parameters:
task Task
startDateTime Date and time the booking starts.
durationInSeconds Duration of time to book, in seconds.
Returns:
true if event was added, false if not (if, for example, the attempted file lock failed).

Definition at line 1059 of file karmstorage.cpp.

void KarmStorage::setName ( const Task task,
const QString &  oldname 
) [inline]

Log a change to a task name.

For iCalendar storage, there is no need to log an Event for this event, since unique id's are used to link Events to Todos. No matter how many times you change a task's name, the uid stays the same.

Parameters:
task The task
oldname The old name of the task. The new name is in the task object already.

Definition at line 220 of file karmstorage.h.

void KarmStorage::startTimer ( const Task task  )  [inline]

Log the event that a timer has started for a task.

For the iCalendar storage, there is no need to log anything for this event. We log an event when the timer is stopped.

Parameters:
task The task the timer was started for.

Definition at line 231 of file karmstorage.h.

void KarmStorage::stopTimer ( const Task task,
QDateTime  when = QDateTime::currentDateTime() 
)

Log the event that the timer has stopped for this task.

The task stores the last time a timer was started, so we log a new iCal Event with the start and end times for this task.

See also:
KarmStorage::changeTime
Parameters:
task The task the timer was stopped for.

Definition at line 1052 of file karmstorage.cpp.

void KarmStorage::addComment ( const Task task,
const QString &  comment 
)

Log a new comment for this task.

iCal allows multiple comment tags. So we just add a new comment to the todo for this task and write the calendar.

Parameters:
task The task that gets the comment
comment The comment

Definition at line 758 of file karmstorage.cpp.

bool KarmStorage::removeTask ( Task task  ) 

Remove this task from iCalendar file.

Removes task as well as all event history for this task.

Parameters:
task The task to be removed.
Returns:
true if change was saved, false otherwise

Definition at line 727 of file karmstorage.cpp.

QString KarmStorage::addTask ( const Task task,
const Task parent 
)

Add this task from iCalendar file.

Create a new KCal::Todo object and load with task information. If parent is not zero, then set the RELATED-TO attribute for this Todo.

Parameters:
task The task to be removed.
parent The parent of this task. Must have a uid() that is in the existing calendar. If zero, this task is considered a root task.
Returns:
The unique ID for the new VTODO. Return an null QString if there was an error creating the new calendar object.

Definition at line 704 of file karmstorage.cpp.

bool KarmStorage::isEmpty (  ) 

Check if the iCalendar file currently loaded has any Todos in it.

Returns:
true if iCalendar file has any todos

Definition at line 365 of file karmstorage.cpp.

bool KarmStorage::isNewStorage ( const Preferences preferences  )  const

Check if iCalendar file name in the preferences has changed since the last call to load.

If there is no calendar file currently loaded, return false.

Parameters:
preferences Set of KArm preferences.
Returns:
true if a previous file has been loaded and the iCalendar file specified in the preferences is different.

Definition at line 373 of file karmstorage.cpp.

QValueList< HistoryEvent > KarmStorage::getHistory ( const QDate &  from,
const QDate &  to 
)

Return a list of start/stop events for the given date range.

Definition at line 1153 of file karmstorage.cpp.


The documentation for this class was generated from the following files:
KDE Home | KDE Accessibility Home | Description of Access Keys