The KTimetracker Handbook

# The KTimetracker Handbook

Jonathan Singer `<jsinger@leeta.net>`

Mark Bucciarelli `<mark@hubcapconsulting.com>`

Sirtaj Singh Kang `<taj@kde.org>`

Reviewer: Lauri Watts
Revision 5.0 (2019-11-19)

Copyright © 2000-2004 Jonathan Singer

Copyright © 2004-2005 Mark Bucciarelli

Legal Notice

KTimetracker tracks time spent on various tasks.

List of Examples

2.1. Bash script that echoes KTimetracker's version
2.2. List KTimetracker's D-Bus interface to console

Chapter 1. Introduction
Introduction

# Chapter 1. Introduction

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 was originally written by Sirtaj Singh Kang. Its home page is https://userbase.kde.org/KTimeTracker.

Chapter 2. Using KTimetracker
Using KTimetracker

# Chapter 2. Using KTimetracker

## Starting KTimetracker

Type ktimetracker at a command prompt or select Personal Time Tracker from the Applications → Utilities group in the Plasma Application Launcher. The generic Qt™ and KDE Frameworks 5 command options are available, see man pages qt5options and kf5options.

KTimetracker provides an additional command option that allows you to enter the name of the iCalendar file that is used to store your labor history. You enter a remote iCalendar file by using HTTP or FTP as part of the file name; for example, https://www.mysite.com/mydata/mylabor.ics.

Tasks
Tasks

## Tasks

Problem: You are a freelance software consultant with many clients. Some clients have multiple projects. During the course of a day, you switch back and forth between different projects. You need to track your time to generate monthly invoices.

Solution: Create one top-level task for each client and a subtask for each client project. For projects that require more detailed tracking, create a list of project subtasks. Track time by double-clicking on the task you are currently working on.

KTimetracker provides great flexibility in tracking your time, allowing unlimited tasks and task depth. Time may be logged to any task, and more than one task can be active at any given time.

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

To create a top-level task, select Task → New Task... (Ctrl+T). To create a subtask, highlight the parent task and select Task → New Subtask... (Ctrl+B).

When KTimetracker exits, the task list is saved to a file on your disk. When it next opens, it reloads the task list from the same file.

KTimetracker can import and export tasks to minimize your work. See the section called “Other Systems”.

Timers
Timers

## Timers

Problem: To remain solvent, you must bill an average of five hours a day. To stay on track, you watch your daily and weekly totals.

Solution: Reset the session timer at the beginning of each work day and reset all timers at the beginning of each week.

KTimetracker makes tracking time simple. To start logging time against a task, double-click on the task. To stop logging time, double-click the task again. Active tasks display a small clock in the Session Time column.

Another visual clue of logging activity is the KTimetracker system tray icon. When a task is active, the second hand in the icon moves. If you rest the mouse pointer over this icon, the name of the active task will display in a tooltip. If more than one task is active, the task names in the tooltip are separated by commas.

KTimetracker maintains two timers for each task: one for the session time and one for the total time. In the default configuration, KTimetracker displays two columns for each timer, resulting in a total of four columns for each task:

Session Time

  The time spent on the task since the session began.

Time

  The time spent on the task since all times were reset.

Total Session Time

  The time spent on the task and all its subtasks since the session began.

Total Time

  The time spent on the task and all its subtasks since all times were reset.

To start a new session, select File → Start New Session

To reset all times, select File → Reset All Times

### Desktop Tracking

Problem: You have two main projects that you switch between each day. To help organize your work, you keep your project 1 files on Desktop 1 and your project 2 files on Desktop 2.

Solution: Associate project 1 task with Desktop 1 and the project 2 task with Desktop 2. When you switch from Desktop 2 to Desktop 1 active, KTimetracker automatically stops the project 2 task and starts the project 1 task.

To associate a task with one or more desktops, select Task → Properties (Ctrl+E). Turn on Auto Tracking and select the desktop or desktops to associate with this task. When any of the selected desktops becomes active, after a short delay KTimetracker will be automatically start logging time against that task.

### Idle Detection

Problem: You leave work early on Friday to run an errand and forget to stop the timer. When you return on Monday, the timer is still running.

Solution: Turn on idle detection on the Behavior page of the settings dialog.

KTimetracker can be configured to detect when the mouse and keyboard become idle. If the mouse and keyboard are idle for longer than the specified number of minutes, KTimetracker displays the following dialog:

Continue Timing

  Apply the idle time to all active timers and keep them running.

  You were working on the task(s) while your computer was idle and still are.

Revert Timing

  Subtract the amount of idle time from all active timers and stop them.

  You were not working on the task(s) while your computer was idle and you are still not.

Other Systems
Other Systems

## Other Systems

### KOrganizer

KTimetracker, like KOrganizer and Apple's iCal, uses the industry standard iCalendar format for its data. KTimetracker can read and write the to-do lists created by these two applications.

You can even work synchronously on one file with KOrganizer and KTimetracker. If one program changes the file, the updates will be propagated to the other application automatically.

### Planner

As a typical usecase, you might want to plan a project with the project management tool Planner and import its tasks to KTimetracker with File → Import → Import Tasks From Planner..., to have them in the industry standard iCalendar format. Having done so, you are able to schedule the tasks in KOrganizer, and account your time to them in KTimetracker. That's one way to help ensure your project stays on time and under budget.

### D-Bus

KTimetracker does support numerous methods that can be used with D-Bus.

There are two ways to use the D-Bus interface: Qt™'s GUI qdbusviewer and the command line qdbus.

Example 2.1. Bash script that echoes KTimetracker's version

    qdbus org.kde.ktimetracker /KTimeTracker version 2>/dev/null || echo "ktimetracker not running"

KTimetracker's current D-Bus interface is currently used mainly for automated testing, so it is very limited. For the full interface definition, see the Appendix A, D-Bus Interface.

To see the full D-Bus interface of the KTimetracker version installed on your system, run the following Bash script:

Example 2.2. List KTimetracker's D-Bus interface to console

    qdbus org.kde.ktimetracker /KTimeTracker 2>/dev/null || echo "ktimetracker not running"

### Export Totals to CSV

KTimetracker can export both totals and history to a comma-delimited file format. To export totals, select File → Export... and KTimetracker displays the export dialog.

Select option Times as CSV in group Report Type. The dialog is going to look as follows:

Modify the dialog defaults if necessary. You can preview the CSV output on the right side of the dialog. Click Save As... and KTimetracker exports the totals for all tasks to the file you enter in a file dialog.

Use the Copy to Clipboard button to export the times to the clipboard.

Here is another example of the output format:

`
"kde",,,,,0.00,0.00,6.88,9.83
,"ktimetracker",,,,6.88,8.70,6.88,9.83
,,"3.2 feature plan",,,0.00,0.00,0.00,0.00
,,"bugs",,,0.00,1.13,0.00,1.13
,,"checkin changes - translation strings",,,0.00,0.00,0.00,0.00
,,"time card report",,,0.00,0.00,0.00,0.00
,"kopete",,,,0.00,0.00,0.00,0.00
,"promo",,,,0.00,0.00,0.00,0.00
,"web stuff",,,,0.00,0.00,0.00,0.00
`

Top-level tasks are output in the first column, sub-tasks in the second, and so on. The time data is output after the maximum task depth (five in this example). The first time column is Session Time, the second is Time, the third is Total Session Time and the fourth is the Total Time.

### Export History to CSV

To export task history, select File → Export → Export... and KTimetracker displays the same export dialog as shown above. Select option History as CSV in group Report Type.

Select a date range that you want the task history to cover. Modify the dialog defaults if necessary. You can preview the CSV output on the right side of the dialog. Click Save As... and KTimetracker exports the totals for all tasks to the file you enter in a file dialog.

Use the Copy to Clipboard button to export the times to the clipboard.

Here is an example of the output format:

`
Task History
From Tuesday 06 July 2004 to Tuesday 13 July 2004
Printed on: 2004-07-13 18:10
2004-07-06,2004-07-07,2004-07-08,2004-07-09,2004-07-10,2004-07-11,2004-07-12,2004-07-13,
,,,,,,,,0.00,"kde"
,,1.77,3.23,1.73,,1.37,0.82,8.95,,"ktimetracker"
,,,,,,,,0.00,,,"3.2 feature plan"
,1.13,,,,,,,1.13,,,"bugs"
,,,,,,,,0.00,,,"checkin changes - translation strings"
,,,,,,,,0.00,,,"time card report"
,,,,,,,,0.00,,"kopete"
,,,,,,,,0.00,,"promo"
,,,,,,,,0.00,,"web stuff"
`

The first three lines identify when the report was generated and for which date range. The fourth row is a comma-delimited list of the dates in the date range, in ISO 8601 format (YYYY-MM-DD). All subsequent rows list the time logged against each task. The last numeric column is the row total across all days. The task name prints after the total column, and is indented to indicate the task/sub-task relationship. Top level task names appear in the first column after the total.

Chapter 3. The KTimetracker interface
The KTimetracker interface

# Chapter 3. The KTimetracker interface

The main KTimetracker window has the following components: menubar, toolbar, searchbar, task/time window and status bar.

The searchbar is a combined field. As long as you do not press Enter, it acts as a filter. Then, only tasks that match your input are shown. As soon as you press Enter, your input is used as a name to create a new task.

