KTimeTracker

    From KDE UserBase Wiki
    The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

    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.

    With KDE 3.x, KTimeTracker was named KArm, with KDE 4.x, it is named KTimeTracker. For KDE 4.x, there is a stub called karm that just reminds you that the name has changed.

    {img src=http://pim.kde.org/img/screenshots/karm.png}

    Using ktimetracker

    What ktimetracker can do for you

    The current stable version of ktimetracker (called kArm) 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: {img src=http://pim.kde.org/img/screenshots/karm-edithistory.png width= height= align= desc= link= }

    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

    • look at [1]
    • join our discussion on irc.kde.org, channel #kontact
    • learn programming with KDE's [ProgrammingTutorial]

    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


    dbus

    dbus is clearly a developer topic. To test the dbus functionality of your ktimetracker, have ktimetracker running and proceed like this: {CODE()} 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 {CODE}

    Info for 4.0

    See http://www.nabble.com/Re:--Kde-cvs-announce--KDE-4.0-Release-Branch-td14615393.html

    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: {CODE()} 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 {CODE} The respective ktimetracker translation is still stored in karm.*o, and it works.

    How to reproduce a stale lock

    {CODE()} touch .kde/share/apps/kabc/lock/_home_tom_.kde_share_apps_karm_karm.ics.lock {CODE}

    How to get rid of debugging output

    {CODE()} cmake -DCMAKE_BUILD_TYPE=Release {CODE}

    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

    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

    http://doc.trolltech.com/4.1/itemviews-simpletreemodel.html