Difference between revisions of "KTimeTracker"

Jump to: navigation, search
m (resize images)
Line 5: Line 5:
 
KTimeTracker detects when your keyboard and mouse are idle and can associate different tasks with different desktops, two tools that can help keep the timer running on the correct task.
 
KTimeTracker detects when your keyboard and mouse are idle and can associate different tasks with different desktops, two tools that can help keep the timer running on the correct task.
  
[[Image:Ktimetracker.png]]
+
[[Image:ktimetracker.png|500px|center]]
  
= Using ktimetracker =
+
= Using KTimeTracker =
  
== What ktimetracker can do for you ==
+
== What KTimeTracker can do for you ==
The current stable version of ktimetracker (4.1) can:
+
The current stable version of KTimeTracker (4.1) can:
 
* organize and stopwatch tasks, subtasks
 
* organize and stopwatch tasks, subtasks
ktimetracker allows you to organize and stopwatch your work. You can put your daily todo-list into that tool. You can group your work by tasks, subtask and n<super>th</super>level tasks, meaning that every subtask can still have a subtask below it, up to some 1000 levels.
+
KTimeTracker allows you to organize and stopwatch your work. You can put your daily todo-list into that tool. You can group your work by tasks, subtask and n<super>th</super>level tasks, meaning that every subtask can still have a subtask below it, up to some 1000 levels.
  
== What ktimetracker will be able to do for you ==
+
== What KTimeTracker will be able to do for you ==
The current development version of ktimetracker can:
+
The current development version of KTimeTracker can:
 
* edit task history and comments
 
* edit task history and comments
ktimetracker allows you to edit your task's history and to put a comment for every event that you have stopped:
+
KTimeTracker allows you to edit your task's history and to put a comment for every event that you have stopped:
  
[[Image:Ktimetracker-history.png]]
+
[[Image:ktimetracker-history.png|500px|center]]
  
 
=== Options ===
 
=== Options ===
 
KTimeTracker 4 has the following behavior options:
 
KTimeTracker 4 has the following behavior options:
{img src="img/wiki_up/KTimeTrackerConFigure.png" }
+
{img src="img/wiki_up/KTimeTrackerConFigure.png"}
  
 
== Compatibility ==
 
== Compatibility ==
 
Up to KDE 3.1 (incl.), flat files were used to store the data. From KDE 3.2 on, the iCal format is used, but flat files can still be imported until KDE 4. With KDE 4, the custom fields  
 
Up to KDE 3.1 (incl.), flat files were used to store the data. From KDE 3.2 on, the iCal format is used, but flat files can still be imported until KDE 4. With KDE 4, the custom fields  
X-KDE-karm-duration, X-KDE-karm-totalTaskTime, X-KDE-karm-totalSessionTime and X-KDE-karm-desktopList were renamed to X-KDE-ktimetracker-duration and the respective other names. KTimeTracker 4 can still read karm iCal files, but not the other way round.
+
X-KDE-karm-duration, X-KDE-karm-totalTaskTime, X-KDE-karm-totalSessionTime and X-KDE-karm-desktopList were renamed to X-KDE-KTimeTracker-duration and the respective other names. KTimeTracker 4 can still read karm iCal files, but not the other way round.
  
 
== Does it scale ==
 
== Does it scale ==
Line 35: Line 35:
 
*needing support ? Ask and answer in the chat at irc.kde.org, channel #kde
 
*needing support ? Ask and answer in the chat at irc.kde.org, channel #kde
  
