KTimeTracker: Difference between revisions

From KDE Community Wiki
(8 intermediate revisions by 2 users not shown)
Line 3: Line 3:
|}
|}


[[Image:Ktimetracker.png|noframe|left|40px]]
KTimeTracker is a standalone desktop application. This page is for people who want to participate in the ktimetracker community. So, for (future) ktimetracker developers.


This page is for people who want to participate in the ktimetracker community. So, for (future) ktimetracker developers.
= How to build =


= IDE =
== Linux ==
Please use qtcreator. Why? Quite easy: The [http://techbase.kde.org/Getting_Started/Set_up_KDE_4_for_development#Development_tasks description how to set up kdevelop with KDE] is over 200 lines long. For eclipse it is 97 and for QtCreator it is 13. So, 13 lines to read instead of 222.
 
mkdir build && cd build
cmake .. && make && make install
 
== Windows ==
 
Install [[Craft]], then:
 
craft 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]
* join our discussion on irc.kde.org, channel #kontact
* learn programming with KDE's [http://techbase.kde.org/Development/Tutorials Programming Tutorial]
 
== So you want to become a KTimeTracker developer ==
Here are your classes:
* mainwindow.*: Is the main window of the KDE application
** 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 instantiate a task, it becomes visible in your TreeWidget.
**** timetrackerstorage.*: Is the storage backend that contains a:
***** KCal::ResourceCalendar


