eb@berns.prima.de
This documentation is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
For more details see the file COPYING in the source distribution of GTimeTracker.
Well, I'm german and I find it hard to express myself in english. So if you find some phrases and/or words that I used in a wrong way (and you will find them :-) ), please send me a mail, to let me correct this. Please send me notes about typos, too.
And I would like to hear about your opionion on GTimeTracker. Maybe you want some features to be integrated in GTimeTracker. Or you have discovered a bug. Or you think, that the user interface needs a change in some way. Just send me a mail, and I will see, what I can do for you. I want to make this tool usable and usefull for everyone.
Basically GTimeTracker is just a tool to measure the time, you let a given project (see What is a Project) in a selected state (see The State of a Project). GTimeTracker isn't espacially smart at this. You, the user, will have to give GTimeTracker hints about what you're currently wanting to measure or it will not display reasonable values.
But when one has learned to use GTimeTracker effectively, it can be of great help. For example you can use it to optimize your work. It can show you, that you are spending to much time on unimportent tasks. Or it can exactly count the hours you spend on a project, that is payed for by time. You may discover many other ways, GTimeTracker can work for you.
After first starting GTimeTracker you will be notified, that there is no readable configuration file in your home directory ($HOME/.gtimetrackerrc). You will be asked, whether or not you want GTimeTracker to install a new one. This is a safety question, because something could have happend that made your configuration file unreadable and maybe you will want to look for it yourself. Writing a new config file will cause the loss of all your projects and time measurements. If you started GTimeTracker for the first time, you can just press the OK button.
The main window consists of four areas. There is a menu bar (see The Menu Bar), a toolbar (see The Toolbar), a status bar at the bottom of the window (see The Status Bar), and a scrollable area where all your projects will be displayed (see The Project List). When you start GTimeTracker for the first time, this area will show just one project, which is titled "empty".
Note that you can customize the look of the main window in the preferences dialog (see The Preferences Dialog), so not all these areas might show up after you have played around with GTimeTracker a bit. You can allways enable missing areas in the preferences dialog.
The menu bar is located at the top of the window by default. If you are using a GNOME version of GTimeTracker, you can change the location of the menu bar in numerouse ways. This customization of the menu bar is subject of the GNOME global documentation and not covered here.
Nearly all menu items in GTimeTracker have a shortcut (or accelerator key). Those key sequences are shown behind the name of the function. If for example you want to activate the function New Project... from the File menu, you can just hold down the Control key and press the N key. In the menu this is shown as Ctl+N.
The menu bar consists of four menus: File, Edit, Timer and Help. I will describe these menus in the following sections.
In the File menu you will find the functions dealing with the configuration file -- $HOME/.gtimetrackerrc. In addition there is a function to quit GTimeTracker. I have also put the New Project... funtion there. This is mainly because nearly all software has a new function in the File menu and that's the place I would search for it.
This function shows the New Project Dialog. Have a look at The New Project Dialog for more info.
Okay, let's have a look at the functions dealing with the configuration file. The configuration file holds infos about your preferences (see The Preferences Dialog) and about your list of projects (see The Project List). The functions are Reload Configuration File and Save Configuration File.
The configuration file will be saved every time, GTimeTracker exits. I have made some effort, to verify that this file will be updated even in case of program aborts. So there should be no need to save the configuration file for safety purpose. But you might want to rearrange your projects a bit. You may want to save the current state of the projects just to make sure you cannot delete a project by accident.
In case you made some mistakes you can then use the Reload Configuration File function. You will be asked, if you really want to discard your current set of projects. Just press OK, if you really ment to reload the old configuration file. If you activated this function by accident, you can press Cancel.
This function just quits GTimeTracker. The configuration file with your current list of projects will automatically be saved.
The Edit menu holds all the functions to edit the project list. In addition there is a menu item to activate the preferences dialog.
These functions are usefull to rearrange your project list. You can use Cut to remove projects from the list. But these cutted projects aren't discarted right away. You can use Paste to insert a cutted or copied project either before the current selected project, or, if no project is selected, at the bottom of your project list. The Copy function does the same as the Cut function, but will not remove the project from the list.
Note that there is only room for one project to be cutted or copied. If you cut or copy another project, before pasting the previous one, that project will be lost forever.
On the other hand it is possible to paste a cutted or copied project multiple times.
This function shows the properties dialog, or, if it is allready shown, updates its contents. See The Properties Dialog for more details.
This function shows the preferences dialog. See The Preferences Dialog for more details.
The Timer menu lets you start and stop the internal timer (see The Internal Timer and The State of a Project).
You can start the timer by activating Start. Stop will stop the timer. And you can toggle the state of the timer with Timer running.
The only menu item in the Help menu is About.... This function will popup the about dialog. Just press Close to get rid of it...
Each item in the toolbar activates a menu item. So besides the menu itself and the shotcut (or accelerator key), I described above, you can use the toolbar items as a third way of executing a given function.
The initial state of the toolbar shows icons for the following functions from left to right:
File — New Project...
File — Reload Configuration File
File — Save Configuration File
Edit — Cut
Edit — Copy
Edit — Paste
Edit — Properties...
Timer — Timer Running
Edit — Preferences...
A project consists of the following:
Each project has a title, that is displayed in the project list
There is a daily timer, which will be automatically reset on a new day, and which you can zero as you please. This is the timer, that will be displayed in the project list.
Another timer holds the total time this project has been worked on.
I have included a description of the project. You can use it to specify the project some more.
Basically a project has just two states. Selected or unselected. You can only select one project at a time. An unselected project is just that — unselected. But there are other values that affect the handling of a selected project.
E.g. there is the timer (see The Internal Timer). The time of a selected project will only be counted, when the timer is running. This gives us a third state of a project. Here is a list of states and what happens to a project in each state:
There is no time measuring or other effect.
In that state, the time is measured for the given project. In addition there will be a log file entry for that project (if log files are enabled - see Logfile), and the shell command is executed (see Shell Commands).
The time will not be measured, and there is no entry in the log file. But the shell command has been run and is not beeing canceled.
This might be confusing the first time, but you can benefit from this. E.g. I use the shell command (see Shell Commands) to update my .project file. When I'm not really working on a project (e.g. because I'm just away to get me a new coffee or something), I can leave the .project file alone, but don't have to count the time.
The project list is displayed in the main area of the main window. It shows what projects are in the list, and which project currently is selected. One line reflects one project. The daily time and the title of the project are displayed.
You can select a project by clicking on it with the left mouse button. Pressing the left mouse button again on a selected project deselects it. This is the way to mark all projects as unselected.
To get a popup menu for a project, you have to press and hold the right mouse button on it. If the project wasn't selected, it will now receive the selection, and the popup menu will be displayed. The popup menu consists of the menu items of the Edit menu, which deal with projects. Thus it is just a replacement for selecting a project and then using the Edit menu.
The status bar displays the currently selected project. It will display more info in the future, but that's not implemented in the current version of GTimeTracker.
The status bar helps to have a better info about the state of a project I was blabbering about in The State of a Project. You know exactly if there is currently no selected project, even if the internal timer is running (which is reflected by the icon in the Start/Stop Timer toolbar item).
You can select, what GTimeTracker should display in the main window, here.
You can tell GTimeTracker, if you want the seconds to be displayed in the project list. If seconds are shown, the time displayed in the project list looks like 00:12:47 (hours:minutes:seconds). If not, you just see 00:12 (hours:minutes).
If you're using a GNOME version of GTimeTracker, you can select how the toolbar should look. You can chosse to display icons and/or a text.
Just choose, if you want the status bar to be displayed.
This shell command will be executed every time you select a project, which was previously unselected. If you use %s in this command, GTimeTracker will replace that by the title of the selected project. I use the following entry to update my .project file:
echo '%s' >~/.project
This shell command will be executed every time you deselect a project or if you exit GTimeTracker. To complete the example above, I use this command:
rm -f ~/.project
You have to enable this, if you want a logfile.
Give a filename for the logfile. GTimeTracker currently does not replace $HOME or ~. You should give the complete path to the logfile.
This value represents the minimum time a project has to be selected, before it will be logged. This is usefull, when you don't want any small task to be logged, or when you clicked on the wrong project first. Let's say, you just wanted to start working on a letter to your friend Joe (so you selected the project Letter to Joe), but that reminds you, that you have to prepare a list of Christmas presents first (Joe has asked you to give him some good ideas). So you switch to the project X-Mas presents. You wouldn't want the project Letter to Joe to be in your logfile, because you didn't really start it yet. I would suggest you set this value at least to 10 seconds.
Note that a project will not get logged, before you either quit GTimeTracker, switch to another project, or deselct that project. So don't be confused when you look at your logfile and your current project still isn't listed, even if it is running since two hours.
If you are pleased with the values of the dialog, press OK to make them active and have the dialog go away.
If you want to apply these values just for a given task and plan to reopen the dialog again, you can press on Apply to activate the values. But the dialog will remain open.
If you don't want to change to working values, you just press Cancel. That will close the dialog, but will not change the behavier of GTimeTracker in any way. I recommend using Cancel even if you didn't change anything.
This dialog shows you all values that are internally stored with a project.
Note that this is the only way to examine the overall time yet.
You can change the title of a project here.
You can give the project a more detailed description if you like. Up to now this value will never be used by GTimeTracker
This is the daily time, you worked on the project today. You can edit this time here.
This is the total time, you worked on a project. You can edit this time here.
See OK, apply and Cancel for the meaning of the buttons at the bottom of the dialog.
This dialog is fairly small. It just wants to know, how you want to entitle the new project. Just enter a title of the new project and press OK, if you are satisfied. Or press Cancel if you changed your mind and don't want GTimeTracker to add a new project.
I haven't finished this chapter yet. I just include it here to make my SGML parser happy about the links to the sections here.
This section isn't finished yet.