ktimetracker

KarmStorage Class Reference

#include <karmstorage.h>

Inheritance diagram for KarmStorage:

[legend]

List of all members.

Detailed Description

Class to store/retrieve KTimeTracker data to/from persistent storage.

The storage is an iCalendar file.

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.

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.

Logic that gets and stores KTimeTracker data to disk.

Author:: Mark Bucciarelli <mark@hubcapconsulting.com>

Definition at line 65 of file karmstorage.h.


Public Member Functions
void	addComment (const Task *task, const QString &comment)
QString	addTask (const Task task, const Task parent=0)
bool	allEventsHaveEndTiMe ()
bool	allEventsHaveEndTiMe (Task *task)
bool	bookTime (const Task *task, const QDateTime &startDateTime, const long durationInSeconds)
QString	buildTaskView (TaskView *view)
QString	buildTaskView (KCal::ResourceCalendar rc, TaskView view)
void	changeTime (const Task *task, const long deltaSeconds)
void	closeStorage ()
QList< HistoryEvent >	getHistory (const QDate &from, const QDate &to)
QString	icalfile ()
bool	isEmpty ()
	KarmStorage ()
QString	load (TaskView *taskview, const QString &fileName)
KCal::Event::List	rawevents ()
bool	removeTask (QString taskid)
bool	removeTask (Task *task)
QString	report (TaskView *taskview, const ReportCriteria &rc)
QString	save (TaskView *taskview)
void	setName (const Task *task, const QString &oldname)
QString	setTaskParent (Task task, Task parent)
void	startTimer (QString taskID)
void	startTimer (const Task *task, const KDateTime &when=KDateTime::currentLocalDateTime())
void	stopTimer (const Task *task, const QDateTime &when=QDateTime::currentDateTime())
Task *	task (const QString &uid, TaskView *view)
QStringList	taskidsfromname (QString taskname)
QStringList	taskNames () const
	~KarmStorage ()

Constructor & Destructor Documentation

KarmStorage::KarmStorage ( )

Definition at line 73 of file karmstorage.cpp.

KarmStorage::~KarmStorage ( )

Definition at line 77 of file karmstorage.cpp.

Member Function Documentation

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 654 of file karmstorage.cpp.

QString KarmStorage::addTask	(	const Task *	task,
		const Task *	parent = `0`
	)

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 550 of file karmstorage.cpp.

bool KarmStorage::allEventsHaveEndTiMe ( )

Deliver if all events of the actual calendar have an endtime.

If ktimetracker has been quitted with one task running, it needs to resumeRunning(). This function delivers if an enddate of an event has not yet been stored.

Definition at line 329 of file karmstorage.cpp.

bool KarmStorage::allEventsHaveEndTiMe ( Task * task )

Deliver if all events of a task have an endtime.

If ktimetracker has been quitted with one task running, it needs to resumeRunning(). This function delivers if an enddate of an event has not yet been stored.

Parameters:

task

The task to be examined

Definition at line 311 of file karmstorage.cpp.

bool KarmStorage::bookTime	(	const Task *	task,
		const QDateTime &	startDateTime,
		const 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 successful 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 892 of file karmstorage.cpp.

QString KarmStorage::buildTaskView ( TaskView * view )

Build up the taskview.

This is needed if a subtask has been deleted.

Definition at line 287 of file karmstorage.cpp.

QString KarmStorage::buildTaskView	(	KCal::ResourceCalendar *	rc,
		TaskView *	view
	)

Build up the taskview.

This is needed if the iCal file has been modified.

Definition at line 219 of file karmstorage.cpp.

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

Log the change in a task's time.

This is also called when a timer is stopped. 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-ktimetracker-duration.

Note that the ktimetracker 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.

Parameters:

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

Definition at line 914 of file karmstorage.cpp.

void KarmStorage::closeStorage ( )

Close calendar and clear view.

Release lock if holding one.

Definition at line 293 of file karmstorage.cpp.

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

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

Definition at line 1001 of file karmstorage.cpp.

QString KarmStorage::icalfile ( )

Return the name of the iCal file.

Definition at line 213 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 411 of file karmstorage.cpp.

QString KarmStorage::load	(	TaskView *	taskview,
		const QString &	fileName
	)

Load the list view with tasks read from iCalendar file.

Parses iCalendar file, builds list view items in the proper hierarchy, and loads them into the list view widget.

If the file name passed in is the same as the last file name that was loaded, this method does nothing.

This method considers any of the following conditions errors:

the iCalendar file does not exist
the iCalendar file is not readable
the list group currently has list items
an iCalendar todo has no related to attribute
a todo is related to another todo which does not exist

Parameters:

	taskview	The list group used in the TaskView
	fileName	Override preferences' filename

Returns:: empty string if success, error message if error.

Definition at line 82 of file karmstorage.cpp.

KCal::Event::List KarmStorage::rawevents ( )

list of all events

Definition at line 305 of file karmstorage.cpp.

bool KarmStorage::removeTask ( QString taskid )

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 627 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 600 of file karmstorage.cpp.

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

Output a report based on contents of ReportCriteria.

Definition at line 673 of file karmstorage.cpp.

QString KarmStorage::save ( TaskView * taskview )

Save all tasks and their totals to an iCalendar file.

All tasks must have an associated VTODO object already created in the calendar file; that is, the task->uid() must refer to a valid VTODO in the calender. Delivers empty string if successful, else error msg.

Parameters:

taskview

The list group used in the TaskView

Definition at line 342 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 215 of file karmstorage.h.

QString KarmStorage::setTaskParent	(	Task *	task,
		Task *	parent
	)

Definition at line 373 of file karmstorage.cpp.

void KarmStorage::startTimer ( QString taskID )

Start the timer for a given task ID.

Parameters:

taskID

The task ID of the task to be started

Definition at line 841 of file karmstorage.cpp.

void KarmStorage::startTimer	(	const Task *	task,
		const KDateTime &	when = `KDateTime::currentLocalDateTime()`
	)

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 831 of file karmstorage.cpp.

void KarmStorage::stopTimer	(	const Task *	task,
		const 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.
	when	When the timer stopped.

Definition at line 863 of file karmstorage.cpp.

Task * KarmStorage::task	(	const QString &	uid,
		TaskView *	view
	)

Find the task with the given uid.

Parameters:

	uid	The uid that identifies the task
	view	The TaskView that contains the task

Returns:: the task identified by uid, residing in the TaskView view

Definition at line 195 of file karmstorage.cpp.

QStringList KarmStorage::taskidsfromname ( QString taskname )

Return a list of all task ids for taskname.

Definition at line 574 of file karmstorage.cpp.

QStringList KarmStorage::taskNames ( ) const

Return a list of all task names.

Definition at line 589 of file karmstorage.cpp.

The documentation for this class was generated from the following files:

ktimetracker

KarmStorage Class Reference

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation

ktimetracker

kdepim