# The &ktimeclock; Handbook

Graham TerMarsch

    graham@howlingfrog.com

1999-2002 Graham TerMarsch
&underArtisticLicense;
08/05/2002
1.10

This Handbook describes &ktimeclock; Version 2.0.2.

KDE KTimeclock timeclock

## Introduction

&ktimeclock; is designed to be a personal timeclock to help keep track of how much time is spent working on various projects and the tasks that they involve. It originally evolved out of my own use of KArm and finding that although it was useful, there were many things that I would have done differently to make it easier to work with larger volumes of projects and tasks.

Simply set up a series of projects, each of which can contain multiple sub-projects and tasks. Select the current task that you're working on, start the clock, and &ktimeclock; will track the time you've spent working on that task.

## Using KTimeclock

### Understanding projects and tasks

In &ktimeclock;, there is the notion of a "Project", a "Sub-Project", and "Tasks". Conceptually, you can think of them similarly to directories, sub-directories, and files respectively. In the main &ktimeclock; display, a Project always appears at the upper-most level in the tree-view. Projects may contain one or more Sub-Projects or Tasks, and Sub-Projects may also contain one more more Sub-Projects or Tasks (feel free to recurse here at your own leisure).

By using Projects and Sub-Projects, your Tasks (and other Sub-Projects) can be grouped together into their own groups. This grouping should help make it easier to work on projects where there are a large number of individual tasks to be completed, by breaking them up amongst the various stages of the project.

Main KTimeclock display

### Understanding billable rates

Within &ktimeclock;, any Project/Sub-Project/Task can have a billable rate associated with it. As time is tracked against a given task, the display will show you not only how much time has been tracked, but also how much money that relates to at the given billable rate.

&ktimeclock; also gives you the flexibility to make the billable rate for any Sub-Project/Task relative to the billable rate for the Project/Sub-Project that it is within. This allows you to do things such as define a major project and have a single task within it which is charged at a different rate (e.g. double-time).

When configuring the billable rate for a given Project/Sub-Project/Task, there are six different modifiers that can be used:

Parent's rate

  Billable rate is inherited from the parent item. This is the default value for all items as they're created.

=

  Explicitly sets the billable rate for the given item.

+

  Billable rate is equal to the parents billable rate PLUS the specified amount.

-

  Billable rate is equal to the parents billable rate MINUS the specified amount.

*

  Billable rate is equal to the parents billable rate MULTIPLIED BY the specified amount.

/

  Billable rate is equal to the parents billable rate DIVIDED BY the specified amount.

### Creating a new top-level project

To create a new top-level Project, select "Tasks | New project" from the menu. You will then be presented with a new window asking for a description of the Project you wish to create, and the billable rate for this Project.

Add Project dialog

### Creating a sub-project

To create a new Sub-Project, first highlight the Project/Sub-Project that you wish to create the new Sub-Project in. Then select "Tasks | New sub-project" from the menu. You will then be presented with the same "Add Project" dialog that was shown in the previous section (Creating a new top-level project).

### Creating tasks

To create a new Task, first highlight a Project/Sub-Project that you wish to create the Task in. Then select "Tasks | New task" from the menu. You will then be presented with a new window asking for a description of the task you wish to create, the billable rate, and any time that you've already spent working on this Task.

Add Task dialog

### Editing projects/tasks

To edit a Project, Sub-Project, or Task, highlight the item which you wish to edit, and select "Tasks | Edit task" from the menu. You will then be shown a dialog in which you can edit the information relating to the given Project/Task.

### Deleting projects/tasks

To delete a Project, Sub-Project, or Task, highlight the item that you wish to delete, and select "Tasks | Delete task" from the menu. You will be asked to confirm that you wish to delete this item from the tree-view. NOTE, that deleting any Project or Sub-Project will also delete any child Sub-Projects or Tasks that the Project might contain.

### Clearing the time for a project/task

To clear the time associated with a specific Task, highlight the Task that you wish to clear the time for and select "Tasks | Clear task" from the menu. This will clear both the time spent on this Task in this session as well as the total time spent on this Task. You will not be asked to confirm this action.

### Clearing the time for all projects/tasks

To clear the time associated with all of the Tasks in the tree-view, select "Tasks | Clear all tasks" item from the menu. You will be asked to confirm that you wish to clear the time for all of the tasks in the tree-view. Once confirmed, the session time and total time spent for all items in the tree-view will be reset to zero.

### Resetting session time

To reset the count of time spent in a particular session, select "Tasks | Reset session" from the menu. This will clear the session times for all tasks in the tree-view. NOTE, that this does NOT clear the total time spent for any of the tasks, it only resets the count of how much time was spent on the Tasks in this session.

## Customizing KTimeclock

### General

Ok, so there aren't too many configuration options in here yet. The following configuration options are present though:

Autosave every 'n' minutes

  Sets the number of minutes between auto-saves of the timeclock data file. By setting the value of the auto-save timer to zero it can be disabled.

General configuration dialog

### Reports

