Stopwatch v0.1.0


Stopwatch is a rather basic timer, with both a command line and graphical user interface (GUI). In addition to the usual start, stop, reset and clear (new) functions, Stopwatch implements a rather large number of lap timers - 27 in the GUI mode, limited only by memory from the command line.


Stopwatch is written in Python using the GTK+ libraries, and should run on just about any modern computer. It has been tested on Windows 98 and XP, Ubuntu Linux (Breezy Badger x86), and the Nokia 770 Internet Tablet (OS 1.0).

Stopwatch requires Python and (to use the Graphical User Interface, or GUI) the GTK+ runtime. Install Python first, then (if needed) GTK+, and finally Stopwatch.

Windows installation is via the usual "installation wizard" (for better or worse). An rpm package is available for Linux. The source code is available as a ZIP file, and is trivial to set up directly (just unzip wherever convenient, and add a link from your applications menu to the file).

Using the GUI

The GUI is best launched using in the installation directory.

The GUI consists of a standard menu bar, a large main timer display flanked by Start and Reset buttons, and a table of 27 lap timers. When first launched, the stopwatch is stopped (that is, not measuring elapsed time).

Just click Start to begin timing. Start will then be relabeled Stop, which may be clicked to stop the timer (and relabel the button Start...). You may also use F8 (or Tools->Start) and F9 (or Tools->Stop) to start and top the timer, respectively.

While running, the timer is accurate to 1/100th of a second regardless of computer interruptions, glitches, or even crashes (as long as you saved the running timer to a file before the crash). Inaccuracies may result in starting and stopping the timer as a result of heavy work loads on the processor, however.

Below the main timer is a set of 27 lap timers in 3 columns, each consisting of a label (like "Lap 1") and a button. Each label is simply a text entry field, and may be edited in the usual way (that is, double-click or swipe the existing label with the mouse, then type something else and press Enter). Clicking a button will record the current timer value as the button label. To reuse a lap timer, just click the button again; the old lap time is discarded, and the current timer value becomes the new lap time and is displayed on the button label.

Lap timer labels may be cut, copied or pasted using the Edit menu items of the same name, or the standard Control-X, Control-C and Control-V shortcuts respectively. The lap timer values may also be copied when the associated button has focus (that is, when the lap time is enclosed by a dashed box). To put focus on a lap timer value without recording a time, click on the label to its left, then press Tab. The main timer cannot accept focus, but can be copied to the clipboard directly by using Edit->Copy Time or Control-Alt-C.

File->Save (As) and File->Open work as expected, but note that if you save a running timer, it will still be running when you open that file again (and the intervening time will have been counted!). The file format is CSV, which can be edited by any competent text editor or spreadsheet program. If a file being opened contains less than 27 lap timers, the unused lap timers will receive the default label and be unset; anything in the file after the first 27 lap timers in the file will be completely ignored.

File->Open Template will open the CSV file and load the lap timer labels only, setting the timer and lap times to zero. This is useful for quickly configuring Stopwatch for the task at hand by pre-labeling the lap timers. Note that template files are not special; any CSV file saved by Stopwatch can be loaded as a Template.

On the right of the main timer display is the Reset button, which clears the timer display and lap timer values but not the lap timer labels. If you want to reset the lap timer labels to their defaults as well, use File->New (or Control-N).

The rate at which the main timer is updated is controlled by the View menu (on a slow or busy CPU, you may not want to burn a lot of processor time making the numbers whiz by). View->Refresh Fast updates the display about every hundredth of a second; View->Refresh Slow about every tenth of a second; and View->Refresh Off updates the display exactly once. Turning off the refresh doesn't affect the timer at all; it continues counting with admirable accuracy. To manually update the display when refresh is off, just select View->Refresh Off again. When you stop the timer, the current timer value will also be refreshed.

Using the Command Line

The command line version is best launched using

The command line version first presents a list of available commands, then waits for and executes commands as they are entered. The command prompt consists of the current timer value, followed by the status of the timer (either "(running)" or "(stopped)"). Thus, pressing Enter with no command results in a new prompt containing an update on the timer value.

