Jump to content

KTimeTracker: Difference between revisions

From KDE Community Wiki
← Older edit
Aspotashev (talk | contribs)
KDEDevelopers, trusted
480 edits
No edit summary
Aspotashev (talk | contribs)
KDEDevelopers, trusted
480 edits
No edit summary
 
(18 intermediate revisions by the same user 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.
= 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/
* 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
* Another frontpage for users: https://apps.kde.org/ktimetracker/
 
= How to build =
 
== Linux ==
Step 1: Install dependencies
 
* If you are running '''Fedora''' 32+
sudo dnf install kf5-kdbusaddons-devel kf5-kdoctools-devel kf5-kidletime-devel \
    kf5-kio-devel kf5-knotifications-devel kf5-ktextwidgets-devel \
    kf5-kwindowsystem-devel kf5-kxmlgui-devel kf5-kcalendarcore-devel
 
Step 2: Compile KTimeTracker from source code
mkdir build && cd build
cmake .. && make && make install
 
== Windows ==
 
Install [[Craft]], then:
 
craft ktimetracker
 
= Developing KTimeTracker =
 
* Bug reports: [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]
* Workboard: https://phabricator.kde.org/tag/ktimetracker/


= Architecture =
= 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 [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 =
ktimetracker is a standalone application. MainWindow displays a TimeTrackerWidget, that is a widget containing one TasksWidget (through a TaskView object). A TaskView is associated with a TimeTrackerStorage object that handle file load/save operations and monitor file changes on disk. A TasksWidget is a [https://doc.qt.io/qt-5/qtreeview.html QTreeView] that displays tasks from a model (TasksModel).
See http://api.kde.org/4.x-api/kdepim-apidocs/ktimetracker/html/
 
main -> mainwindow ------------------------                                                        -> task
A task has a name, description, priority and times: the time, total time, session time and total session time. A task can have subtasks. The total time is defined as the task's and all its subtasks' times.
                                            \                                                    /
                                              -> timetrackerwidget -(contains n>=0)-> [http://api.kde.org/4.x-api/kdepim-apidocs/ktimetracker/html/classTaskView.html taskview] -
                                            /                                                    \
ktimetracker_plugin -> ktimetrackerpart ---                                                        -> [http://api.kde.org/4.x-api/kdepim-apidocs/ktimetracker/html/classtimetrackerstorage.html timetrackerstorage]
KTimeTrackerSettings


ktimetracker's program main.cpp creates '''mainwindow''', this creates a '''timetrackerpart''' this calls '''timetrackerwidget''', this calls '''taskview''', this contains a '''timetrackerstorage'''.
= Overview of the classes =


karmstorage stores and loads the events and tasks.
taskview displays them.
timetrackerwidget displays one or more taskviews in tabs, plus the searchWidget.
timetrackerwidget displays one or more taskviews in tabs, plus the searchWidget.
timetrackerpart can be integrated into a mainwindow or a kontact plugin.
timetrackerpart can be integrated into a mainwindow or a kontact plugin.
Line 36: Line 61:
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.
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.
= how configuration is programmed =
 
Configuration is also called preferences. The following files are involved:
* settings/cfg*.ui - tabs of the Settings dialog
* settings/ktimetrackerconfigdialog.cpp
* settings/ktimetrackerconfigdialog.h
* settings/ktimetracker.kcfgc
* settings/ktimetracker.kcfg
* ktimetracker.{h,cpp} - declaring/implementing the class KTimeTrackerSettings. These files are automatically generated from ktimetracker.kcfg.
* widgets/taskswidget.cpp - saves which tasks will be shown expanded and which ones collapsed
 
= dbus =


'''KTimeTrackerSettings''' stores ktimetracker's configuration, settings, preferences or however you call it. It is declared in the file ktimetracker.h.
To test the dbus functionality of your KTimeTracker, have KTimeTracker running and proceed like in this example:
qdbus
qdbus org.kde.ktimetracker
qdbus org.kde.ktimetracker /KTimeTracker
qdbus org.kde.ktimetracker /KTimeTracker org.kde.ktimetracker.ktimetracker.quit


= how configuration is programmed =
== How to reproduce a stale lock ==
Configuration is also called preferences. The following files are involved:
Here is an example to give you an idea:
* cfgbehavior.ui
touch .kde/share/apps/kabc/lock/_home_tom_.kde_share_apps_karm_karm.ics.lock
* ui_cfgbehavior.h - automatically created from cfgbehavior.ui
 
* preferences.h - saves which tasks will be shown expanded and which ones collapsed
== Development Direction ==
* preferences.cpp - saves which tasks will be shown expanded and which ones collapsed
 
* preferences.moc - automatically created from preferences.h
The following similar programs can give you inspiration how to move forward developing:
* ktimetrackerconfigdialog.cpp
* hourglass
* ktimetracker.kcfgc
* gnotime
* ktimetracker.kcfg
* titrax
* ktimetracker.h - declaring the class KTimeTrackerSettings. This file is automatically generated from ktimetracker.kcfg.
* taskCoach
* ktimetracker.cpp - implementing the class KTimeTrackerSettings. This file is automatically generated from ktimetracker.kcfg.
* Hamster
* ktimetrackerconfigdialog.cpp
 
* ktimetrackerconfigdialog.h
== 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


= ktimetracker in the web =
END:VCALENDAR
If you need to update screenshots you might have to do it on the following pages:
</pre>
* http://userbase.kde.org/KTimeTracker
* https://community.kde.org/Ktimetracker
* http://kde.org/applications/utilities/ktimetracker/ - deleted as of 2019-05-26


= bugs =
= bugs =
* Find ktimetracker's open bugs (without NEEDINFO bugs) with [https://bugs.kde.org/buglist.cgi?product=ktimetracker&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&columnlist=changeddate%2Cbug_severity%2Cassigned_to%2Creporter%2Cresolution%2Cvotes%2Cshort_desc this query]
* Find ktimetracker's open bugs (without NEEDINFO bugs) with [https://bugs.kde.org/buglist.cgi?product=ktimetracker&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&columnlist=changeddate%2Cbug_severity%2Cassigned_to%2Creporter%2Cresolution%2Cvotes%2Cshort_desc this query]
* find all ktimetracker's bugs with [https://bugs.kde.org/buglist.cgi?product=ktimetracker&columnlist=changeddate%2Cbug_severity%2Cassigned_to%2Creporter%2Cresolution%2Cvotes%2Cshort_desc this query]
* find all ktimetracker's bugs with [https://bugs.kde.org/buglist.cgi?product=ktimetracker&columnlist=changeddate%2Cbug_severity%2Cassigned_to%2Creporter%2Cresolution%2Cvotes%2Cshort_desc this query]


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


= 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


= The help menu =
= Polls =
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 =
* [http://www.doodle.com/kykdg32p3f5aqidy Do you want to be able to start several ktimetracker instances?]
* [http://www.doodle.com/kykdg32p3f5aqidy Do you want to be able to start several ktimetracker instances?]


= 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]
Line 88: Line 166:
** [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]


= Maintainer knowledge =
= Related Projects =
If you want to hand over maintainership, here is some info:
 
http://websvn.kde.org/trunk/playground/base/plasma/applets/timetracker/
 
= Readings =


* to be allowed to change ktimetracker options in bugzilla, like adding a new version to bugzilla:
* RFC 2445
** open a request under https://bugs.kde.org/enter_sysadmin_request.cgi and ask to be added to the editcomponents group
** change ktimetracker options (e.g. add a version) under https://bugs.kde.org/editproducts.cgi?action=edit&product=ktimetracker

Latest revision as of 17:13, 7 May 2023

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.

Where is what?

How to build

Linux

Step 1: Install dependencies

  • If you are running Fedora 32+
sudo dnf install kf5-kdbusaddons-devel kf5-kdoctools-devel kf5-kidletime-devel \
    kf5-kio-devel kf5-knotifications-devel kf5-ktextwidgets-devel \
    kf5-kwindowsystem-devel kf5-kxmlgui-devel kf5-kcalendarcore-devel

Step 2: Compile KTimeTracker from source code 

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

Windows

Install Craft, then: 

craft ktimetracker

Developing KTimeTracker

Architecture

ktimetracker is a standalone application. MainWindow displays a TimeTrackerWidget, that is a widget containing one TasksWidget (through a TaskView object). A TaskView is associated with a TimeTrackerStorage object that handle file load/save operations and monitor file changes on disk. A TasksWidget is a QTreeView that displays tasks from a model (TasksModel).

A task has a name, description, priority and times: the time, total time, session time and total session time. A task can have subtasks. The total time is defined as the task's and all its subtasks' times.

Overview of the classes

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.

how configuration is programmed

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

  • settings/cfg*.ui - tabs of the Settings dialog
  • settings/ktimetrackerconfigdialog.cpp
  • settings/ktimetrackerconfigdialog.h
  • settings/ktimetracker.kcfgc
  • settings/ktimetracker.kcfg
  • ktimetracker.{h,cpp} - declaring/implementing the class KTimeTrackerSettings. These files are automatically generated from ktimetracker.kcfg.
  • widgets/taskswidget.cpp - saves which tasks will be shown expanded and which ones collapsed

dbus

To test the dbus functionality of your KTimeTracker, have KTimeTracker running and proceed like in this example: 

qdbus
qdbus org.kde.ktimetracker
qdbus org.kde.ktimetracker /KTimeTracker
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

Development Direction

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

  • hourglass
  • gnotime
  • titrax
  • taskCoach
  • Hamster

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

Polls

recent activity

Related Projects

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

Readings

  • RFC 2445
Retrieved from "https://community.kde.org/index.php?title=KTimeTracker&oldid=96475"