As of this writing, this page in the configuration dialog is primarily a placeholder for things to come. The current release of &ktimeclock; does not have any reports which can be run (yet). Reporting was a much requested feature and is currently in the works; this page in the configuration dialog is simply to let people know that its coming and will be present in the next release.

Reports configuration dialog (unused)

## KTimeclock features

### Features

- Task based time tracking, with billable rates which can be associated with any given task/project.

- Tracks time to the nearest second.

- Hide-able into system tray.

- XML-based data file. Support for loading of data files from pervious versions of &ktimeclock; is provided.

### Future features

Since the last KDE-1.x release of &ktimeclock; there have been a number of requests for features. This list includes those which I plan to implement but have not yet had a chance to get around to.

Reporting

  This is probably the most often requested feature of &ktimeclock;. I am currently working on this feature, but I need to get a KDE-2.0 version of &ktimeclock; out quickly so this one missed the deadline.

  For users out there who don't want to wait for the next version, and who know how to work with Perl, contact me and I'll send you some Perl scripts which I've been using here as prototypes for some of the reports. Knowledge of programming Perl is a requirement; you've got to edit a few things in the scripts in order to get them working properly in your own installation.

## Frequently asked questions (FAQ)

How can I track time for more than one task simultaneously?

You can't. I've had a few users request this feature so that they can easily keep track of their time while working on more than one project simultaneously, but at this point its not something you can do with &ktimeclock;. If this is a feature that you're seriously interested in do contact the author and let him know; if enough people request it I might just get around to implementing it.

## Credits

&ktimeclock;

Copyright 1998-2002, Graham TerMarsch graham@howlingfrog.com

Contributors:

- Mike Smith mike@rheostatic.com

Translations done by:

- Nobody; there aren't any translations yet. If you'd like to volunteer to help out with translations, please contact the author.

Thanks to:

- Tobias Besch

for providing bug-reports, suggestions, beta-testing, and for the patience to help me work through numerous little glitches.

## License

&ktimeclock;

Copyright 1998-2002, Graham TerMarsch graham@howlingfrog.com

&underArtisticLicense;

## &ktimeclock; Revision History

### v2.0.2

Released May 8, 2002

- Upgraded the build/admin scripts so that KTimeclock will now build against KDE-3.x.

### v2.0.1

Released Jan 29, 2002

- Upgraded the build/admin scripts so that KTimeclock will now build properly against newer Linux distributions using KDE-2.2.x.

- Fixed a bug which would cause &ktimeclock; to not always create the data directory properly in which it tries to store its XML data file. This would manifest itself as having created some tasks/projects in &ktimeclock; and them not being present again when you reloaded &ktimeclock;.

### v2.0.0

Released Jan 13, 2001

- Rebuilt for KDE-2.x.

- File format changed to an XML based data file. Support for loading of legacy text-based data files from previous versions of &ktimeclock; provided.

- &ktimeclock; now periodically auto-saves the data file. The timeout period for how often the data file is auto-saved is configurable.

- License changed from QPL to the Artistic License.

### v0.0.6

Released Sept 22, 2000

- Fixed bug which caused &ktimeclock; to segfault and dump core on exit.

- Fixed bug which caused the data file to not be created if the "File | Quit" menu item was used to exit the application.

- Now saves/restores window size/position.

### v0.0.5

Released Feb 18, 2000

- Fixed several configuration/compilation bugs from the last release of &ktimeclock;. &ktimeclock; should now build properly on SuSE Linux systems.

### v0.0.4

Released Feb 7, 2000

- Added support for docking into KPanel.

- Fixed max limit of 59 hours for any task.

- Changed licensing from GPL to QPL.

### v0.0.3

Released June 10, 1999

- Added ability to clear the time associated with a given item, as well as the ability to clear the time associated with ALL of the items.

- Moved main widget over to KTMainWindow from KTopLevelWidget. Doesn't really do much for us yet as we still don't have any real "state" other than the project list, but the support for session management is at least now available when I get there.

### v0.0.2

Released Nov 16, 1998

- Initial public release.

## Installation

### How to obtain KTimeclock

&ktimeclock; can be found at http://www.howlingfrog.com/opensource/ktimeclock/, the main &ktimeclock; home page.

### Requirements

In order to successfully use &ktimeclock;, you need the KDE 3.x libraries and base installation. No other special software or libraries are required in order to use &ktimeclock;.

### Compilation and installation

In order to compile and install &ktimeclock; on your system, type the following in the base directory of the &ktimeclock; distribution:

            % ./configure
            % make
            % make install

Since &ktimeclock; uses autoconf and automake you should not have any troubles compiling it. Should you run into problems please report them to the author (Graham TerMarsch).

There are several binary distributions of &ktimeclock; available from the &ktimeclock; home page; if you have troubles compiling a version for your system you might want to check there and see if a binary is available. Contributed binaries/packages are welcome; if you manage to get &ktimeclock; to compile on a system for which there is no binary available please contact the author.

&documentation.index;