= Architecture =
= Architecture =
ktimetracker can be a kpart (class ktimetrackerpart) or a mainwindow (class mainwindow). The kpart can be used e.g. for a kontact plugin, the mainwindow as stand-alone application. Both classes display a timetrackerwidget, that is a ktabwidget containing one or more taskviews. A taskview is associated with a timetrackerstorage object that holds a calendar with todos and events. A taskview is a [http://doc.qt.nokia.com/4.7/qtreewidget.html QTreeWidget] that holds tasks. A task has a summary (name), a priority and times: the time, total time, session time and total session time. Over the QTreeWidget, a task can have subtasks. The total time is defined as the task's and all its subtasks' times.
ktimetracker is a standalone application. MainWindow displays a timetrackerwidget, that is a ktabwidget containing one or more taskviews. A taskview is associated with a timetrackerstorage object that holds a calendar with todos and events. A taskview is a [http://doc.qt.nokia.com/4.7/qtreewidget.html QTreeWidget] that holds tasks. A task has a summary (name), a priority and times: the time, total time, session time and total session time. Over the QTreeWidget, a task can have subtasks. The total time is defined as the task's and all its subtasks' times.


= Roadmap to the classes =
= Roadmap to the classes =
Line 50: Line 74:
* preferences.cpp - saves which tasks will be shown expanded and which ones collapsed
* preferences.cpp - saves which tasks will be shown expanded and which ones collapsed
* preferences.moc - automatically created from preferences.h
* preferences.moc - automatically created from preferences.h
* ktimetracker_config_behavior.desktop
* ktimetracker_config_display.desktop
* ktimetracker_config_storage.desktop
* ktimetrackerconfigdialog.cpp
* ktimetrackerconfigdialog.cpp
* ktimetracker.kcfgc
* ktimetracker.kcfgc
Line 63: Line 84:
= ktimetracker in the web =
= ktimetracker in the web =
If you need to update screenshots you might have to do it on the following pages:
If you need to update screenshots you might have to do it on the following pages:
* http://userbase.kde.org/ktimetracker
* http://userbase.kde.org/KTimeTracker
* http://community.kde.org/index.php?title=Ktimetracker
* https://community.kde.org/Ktimetracker
* http://kde.org/applications/utilities/ktimetracker/
* http://kde.org/applications/utilities/ktimetracker/ - deleted as of 2019-05-26
 
== 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
 
== 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 ==
 
* ?
 
 
== Where is what ? ==
* The latest development sourcecode is available via web at https://cgit.kde.org/ktimetracker.git/
* Craft ''blueprint'': https://cgit.kde.org/craft-blueprints-kde.git/tree/extragear/ktimetracker
* CI setup: https://cgit.kde.org/sysadmin/ci-tooling.git
* Building dependencies for CI and kdesrc-build: https://cgit.kde.org/kde-build-metadata.git/
* You can discuss about KDE pim development on freenode, channel #kontact
* The user documentation is generated from https://cgit.kde.org/ktimetracker.git/tree/doc
* KTimeTracker all-you-need in the internet: https://userbase.kde.org/KTimeTracker
 
== Development Direction ==
The following similar programs can give you inspiration how to move forward developing:
* hourglass
* gnotime
* titrax
* taskCoach
* Hamster
 
== 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:
 
<pre>
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
</pre>
 


= bugs =
= bugs =
Line 73: Line 187:
= coding style =
= coding style =
It is more important that you contribute than that you contribute with the right coding style. That having said, [[User:ThorstenStaerk|I]] prefer if you use code that is consistent with QtCreator's defaults. Opening and closing brackets and parentheses should be on the same row or column.
It is more important that you contribute than that you contribute with the right coding style. That having said, [[User:ThorstenStaerk|I]] prefer if you use code that is consistent with QtCreator's defaults. Opening and closing brackets and parentheses should be on the same row or column.
= git art =
git checkout KDE/4.7
then
git cherry-pick -x <commit>


= development direction =
= development direction =
There should not be any "New" and "Close". ktimetracker should contain exactly one taskview. See https://bugs.kde.org/show_bug.cgi?id=182317 and https://bugs.kde.org/show_bug.cgi?id=265085
There should not be any "New" and "Close". ktimetracker should contain exactly one taskview. See https://bugs.kde.org/show_bug.cgi?id=182317 and https://bugs.kde.org/show_bug.cgi?id=265085
= ktimetracker benchmark =


= The help menu =
= The help menu =
The help menu is stupidly overloaded and I cannot do anything about it because it is somewhere hidden in the library code. Would love to simplify it. "Help" does not need subitems - you want help.
The help menu is stupidly overloaded and I cannot do anything about it because it is somewhere hidden in the library code. Would love to simplify it. "Help" does not need subitems - you want help.
= The KPart Mess =
ktimetracker is an application displaying a kpart. On the one hand, this makes it easy to be integrated as kontact plugin. But on the other hand, I have the feeling, ktimetracker can no long be debugged so easily. Here are the reasons why dedicated applications are better:
* can be designed graphically in qtcreator
* can be edited in qtcreator having all advantages like code completion
* can be debugged step-by-step from qtcreator
* [https://bugs.kde.org/show_bug.cgi?id=182312 toolbar magic] can be done
* with a kpart, you will have to do make install to get the kpart installed(?)
* https://bugs.kde.org/show_bug.cgi?id=204203
* https://bugs.kde.org/show_bug.cgi?id=283479


= Polls =
= Polls =
Line 102: Line 199:
= recent activity =
= recent activity =
* [http://bugs.kde.org/188769 Ktimetracker history export and editing broken]
* [http://bugs.kde.org/188769 Ktimetracker history export and editing broken]
* [http://bugs.kde.org/show_bug.cgi?id=238164 duplicate 238164]
** [http://bugs.kde.org/show_bug.cgi?id=238164 duplicate 238164]
* [http://bugs.kde.org/282546 setting changes do not have immediate effect]
* [http://bugs.kde.org/282546 setting changes do not have immediate effect]
* [http://bugs.kde.org/270929 Store value in edit history dialog even if user does not change cell afterwards.], [http://commits.kde.org/kdepim/cbeb999d445fbf98cad927c8c70b8b8675ea1746 fix], [http://commits.kde.org/kdepim/b85b4e94dc6883e53e59c89a3070cf33c1d8ad7a backport]
* [http://bugs.kde.org/270929 Store value in edit history dialog even if user does not change cell afterwards.], [http://commits.kde.org/kdepim/cbeb999d445fbf98cad927c8c70b8b8675ea1746 fix], [http://commits.kde.org/kdepim/b85b4e94dc6883e53e59c89a3070cf33c1d8ad7a backport]
Line 110: Line 207:
** [http://bugs.kde.org/272686 ktimetracker always have tray icon(s) even if configured to disable them], [http://quickgit.kde.org/?p=kdepim.git&a=commit&h=7664da2b1a72fef6c03d47cc5c6e741a85b28a65 fix], [http://quickgit.kde.org/?p=kdepim.git&a=commit&h=09d423048814d34965e954ab6d3fe9e72b9a5b7d backport]
** [http://bugs.kde.org/272686 ktimetracker always have tray icon(s) even if configured to disable them], [http://quickgit.kde.org/?p=kdepim.git&a=commit&h=7664da2b1a72fef6c03d47cc5c6e741a85b28a65 fix], [http://quickgit.kde.org/?p=kdepim.git&a=commit&h=09d423048814d34965e954ab6d3fe9e72b9a5b7d backport]
** [http://bugs.kde.org/236566 System tray icon displayed 2 times], [http://quickgit.kde.org/?p=kdepim.git&a=commit&h=2733d0dc422fff8691a828579db372570741bb21 fix], [http://commits.kde.org/kdepim/ff4ab352188edddd55baa8e2f7dfa26d1dc530ed backport]
** [http://bugs.kde.org/236566 System tray icon displayed 2 times], [http://quickgit.kde.org/?p=kdepim.git&a=commit&h=2733d0dc422fff8691a828579db372570741bb21 fix], [http://commits.kde.org/kdepim/ff4ab352188edddd55baa8e2f7dfa26d1dc530ed backport]
= Related Projects =
http://websvn.kde.org/trunk/playground/base/plasma/applets/timetracker/
= Readings =
* http://doc.trolltech.com/4.5/itemviews-simpletreemodel.html
* RFC 2445


= Maintainer knowledge =
= Maintainer knowledge =

Revision as of 23:28, 18 June 2019

Ktimetracker
ktimetracker running on the N810
noframe
noframe

KTimeTracker is a standalone desktop application. This page is for people who want to participate in the ktimetracker community. So, for (future) ktimetracker developers.

How to build

Linux

mkdir build && cd build
cmake .. && make && make install

Windows

Install Craft, then:

craft ktimetracker

Developing KTimeTracker

So you want to become a KTimeTracker developer

Here are your classes:

  • mainwindow.*: Is the main window of the KDE application
    • 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 instantiate a task, it becomes visible in your TreeWidget.
        • timetrackerstorage.*: Is the storage backend that contains a:
          • KCal::ResourceCalendar

Architecture

ktimetracker is a standalone application. MainWindow displays a timetrackerwidget, that is a ktabwidget containing one or more taskviews. A taskview is associated with a timetrackerstorage object that holds a calendar with todos and events. A taskview is a QTreeWidget that holds tasks. A task has a summary (name), a priority and times: the time, total time, session time and total session time. Over the QTreeWidget, a task can have subtasks. The total time is defined as the task's and all its subtasks' times.

Roadmap to the classes

See http://api.kde.org/4.x-api/kdepim-apidocs/ktimetracker/html/

main -> mainwindow ------------------------                                                         -> task
                                            \                                                     /
                                             -> timetrackerwidget -(contains n>=0)-> taskview -
                                            /                                                     \
ktimetracker_plugin -> ktimetrackerpart ---                                                         -> timetrackerstorage 

KTimeTrackerSettings

ktimetracker's program main.cpp creates mainwindow, this creates a timetrackerpart this calls timetrackerwidget, this calls taskview, this contains a timetrackerstorage.

karmstorage stores and loads the events and tasks. taskview displays them. timetrackerwidget displays one or more taskviews in tabs, plus the searchWidget. timetrackerpart can be integrated into a mainwindow or a kontact plugin. mainwindow adds the menu.

MainWindow is the outermost layer and initializes the menus and actions, sets up the status bar, and handles many of the signal-to-slot connections. It holds a pointer to the timetrackerwidget and Preferences objects and implements the ktimetracker DBUS interface.

TaskView does most of the work in the application. This QListWidget subclass sets up the columns in the list, the idle detection timer, the auto save timer, and the desktop tracker. It starts and stops timers, handles importing and exporting and displays the edit task dialog in response to user action. TaskView holds a private pointer to Preferences and a timetrackerstorage object.

A Task is a QListViewItem subclass stores state such as the timer totals, if a timer is currently running for the task. It also defines the list view sort order and can return a pointer to a KCal::Todo object that holds the same information.

Preferences is a singleton that stores configuration options. It raises signals when options change (for example, the location where the ktimetracker data is stored) so the application can react and adjust.

timetrackerstorage is a singleton that creates an interface for storing ktimetracker data. Currently, it uses KDE Resource framework and stores data in the iCalendar format.

KTimeTrackerSettings stores ktimetracker's configuration, settings, preferences or however you call it. It is declared in the file ktimetracker.h.

how configuration is programmed

Configuration is also called preferences. The following files are involved:

  • cfgbehavior.ui
  • ui_cfgbehavior.h - automatically created from cfgbehavior.ui
  • preferences.h - saves which tasks will be shown expanded and which ones collapsed
  • preferences.cpp - saves which tasks will be shown expanded and which ones collapsed
  • preferences.moc - automatically created from preferences.h
  • ktimetrackerconfigdialog.cpp
  • ktimetracker.kcfgc
  • ktimetracker.kcfg
  • ktimetracker.h - declaring the class KTimeTrackerSettings. This file is automatically generated from ktimetracker.kcfg.
  • ktimetracker.cpp - implementing the class KTimeTrackerSettings. This file is automatically generated from ktimetracker.kcfg.
  • ktimetrackerconfigdialog.cpp
  • ktimetrackerconfigdialog.h

ktimetracker in the web

If you need to update screenshots you might have to do it on the following pages:

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

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

  • ?


Where is what ?

Development Direction

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

  • hourglass
  • gnotime
  • titrax
  • taskCoach
  • Hamster

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


bugs

  • Find ktimetracker's open bugs (without NEEDINFO bugs) with this query
  • find all ktimetracker's bugs with this query

coding style

It is more important that you contribute than that you contribute with the right coding style. That having said, I prefer if you use code that is consistent with QtCreator's defaults. Opening and closing brackets and parentheses should be on the same row or column.

development direction

There should not be any "New" and "Close". ktimetracker should contain exactly one taskview. See https://bugs.kde.org/show_bug.cgi?id=182317 and https://bugs.kde.org/show_bug.cgi?id=265085

The help menu

The help menu is stupidly overloaded and I cannot do anything about it because it is somewhere hidden in the library code. Would love to simplify it. "Help" does not need subitems - you want help.

Polls

recent activity

Related Projects

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

Readings

Maintainer knowledge

If you want to hand over maintainership, here is some info: