#include <karmstorage.h>

Public Member Functions
TQString	load (TaskView taskview, const Preferences preferences, TQString fileName="")

TQString	icalfile ()

TQString	buildTaskView (KCal::ResourceCalendar rc, TaskView view)

void	closeStorage (TaskView *view)

TQString	save (TaskView *taskview)

TQString	loadFromFlatFile (TaskView *taskview, const TQString &filename)

TQString	loadFromFlatFileCumulative (TaskView *taskview, const TQString &filename)

TQString	report (TaskView *taskview, const ReportCriteria &rc)

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

bool	bookTime (const Task *task, const TQDateTime &startDateTime, long durationInSeconds)

void	setName (const Task *task, const TQString &oldname)

void	startTimer (const Task *task)

void	stopTimer (const Task *task, TQDateTime when=TQDateTime::currentDateTime())

void	addComment (const Task *task, const TQString &comment)

bool	removeTask (Task *task)

TQString	addTask (const Task task, const Task parent)

bool	isEmpty ()

bool	isNewStorage (const Preferences *preferences) const

TQValueList< HistoryEvent >	getHistory (const TQDate &from, const TQDate &to)

Static Public Member Functions
static KarmStorage *	instance ()

Detailed Description

Singleton to store/retrieve KArm data to/from persistent storage.

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.

Logic that gets and stores KArm data to disk.

Author: Mark Bucciarelli mark@.nosp@m.hubc.nosp@m.apcon.nosp@m.sult.nosp@m.ing.c.nosp@m.om

Definition at line 67 of file karmstorage.h.

Member Function Documentation

◆ addComment()

void KarmStorage::addComment	(	const Task *	task,
		const TQString &	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.

◆ addTask()

TQString 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 TQString if there was an error creating the new calendar object.

Definition at line 704 of file karmstorage.cpp.

◆ bookTime()

bool KarmStorage::bookTime	(	const Task *	task,
		const TQDateTime &	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.

◆ changeTime()

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-TDE-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.

◆ getHistory()

TQValueList< HistoryEvent > KarmStorage::getHistory	(	const TQDate &	from,
		const TQDate &	to
	)

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

Definition at line 1153 of file karmstorage.cpp.

◆ isEmpty()

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.

◆ isNewStorage()

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.

◆ loadFromFlatFile()

TQString KarmStorage::loadFromFlatFile	(	TaskView *	taskview,
		const TQString &	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.

◆ loadFromFlatFileCumulative()

TQString KarmStorage::loadFromFlatFileCumulative	(	TaskView *	taskview,
		const TQString &	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.

◆ removeTask()

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.

◆ report()

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

Output a report based on contents of ReportCriteria.

Definition at line 873 of file karmstorage.cpp.

◆ setName()

void KarmStorage::setName	(	const Task *	task,
		const TQString &	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 219 of file karmstorage.h.

◆ startTimer()

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 230 of file karmstorage.h.

◆ stopTimer()

void KarmStorage::stopTimer	(	const Task *	task,
		TQDateTime	when = `TQDateTime::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.

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

karm

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ addComment()

◆ addTask()

◆ bookTime()

◆ changeTime()

◆ getHistory()

◆ isEmpty()

◆ isNewStorage()

◆ loadFromFlatFile()

◆ loadFromFlatFileCumulative()

◆ removeTask()

◆ report()

◆ setName()

◆ startTimer()

◆ stopTimer()

karm

karm