= Developing ktimetracker =
+
= Developing KTimeTracker =
* look at [http://bugs.kde.org/buglist.cgi?short_desc_type=allwordssubstr&short_desc=&long_desc_type=allwordssubstr&long_desc=&product=ktimetracker&component=general&component=reporting&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bugidtype=include&bug_id=&votes=&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&changedin=&chfieldfrom=&chfieldto=Now&chfieldvalue=&order=Reuse+same+sort+as+last+time&cmdtype=doit&newqueryname=&namedcmd=allktimetrackerbugs our Bugzilla]
+
* look at [http://bugs.kde.org/buglist.cgi?short_desc_type=allwordssubstr&short_desc=&long_desc_type=allwordssubstr&long_desc=&product=KTimeTracker&component=general&component=reporting&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bugidtype=include&bug_id=&votes=&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&changedin=&chfieldfrom=&chfieldto=Now&chfieldvalue=&order=Reuse+same+sort+as+last+time&cmdtype=doit&newqueryname=&namedcmd=allKTimeTrackerbugs our Bugzilla]
 
* join our discussion on irc.kde.org, channel #kontact
 
* join our discussion on irc.kde.org, channel #kontact
 
* learn programming with KDE's [http://techbase.kde.org/Development/Tutorials Programming Tutorial]
 
* learn programming with KDE's [http://techbase.kde.org/Development/Tutorials Programming Tutorial]
  
== So you want to become a ktimetracker developer ==
+
== So you want to become a KTimeTracker developer ==
 
Here are your classes:
 
Here are your classes:
 
* mainwindow.*: Is the main window of the KDE application
 
* mainwindow.*: Is the main window of the KDE application
* karm_part.*: Is the KPart of ktimetracker
+
* karm_part.*: Is the KPart of KTimeTracker
 
** timetrackerwidget.*: Is a widget with no or several tabs that contain
 
** timetrackerwidget.*: Is a widget with no or several tabs that contain
 
*** taskview.*: Is a treeListWidget that contains:
 
*** taskview.*: Is a treeListWidget that contains:
Line 51: Line 51:
  
 
== Nokia N810 ==
 
== Nokia N810 ==
I got a Nokia N810 from Nokia to allow me porting ktimetracker to it. I appreciate this a lot and am now kompiling ktimetracker for arm. The project is not ready, here is what I found out:
+
I got a Nokia N810 from Nokia to allow me porting KTimeTracker to it. I appreciate this a lot and am now kompiling KTimeTracker for arm. The project is not ready, here is what I found out:
  
To kompile ktimetracker for the Nokia N810
+
To kompile KTimeTracker for the Nokia N810
 
* add the maemo repository  
 
* add the maemo repository  
 
* install openssh
 
* install openssh
  
 
== dbus ==
 
== dbus ==
dbus is clearly a developer topic. To test the dbus functionality of your ktimetracker, have ktimetracker running and proceed like in this example:
+
dbus is clearly a developer topic. To test the dbus functionality of your KTimeTracker, have KTimeTracker running and proceed like in this example:
 
  qdbus
 
  qdbus
 
  ...
 
  ...
   org.kde.ktimetracker
+
   org.kde.KTimeTracker
 
  ...
 
  ...
  qdbus org.kde.ktimetracker
+
  qdbus org.kde.KTimeTracker
 
  ...
 
  ...
 
  /KTimeTracker
 
  /KTimeTracker
 
  ...
 
  ...
  qdbus org.kde.ktimetracker /KTimeTracker
+
  qdbus org.kde.KTimeTracker /KTimeTracker
 
  ...
 
  ...
  method void org.kde.ktimetracker.ktimetracker.quit()
+
  method void org.kde.KTimeTracker.KTimeTracker.quit()
 
  ...
 
  ...
  qdbus org.kde.ktimetracker /KTimeTracker org.kde.ktimetracker.ktimetracker.quit
+
  qdbus org.kde.KTimeTracker /KTimeTracker org.kde.KTimeTracker.KTimeTracker.quit
  
 
== Internationalization ==
 
== Internationalization ==
You want to test the translation of ktimetracker. For this, you want to call ktimetracker in, say, german. For this, you need to know how you at all can call a KDE 4 program in another language than english. Here is as an example how I call akregator in german:
+
You want to test the translation of KTimeTracker. For this, you want to call KTimeTracker in, say, german. For this, you need to know how you at all can call a KDE 4 program in another language than english. Here is as an example how I call akregator in german:
 
  wget http://websvn.kde.org/*checkout*/trunk/l10n-kde4/de/messages/kdepim /akregator.po   
 
  wget http://websvn.kde.org/*checkout*/trunk/l10n-kde4/de/messages/kdepim /akregator.po   
 
  msgfmt -o akregator.mo akregator.po
 
  msgfmt -o akregator.mo akregator.po
 
  cp akregator.mo .kde4/share/locale/de/LC_MESSAGES/
 
  cp akregator.mo .kde4/share/locale/de/LC_MESSAGES/
 
  KDE4_LANG=de akregator
 
  KDE4_LANG=de akregator
The respective ktimetracker translation is still stored in karm.*o, and it works.
+
The respective KTimeTracker translation is still stored in karm.*o, and it works.
  
 
== How to reproduce a stale lock ==
 
== How to reproduce a stale lock ==
Line 92: Line 92:
  
 
== Where is what ? ==
 
== Where is what ? ==
* The latest development sourcecode is available via web at http://websvn.kde.org/trunk/KDE/kdepim/ktimetracker
+
* The latest development sourcecode is available via web at http://websvn.kde.org/trunk/KDE/kdepim/KTimeTracker
 
* You can subscribe to watch code changes at  
 
* You can subscribe to watch code changes at  
 
http://commitfilter.kde.org
 
http://commitfilter.kde.org
Line 102: Line 102:
 
* The userdocumentation is generated from  
 
* The userdocumentation is generated from  
 
http://websvn.kde.org/trunk/KDE/kdepim/doc/karm
 
http://websvn.kde.org/trunk/KDE/kdepim/doc/karm
* ktimetracker all-you-need in the internet:
+
* KTimeTracker all-you-need in the internet:
http://wiki.kde.org/ktimetracker
+
http://wiki.kde.org/KTimeTracker
* ktimetracker as part of pim, for developers:
+
* KTimeTracker as part of pim, for developers:
 
http://pim.kde.org/components/karm.php / http://websvn.kde.org/trunk/www/areas/pim/components/karm.php
 
http://pim.kde.org/components/karm.php / http://websvn.kde.org/trunk/www/areas/pim/components/karm.php
* ktimetracker as part of pim, for users:
+
* KTimeTracker as part of pim, for users:
 
http://kontact.kde.org / http://websvn.kde.org/trunk/www/apps/kontact
 
http://kontact.kde.org / http://websvn.kde.org/trunk/www/apps/kontact
  
Line 118: Line 118:
  
 
== Kontact plugin vs. Standalone ==
 
== Kontact plugin vs. Standalone ==
The Kontact plugin is realized via a KPart. The elegant solution would be to have one KPart that can be integrated into Kontact and one shell that just displays the KPart. This is not so far now. At the moment, karm_part.cpp implements the ktimetracker part and mainwindow.cpp implements the standalone application.
+
The Kontact plugin is realized via a KPart. The elegant solution would be to have one KPart that can be integrated into Kontact and one shell that just displays the KPart. This is not so far now. At the moment, karm_part.cpp implements the KTimeTracker part and mainwindow.cpp implements the standalone application.
 
Here's a patch that allows us to use the karm part (karm_part.cpp) as widget of mainwindow, not perfect yet, but showing a direction:
 
Here's a patch that allows us to use the karm part (karm_part.cpp) as widget of mainwindow, not perfect yet, but showing a direction:
 
<pre>
 
<pre>
Line 195: Line 195:
  
 
== About storage ==
 
== About storage ==
The storage of your ktimetracker data takes place in an iCal file. That format needs a bit of explanation. A simple one looks like the following:
+
The storage of your KTimeTracker data takes place in an iCal file. That format needs a bit of explanation. A simple one looks like the following:
  
 
<pre>
 
<pre>
Line 272: Line 272:
 
   KCal::ResourceCalendar* cal;
 
   KCal::ResourceCalendar* cal;
 
   KCal::ResourceCached* resource;
 
   KCal::ResourceCached* resource;
   resource=new KCal::ResourceLocal("/tmp/ktimetrackerkonsole.ics");
+
   resource=new KCal::ResourceLocal("/tmp/KTimeTrackerkonsole.ics");
 
   cal=resource;
 
   cal=resource;
 
}
 
}

Revision as of 19:57, 18 August 2008

What is KTimeTracker

KTimeTracker tracks time spent on various tasks. It is useful for tracking billable hours and can report the hours logged by task and day. This time history can be exported to a comma-delimited text file for import into other billing and/or project management tools. KTimeTracker detects when your keyboard and mouse are idle and can associate different tasks with different desktops, two tools that can help keep the timer running on the correct task.

Ktimetracker.png

Using KTimeTracker

What KTimeTracker can do for you

The current stable version of KTimeTracker (4.1) can:

  • organize and stopwatch tasks, subtasks

KTimeTracker allows you to organize and stopwatch your work. You can put your daily todo-list into that tool. You can group your work by tasks, subtask and n<super>th</super>level tasks, meaning that every subtask can still have a subtask below it, up to some 1000 levels.

What KTimeTracker will be able to do for you

The current development version of KTimeTracker can:

  • edit task history and comments

KTimeTracker allows you to edit your task's history and to put a comment for every event that you have stopped:

Ktimetracker-history.png

Options

KTimeTracker 4 has the following behavior options: {img src="img/wiki_up/KTimeTrackerConFigure.png"}

Compatibility

Up to KDE 3.1 (incl.), flat files were used to store the data. From KDE 3.2 on, the iCal format is used, but flat files can still be imported until KDE 4. With KDE 4, the custom fields X-KDE-karm-duration, X-KDE-karm-totalTaskTime, X-KDE-karm-totalSessionTime and X-KDE-karm-desktopList were renamed to X-KDE-KTimeTracker-duration and the respective other names. KTimeTracker 4 can still read karm iCal files, but not the other way round.