Choose Configuration for PDA in the Appearance page of the settings dialog if you have a touchscreen and your screen real estate is precious. It will disable the search bar and every click will pop up a context menu.

## The Task/Time window

The various tasks are displayed in this window, along with the time accumulated for each in the current session and in total. Tasks being timed have a small clock icon next to the session time.

Subtasks can be created for each task. Clicking the plus sign and minus sign in front of the main task toggles the view of its associated subtasks. The total time accrued for a task includes the times for its subtasks, as well as its own accumulated time.

The Toolbar and Statusbar
The Toolbar and Statusbar

## The Toolbar and Statusbar

The toolbar contains icons for the following commands:

### Note

All behave identically to the menu command.

- New Task

- New Subtask

- Start

- Stop

- Delete

- Edit

- Open

- Save

The statusbar reports the name of the file where the data was saved.

Chapter 4. Credits and License
Credits and License

# Chapter 4. Credits and License

KTimetracker

Program copyright:

- 1997-2000 Sirtaj Singh Kang `(taj AT kde.org)`

- 2001-2002 Tomas Pospisek `(tpo_deb AT sourcepole.ch)`

- 2003-2004 Mark Bucciarelli `(mark AT hubcapconsulting.com)`

- 2004-2011 Thorsten Stärk `(dev AT staerk.de)`

- 2019 Alexander Potashev `(aspotashev AT gmail.com)`

Contributors (in alphabetical order)

- Alexander Potashev `(aspotashev AT gmail.com)`

- Allen Winter `(winter AT kde.org)`

- David Faure `(faure AT kde.org)`

- Espen Sand `(espen AT kde.org)`

- Gioele Barabucci `(gioele AT gioelebarabucci.com)`

- Jan Schaumann `(jschauma AT netmeister.org)`

- Jesper Pedersen `(blackie AT ifad.dk)`

- Kalle Dalheimer `(kalle AT kde.org)`

- Klarälvdalens Datakonsult AB

- Mark Bucciarelli `(mark AT hubcapconsulting.com)`

- Thorsten Stärk `(dev AT staerk.de)`

- Tomas Pospisek `(tpo_deb AT sourcepole.ch)`

- Willi Richert `(w.richert AT cox.net)`

KTimetracker was inspired by Harald Tveit Alvestrand's very useful utility called titrax, the only failing of which is that it is based on the Xt toolkit.

Documentation copyright 2000-2004 Jonathan Singer `(jsinger AT leeta.net)` and Sirtaj Singh Kang `(taj AT kde.org)`.

This documentation is licensed under the terms of the GNU Free Documentation License.

This program is licensed under the terms of the GNU General Public License.

Glossary
Glossary

# Glossary

### A

active task

  A task which has a timer running.

### D

D-Bus

  An interprocess communication protocol. Short for Desktop Bus.

desktop

  GNU/Linux®, FreeBSD and other systems that run X.Org Server have multiple desktops. You can typically have four different desktops installed by default. Each desktop can display its own set of programs and files. When KDE Plasma first starts up, the desktop you see is Desktop 1. If you press Ctrl+F2, you will see Desktop 2. Pressing Ctrl+F1 will bring back Desktop 1.

### H

history

  If KTimetracker is configured to log history, it will record every start/stop timer event. This history is not cleared when times are reset and remains on file until the task is deleted.

### S

session

  A user-defined starting point for the session timers. A new session begins when you select File → Start New Session. Session data is not saved when you create a new session.

Session Time

  The time spent on the task since the session began.

system tray

  The system tray is in the bar that (by default in KDE Plasma) appears at the bottom of the screen. In this system tray the KTimetracker icon is on the far right.

### T

top level task

  A task with no parent tasks.

Total Session Time

  The time spent on the task and all its subtasks since the session began.

Time

  The time spent on the task since all times were reset.

Total Time

  The time spent on the task and all its subtasks since all times were reset.

Appendix A. D-Bus Interface
D-Bus Interface

# Appendix A. D-Bus Interface

version
version

## Name

version — Return KTimetracker's version.

## Synopsis

    QString version()

## Description

`version()` is a D-Bus call that returns KTimetracker's version number; for example 4.3.1. The version number is returned as a string in the typical GNU format of major.minor.bugfix.

quit
quit

## Name

quit — Quit KTimetracker'.

## Synopsis

    QString quit()

## Description

`quit()` is a D-Bus call that provides a way that an external program can gracefully shutdown KTimetracker.

addTask
addTask

## Name

addTask — Add new task.

## Synopsis

    QString addTask(QString taskname)

### Parameters

`taskname`

  The name of new task.

## Description

`addTask(QString taskname)` is a D-Bus call that adds a new top-level to-do to the current storage. The UID of the new task is returned.