]> Jonathan Singer

jsinger@leeta.net

Mark Bucciarelli

mark@hubcapconsulting.com

Sirtaj Singh Kang

taj@kde.org

Lauri Watts Reviewer

lauri@kde.org

2000-2004 Jonathan Singer 2004-2005 Mark Bucciarelli &FDLNotice; 2005-02-02 1.5.0 &karm; tracks time spent on various tasks. KDE karm kdeutils time tracker project &karm; 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. &karm; 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. &karm; was originally written by Sirtaj Singh Kang. The word karm means work or deeds in the author's native Punjabi and is the same word (but a better transliteration) as karma. Type karm at a command prompt or select Personal Time Tracker from the Utilities group in the KDE start menu. The standard &Qt; and &kde; command options are available, and can be listed by entering karm --help at the command line. &karm; 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, http://www.mysite.com/mydata/mylabor.ics. Problem: You are a free 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 task you are currently working on. &karm; 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. To create a top-level task, select &Ctrl;N Task New To create a subtask, pick the parent task and select &Ctrl;&Alt;N Task New Subtask When &karm; exits, the task list is saved to the file specified in Settings Configure KArm . When it next opens, it reloads the task list from the same file. &karm; can import and export tasks to minimize your work. See Other Systems. 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. &karm; 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 &karm; 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. &karm; maintains two timers for each task: one for the session time and one for the total time. In the default configuration, &karm; 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. Total Session Time The time spent on the task and all it's 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 it's 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 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, &karm; automatically stops the project 2 task and starts the project 1 task. To associate a task with a one or more desktops, select &Ctrl;E Task Edit . 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 &karm; will be automatically start logging time against that task. 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. &karm; 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, &karm; displays the following dialog: &karm; Idle Detection &karm; Idle Detection Dialog Revert & Stop Subtract the amount of idle time from all active timers and stop them.You were not working on the task(s) while you computer was idle and you are still are not. Revert & Continue Subtract the amount of idle time from all active timers but keep them running.You were not working on the task(s) while your computer was idle but you are now. 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. &karm; provides three ways to report on time you have logged. You can send the session and time totals to the printer, copy the time totals to the clipboard, or copy the time history to the clipboard. To generate the totals report for the printer, select &Ctrl;P File Print . This generates a three-column report for the complete list of tasks. The first column is the task name, the second column is the Total Session Time and the third column is the Total Time. To generate the totals report to the clipboard, select &Ctrl;C File Copy Totals to Clipboard . This report is generated for the currently selected task and all it's subtasks. If the current task is a top-level task, &karm; asks you if you want to generate the report for the current task and it's subtasks or for the entire task list. &karm; Copy This Task &karm; Copy This Task Dialog Once the report is generated, open KEdit or some other text editor and paste the report data. Task Totals 2004-07-10 02:26 Time Task ---------------------------------------------- 9:14 kde 9:14 karm 1:08 bugs 0:00 checkin changes 0:00 promo 0:00 web stuff ---------------------------------------------- 9:14 Total The first column is the Total Time and is indented (like the task names) to indicate task/sub-task relationships. The reported times include the sub-task times. To generate the totals report to the clipboard, select &Ctrl;&Alt;C File Copy History to Clipboard . You must turn on the Log History option in Settings Configure KArm . Otherwise, &karm; only keeps track of totals and not the detailed task history. This report is generated for the currently selected task and all it's subtasks. You also have the choice to generate it for all tasks. When you select the history report, &karm; first prompts you to enter the date range for the report: &karm; Enter Date Range &karm; Enter Date Range After entering a date range, open KEdit or some other text editor and paste the report data. Task History From Thursday 01 July 2004 to Monday 12 July 2004 Printed on: 2004-07-12 17:18 Week of Monday 05 July 2004 5 6 7 8 9 10 11 ------------------------------------------------------------------------- 0:00 kde 0:00 dc !:22 1:46 3:14 1:44 8:06 karm 0:00 3.2 feature plan 1:08 1:08 bugs 0:00 checkin changes 0:00 promo 0:00 web stuff ------------------------------------------------------------------------- 2:30 1:46 3:14 1:44 9:14 Total The task history is totaled for each day and task, grouped by week. The first seven columns are Monday through Sunday. The eighth column is the total for the week and the ninth column is the task name. The task names are indented to indicate the task/sub-task relationships. &karm;, like KOrganizer and Apple's iCal, uses the industry standard iCalendar format for its data. &karm; can read and write the to do lists created by these two applications. If both &karm; and KOrganizer have the same file open, if you edit the file with KOrganizer, you risk losing data. To be safe, only edit the file with one application or the other. As a typical usecase, you might want to plan a project with the project management tool Imendio Planner (from planner.imendio.org) and import its tasks to &karm;, 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 &karm;. That's one way to help ensure your project stays on time and under budget. &DCOP; is the mechanism KDE programs use to communicate with each other. A KDE program provides a list of functions that other programs (a Bash script, for example) can use. DCOPID=`dcop | grep karm` if [ $DCOPID ] then VERS=`dcop $DCOPID KarmDCOPIface version` echo "&karm; version is $VERS" else echo "&karm; not running" fi &karm;'s current &DCOP; interface is currently used mainly for automated testing, so it is very limited. For the full interface definition, see &DCOP; Interface Appendix. To see the full &DCOP; interface of the &karm; version installed on your system, run the following Bash script: DCOPID=`dcop | grep karm` if [ $DCOPID ] then dcop $DCOPID KarmDCOPIface else echo "&karm; not running" fi &karm; can export both totals and history to a comma-delimited file format. To export totals, select File Import/Export Export to CSV file... and &karm; displays the following export dialog: &karm; CSV Export Dialog &karm; CSV Export Dialog Enter the file you would like to export the data to, and modify the other dialog defaults if necessary. Note that the date range control is disabled since you are exporting time totals, not the history data. Click Export and &karm; exports the totals for all tasks to the file you selected. Here is an example of the output format: "kde",,,,,0.00,0.00,6.88,9.83 ,"karm",,,,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. To export task history, select File Import/Export Export History to CSV file... and &karm; displays the same export dialog as shown above. Enter the file you would like to export the data to, and select a date range that you want the task history. Modify the other dialog defaults if necessary. Click Export and &karm; exports the task history for all tasks to the file you selected. 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,,"karm" ,,,,,,,,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 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. The main &karm; window has the following components: menubar, toolbar, task/time window and status bar. &karm; Screen &karm; Screen 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. &Ctrl;S File Save Saves the current tasks and subtasks with their accumulated times &Ctrl;P File Print Prints the &karm; window File Start New Session Resets all session times to zero File Reset All Times Resets all times to zero File Import/Export Import Legacy Flat File... Import old style &karm; save files (&karm; now uses iCalendar-style save files.) File Import/Export Import Tasks from Planner... Import an imendio planner project (see planner.imendio.org). All tasks, subtasks and their "completed" flag will be imported from a .planner-file. You can import them as a subtask by creating a subtask, leaving it marked, and then importing. File Import/Export Export to CSV file... Export Total Session Time, Session Time, Time, and Total Time to a text file. File Import/Export Export History to CSV file... Export task history to a text file. &Ctrl;C File Copy Totals to Clipboard Copies the current total time for a task or all tasks to the &kde; clipboard &Ctrl;&Alt;C File Copy History to Clipboard Copies daily times for a given period to the &kde; clipboard &Ctrl;Q File Quit Closes &karm; S Clock Start Starts timing the selected task Clock Stop Stops timing the selected task &Esc; Clock Stop All Timers Stops timing all tasks &Ctrl;N Task New Add a new task &Ctrl;&Alt;N Task New Subtask Add a new subtask to the selected task Del Task Delete Delete the selected task or subtask &Ctrl;E Task Edit Change the name or accumulated time for the current taskThere are two options for changing the time: Edit Absolute, in which the session and total times can be changed separately; and Edit Relative, in which a certain change is added to or subtracted from both the session and total times.The Auto tracking option allows timing to start and stop automatically when you switch to or from a particular &kde; desktop. Settings Configure Shortcuts Opens a dialog to allow the user to customize the keyboard shortcuts Settings Configure KArm Opens a dialog to allow the user to configure &karm; The dialog has three tabbed panes: Behavior , which allows you to specify an alert for no activity and a warning message when you delete a task set, Display , which configures the fields shown in the main window and Storage, which configures the location of the save file, whether auto saving is enabled and the auto save interval. &help.menu.documentation; The toolbar contains icons for the following commands: (All behave identically to the menu command.) Start Stop New New Subtask Delete Edit Reports the total elapsed time for the session. &karm; Program copyright: 1997-2000 Sirtaj Singh Kang taj@kde.org. 2001-2002 Tomas Pospisek tpo_deb@sourcepole.ch 2003-2004 Mark Bucciarellimark@hubcapconsulting.com Contributors (in alphabetical order) Allen Winter winterz@verizon.net David Faure faure@kde.org Espen Sand espen@kde.org Gioele Barabucci gioele@gioelebarabucci.com Jan Schaumann jschauma@netmeister.org Jesper Pedersen blackie@ifad.dk Kalle Dalheimer kalle@kde.org Klarälvdalens Datakonsult AB Mark Bucciarelli mark@hubcapconsulting.com Thorsten Stärk dev@staerk.de Tomas Pospisek tpo_deb@sourcepole.ch Willi Richert w.richert@cox.net &karm; 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@leeta.net and Sirtaj Singh Kang taj@kde.org. &underFDL; &underGPL; active task A task which has a timer running. &DCOP; The interprocess communication protocol used in KDE. Short for Desktop COmmunication Protocol. desktop GNU/Linux, FreeBSD and other systems that run X-Windows have multiple desktops. You typically have four different desktops installed by default. Each desktop can display it's own set of programs and files. When KDE first starts up, the desktop you see is Desktop 1. If you press &Alt;F2, you will see Desktop 2. Pressing &Alt;F1 will bring back Desktop 1. history If &karm; is configured to log history, it will record ever start/stop timer event. This history is never cleared when times are reset cleared and remains on file until the task is deleted. 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) appears at the bottom of the screen. In this system tray the &karm; icon is on the far right. top level task A task with no parent tasks. Total Session Time The time spent on the task and all it's 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 it's subtasks since all times were reset. &install.intro.documentation; &install.compile.documentation; version version Return &karm;'s version. QString version() version() is a &DCOP; call that returns &karm;'s version number; for example 1.5.0. The version number is returned as a string in the typical GNU format of major.minor.bugfix. quit quit Return &karm;'s quit. QString quit() quit() is a &DCOP; call that provides a way that an external program can gracefully shutdown &karm;. hastodo hastodo Check if top-level todo exists. QString hastodo(QString taskname) taskname The name of the todo to look for. hastodo(QString taskname) is a &DCOP; call that looks for a of the given name. If found, it returns the iCalendar UID that identifies that todo. If not found, it returns an empty string. The iCalendar file that &karm; currently has opened is the file that is searched. All todo trees are searched, not just top-level todo's. If more than one todo has a matching name, the first one found is returned. addtodo addtodo Add new todo. QString addtodo(QString todoname) todoname The name of new todo. addtodo(QString todoname) is a &DCOP; call that adds a new top-level todo to the current storage. The UID of the new todo is returned. &documentation.index;