The following commands are available. * "s" will start the timer, if it is not already running. No additional information (beyond the subsequent command prompt) will be given. * "x" will stop the timer, if it is running. No additional information will be given. * "d" will display the current filename (if one has been set via the "r" or "w" command), the current time, and the name and associated lap time of each of the lap timers in alphabetical order. * "w filename" will write the timer value and lap timer values to a CSV format file. If a filename has already been set via an earlier "r" or "w" command, filename may optionally be omitted. * "r filename" will read the specified file, creating a new stopwatch to contain the data (any existing stopwatch is discarded). If the timer was running when the file was written, the new timer will also be running, and all time elapsed since the file was written will be counted in the current timer value. If a filename has already been set via an earlier "r" or "w" command, filename may optionally be omitted (this is equivalent to reverting to the original values in the file). * "h" will again display the brief help message shown when the program was first started. * "exit" will exit the program to the command line. * Any other text entered will be accepted as the name of a lap timer. The specified lap timer will be created (if it doesn't already exist), and will be set to the current timer value. The only limitation on the number of lap timers is available memory. Lap timer values may be displayed using the "d" command. It is a Bad Idea to create lap timer names that contain commas.

On most Linux shells, pressing Control-Z and then entering the bg command to the shell will put the timer in the background, allowing other work to continue (the timer continues to run). Entering the fg command will activate the timer again, ready for a command (press Enter to see the prompt). Placing the timer in the background is guaranteed not to affect timings in progress.

File Format

Both the command line and GUI versions of Stopwatch share an identical file format. Opening a file saved from Stopwatch in your favorite spreadsheet program should make the file format.

The first line is the program name - 'Stopwatch'. The second line is the version number of the Stopwatch program that wrote the file - '0.1.0' (the only released version to date).

The third line will be either 'running' or 'stopped', to indicate whether the Stopwatch was running when this file was saved or not. If 'running', then the Stopwatch will still be running when the file is reloaded.

The fourth line is the time of the epoch (in seconds) when the Stopwatch was most recently started. The fifth line is the elapsed seconds counted before the most recent start of the Stopwatch. If the Stopwatch is still running, then the current total elapsed time is '(NOW - start_time) + elapsed_time'; if the Stopwatch is stopped, then the current elapsed time is just 'elapsed_time', and start_time is ignored.

Lines 6 and later are name / value pairs for the lap timers, separated by commas (or, in a spreadsheet, in adjacent cells). The GUI version will ignore any lines after line 32 (that is, 27 lap timers), but the command line version will not. Thus, unless you use only the GUI version, it's a Bad Idea to put non-Stopwatch information below line 32.


Version Author / Maintainer Release Date Changes
0.1.0 George F. Rice 2006-Mar-21 Initial (experimental) release.

Like all worthwhile things in life, this program resulted from a Good Woman. Stick with me and you'll understand.

I've been a Palm Treo fan for many years, but had stalled at the Treo 300 - all subsequent versions included cameras, and my job ("if I describe it, I'll have to shoot you") doesn't permit cameras. The next version of Palm (coming soon, or so I heard - repeatedly) was Linux-based, and since I'm also a Linux fan, I waited with bated breath.

It didn't come.

So as hope faded for a Linux-based Treo to arrive before my 300 crumbled to dust, I began searching for a good Linux-based computer that would fit in my pocket to use instead. I found a few practical options, but at nearly $1000 a pop, I couldn't tear the credit card out of my wallet (yes, I'm tight, even when it comes to Toys).

The Nokia 770 was a fascinating new option, despite being a "version 1.0" product. My wife Janet noticed the drool marks on my computer desk while browsing (honest!), and bought one for me as a 19th anniversary present (no, you can't have her - she's mine).

Almost immediately, I found a need for a good stopwatch. First, our Destination Imagination team needed to practice finishing in exactly 7 minutes - not one second more. More critically (and uniquely), my son's Scout troop began work on the Personal Fitness merit badge, and I needed to record the lap times for 20 Scouts running laps around the parking lot.

Since I couldn't find a stopwatch at Target with 20 independent lap timers, I decided to write one. And my shiny new Nokia 770 seemed like the ideal host, since it spoke fluent Python / GTK+ (according to the website), and we recently began using Python at work. Now you understand why a Good Woman resulted in this program - and why it has so darned many lap timers with custom labels!

I hope you enjoy using this program as much as I have writing it (while learning Python and GTK+).

I would enjoy reading your comments and suggestions. Please visit me at when you have a moment. Logo