Does it scale

KTimeTracker scales well and it regularly tested with a 1.2 MB file (https://bugs.kde.org/attachment.cgi?id=14413&action=view) available from (https://bugs.kde.org/show_bug.cgi?id=110523). We have never observed slow-downs caused by the size of the calendar-file.

Support

  • needing support ? Ask and answer in the chat at irc.kde.org, channel #kde

Developing KTimeTracker

So you want to become a KTimeTracker developer

Here are your classes:

  • mainwindow.*: Is the main window of the KDE application
  • karm_part.*: Is the KPart of KTimeTracker
    • timetrackerwidget.*: Is a widget with no or several tabs that contain
      • taskview.*: Is a treeListWidget that contains:
        • task.*: A QObject and QTreeWidgetItem. A task can be constructed from a taskview and a todo. As soon as you instanciate a task, it becomes visible in your TreeWidget.
        • karmstorage.*: Is the storage backend that contains a:
          • KCal::ResourceCalendar

Nokia N810

I got a Nokia N810 from Nokia to allow me porting KTimeTracker to it. I appreciate this a lot and am now kompiling KTimeTracker for arm. The project is not ready, here is what I found out:

To kompile KTimeTracker for the Nokia N810

  • add the maemo repository
  • install openssh

dbus

dbus is clearly a developer topic. To test the dbus functionality of your KTimeTracker, have KTimeTracker running and proceed like in this example:

qdbus
...
 org.kde.KTimeTracker
...
qdbus org.kde.KTimeTracker
...
/KTimeTracker
...
qdbus org.kde.KTimeTracker /KTimeTracker
...
method void org.kde.KTimeTracker.KTimeTracker.quit()
...
qdbus org.kde.KTimeTracker /KTimeTracker org.kde.KTimeTracker.KTimeTracker.quit

Internationalization

You want to test the translation of KTimeTracker. For this, you want to call KTimeTracker in, say, german. For this, you need to know how you at all can call a KDE 4 program in another language than english. Here is as an example how I call akregator in german:

wget http://websvn.kde.org/*checkout*/trunk/l10n-kde4/de/messages/kdepim /akregator.po  
msgfmt -o akregator.mo akregator.po
cp akregator.mo .kde4/share/locale/de/LC_MESSAGES/
KDE4_LANG=de akregator

The respective KTimeTracker translation is still stored in karm.*o, and it works.

How to reproduce a stale lock

Here is an example to give you an idea:

touch .kde/share/apps/kabc/lock/_home_tom_.kde_share_apps_karm_karm.ics.lock

How to get rid of debugging output

cmake -DCMAKE_BUILD_TYPE=Release

Goals

  • Unicode - I found out it is already capable of UTF-8.

Where is what ?

http://commitfilter.kde.org

  • You can get informed on irc about code changes at freenode,
  1. kde-commits
  • You can discuss about KDE pim development on freenode,
  1. kontact

http://websvn.kde.org/trunk/KDE/kdepim/doc/karm

  • KTimeTracker all-you-need in the internet:

http://wiki.kde.org/KTimeTracker

  • KTimeTracker as part of pim, for developers:

http://pim.kde.org/components/karm.php / http://websvn.kde.org/trunk/www/areas/pim/components/karm.php

  • KTimeTracker as part of pim, for users:

http://kontact.kde.org / http://websvn.kde.org/trunk/www/apps/kontact

Development Direction

The following similar programs can give you inspiration how to move forward developing:

  • hourglass
  • gnotime
  • titrax
  • taskCoach
  • Hamster

Kontact plugin vs. Standalone

The Kontact plugin is realized via a KPart. The elegant solution would be to have one KPart that can be integrated into Kontact and one shell that just displays the KPart. This is not so far now. At the moment, karm_part.cpp implements the KTimeTracker part and mainwindow.cpp implements the standalone application. Here's a patch that allows us to use the karm part (karm_part.cpp) as widget of mainwindow, not perfect yet, but showing a direction:

Index: mainwindow.cpp
===================================================================
--- mainwindow.cpp      (revision 618712)
+++ mainwindow.cpp      (working copy)
@@ -24,6 +24,7 @@
 #include <qstring.h>

 #include "karmerrors.h"
+#include "karm_part.h"
 #include "karmutility.h"
 #include "mainwindow.h"
 #include "preferences.h"
@@ -43,9 +44,10 @@
     _sessionSum( 0 )
 {

+  _karmpart  = new karmPart(this,"hi",this,"hi");
   _taskView  = new TaskView( this, 0, icsfile );

-  setCentralWidget( _taskView );
+  setCentralWidget( _karmpart->widget() );
   // status bar
   startStatusBar();

@@ -85,7 +87,7 @@
   connect( _taskView, SIGNAL( tasksChanged( QPtrList<Task> ) ),
                       _tray, SLOT( updateToolTip( QPtrList<Task> ) ));

-  _taskView->load();
+  //_taskView->load();

   // Everything that uses Preferences has been created now, we can let it
   // emit its signals
Index: mainwindow.h
===================================================================
--- mainwindow.h        (revision 618621)
+++ mainwindow.h        (working copy)
@@ -5,6 +5,7 @@

 #include "karmerrors.h"
 #include <karmdcopiface.h>
+#include "karm_part.h"
 #include "reportcriteria.h"

 class KAccel;
@@ -34,7 +35,8 @@

     KAccel*          _accel;
     KAccelMenuWatch* _watcher;
-    TaskView*        _taskView;
+    TaskView*       _taskView;
+    karmPart*        _karmpart;
     long             _totalSum;
     long             _sessionSum;
     Preferences*     _preferences;
Index: Makefile.am
===================================================================
--- Makefile.am (revision 618621)
+++ Makefile.am (working copy)
@@ -21,7 +21,7 @@
 libkarm_shared_la_LIBADD = $(top_builddir)/libkcal/libkcal.la \
             $(top_builddir)/kresources/remote/libkcal_resourceremote.la \
              $(top_builddir)/libkdepim/libkdepim.la $(LIBXSS) -lkdeprint
-karm_SOURCES = main.cpp
+karm_SOURCES = main.cpp karm_part.cpp
 karm_LDADD = libkarm_shared.la
 karm_LDFLAGS = $(all_libraries) $(KDE_RPATH)
 noinst_HEADERS = desktoptracker.h edittaskdialog.h printdialog.h \

IdleTimeDetector

The idletimedetector is in the equally-named .cpp and .h file. It starts a qtimer and at every timeout, checks, if the X extension delivers for the last user interaction a timepoint that is further away than the maxIdleTime.

About storage

The storage of your KTimeTracker data takes place in an iCal file. That format needs a bit of explanation. A simple one looks like the following:

BEGIN:VCALENDAR
PRODID:-//K Desktop Environment//NONSGML libkcal 3.5//EN
VERSION:2.0
BEGIN:VTODO
DTSTAMP:20060915T181010Z
ORGANIZER;CN=root:MAILTO:
X-KDE-karm-totalSessionTime:0
X-KDE-karm-totalTaskTime:19
CREATED:20060609T230212Z
UID:libkcal-652058592.803
SEQUENCE:0
LAST-MODIFIED:20060915T181010Z
SUMMARY:fg
CLASS:PUBLIC
PRIORITY:5
PERCENT-COMPLETE:0
END:VTODO

BEGIN:VEVENT
DTSTAMP:20060915T181010Z
ORGANIZER:MAILTO:
X-KDE-karm-duration:300
CREATED:20060915T174305Z
UID:libkcal-6397995.845
SEQUENCE:0
LAST-MODIFIED:20060910T174305Z
SUMMARY:fg
CLASS:PUBLIC
PRIORITY:5
CATEGORIES:KArm
RELATED-TO:libkcal-652058592.803
DTSTART:20060910T172346Z
DTEND:20060910T174305Z
TRANSP:OPAQUE
END:VEVENT

END:VCALENDAR

A test case for kcal

CMakeLists.txt

PROJECT( kde4start )
FIND_PACKAGE(KDE4 REQUIRED)
INCLUDE_DIRECTORIES( ${KDE4_INCLUDES} . )


SET(kde4startSources main.cpp )

KDE4_ADD_EXECUTABLE(kde4start ${kde4startSources} )

TARGET_LINK_LIBRARIES(kde4start ${KDE4_KDEUI_LIBS} ${KDE4_KCAL_LIBS} ${KDE4_KPARTS_LIBS} kdepim kcal_resourceremote )

main.cpp

#include <QString>
#include <kapplication.h>
#include <kaboutdata.h>
#include <kmessagebox.h>
#include <kcmdlineargs.h>
#include <KMainWindow>
#include <kcal/resourcecalendar.h>
#include <kcal/resourcecached.h>
#include <kcal/resourcelocal.h>

int main (int argc, char *argv[])
{
  const QByteArray& ba=QByteArray("test");
  const KLocalizedString name=ki18n("myName");
  KAboutData aboutData( ba, ba, name, ba, name);
  KCmdLineArgs::init( argc, argv, &aboutData );
  KApplication khello;
  KCal::ResourceCalendar* cal;
  KCal::ResourceCached* resource;
  resource=new KCal::ResourceLocal("/tmp/KTimeTrackerkonsole.ics");
  cal=resource;
}

kompile, link and run

cmake . && make && ./kde4start

Related Projects

http://websvn.kde.org/trunk/playground/base/plasma/applets/timetracker/

Readings


Content is available under Creative Commons License SA 4.0 unless otherwise noted.