Clockwork User Guide

For Mac users who sometimes forget. Clockwork is the desktop timer that will keep you ontime and in style. Unlike the alternatives, Clockwork packs its punch in a clean and easy-to-use interface that looks great on your desktop. Requires Mac OS X 10.4 or later.

Getting Started

System Requirements

Clockwork requires Mac OS X 10.4 or later to run.

Installing Clockwork

To install Clockwork, simply copy the application to your /Applications folder. If you want Clockwork to wake your computer from sleep you will need to enter your administrator password and check “Alarms wake computer from sleep” in Clockwork’s preferences.

Enter License

When you purchase Clockwork you will receive an email with a license file attached. If you lose your license you can get it resent to you by entering your email address on this page.

To install this license double-click it or drag and drop it onto Clockwork’s icon. Clockwork will then display a dialogue letting you know that the license is installed. Once your software is licensed you will see your name in Clockwork’s About box.

Upgrading from Hog Bay Timer

We are moving to a donation based upgrade system. Upgrades are free but I ask that you donate if you find the new features useful. This makes things easier and simpler for everyone.

Unfortunately this time around the upgrade process for existing Hog Bay Timer users going to be a bit of a pain :(. The problem is that the new license key system requires that you are in our new order system, but I don’t want to charge you for this update. To get around this and get your new license for free please follow these instructions:

  1. Add Clockwork to your shopping cart.

  2. Next checkout your shopping cart. You will be asked to enter a billing address. Even though you won’t be charged for this order (follow instructions below) we need the billing address so that we can generate a unique license key.

  3. After entering your billing address you will be sent to the “Order Summary” page. Choose the “Continue to payment details button”, that will send you to Pay-Pal.

  4. At this point our order system has enough information to issue a new license. Important You have only completed the process when your browser goes to the www.paypal.com site, if you stop before that the transaction isn’t recorded and we don’t have enough information to generate a license key. You shouldn’t complete the payment with Pay-Pal since I don’t want to charge you for this upgrade. Instead please send me an email with your Hog Bay Timer license key and I’ll manually authorize your order (as if you had paid) so that your new license will be sent out.

I’m sorry that this upgrade process had to be such a pain, and I hope you like all the new features in Clockwork.

Visual QuickStart

Clockwork Labeled Screenshot

  1. Display Time The display time of the selected timer.
  2. Timers View List of all timers, the selected timer is highlighted blue.
  3. Add/Remove Timer Insert a new timer, or remove the selected timer.
  4. Timer Controls Start/Stop, clear, and change mode of selected timer. Selected timer must be Stopped before it can be changed.
  5. Show Info Drawer Toggle display of the info drawer.
  6. Show Tenths of Seconds Toggle display of tenths of seconds.
  7. Alarm Actions List of available alarm actions. All checked actions will be run when the timer reaches zero. You can add new alarm actions will plugins or scripts.
  8. Repeat Mode The repeat mode used to reschedule alarms that have reached zero.

Using Clockwork

Stopwatches & Alarms

Clockwork manages a collection of timers for you. To create a new timer:

  1. Choose the menu File > New.
  2. The new timer is created and you can now give the timer a name.

Each timer can be in either stopwatch or alarm mode. When a timer is in stopwatch mode it counts up from zero until you stop it. Stopwatch mode is useful for recording how long something takes. When a timer is in alarm mode it counts down until it reaches zero. When the time reaches zero the alarm will trigger an alarm action.

To change a timers mode:

  1. Make sure that the timer is stopped, otherwise mode changing is disabled.
  2. Choose the menu item Timer > Mode, or click on the mode button in Clockwork’s interface.

Setting Alarm Actions

Each alarm is associated with a list of actions that it will perform when it reaches zero. By default all new alarms have an action that will show an alert dialogue when the alarm reaches zero. The alarm actions for the selected timer are listed in the Info Drawer. To show the info drawer:

  1. Choose the menu View > Show Info Drawer.

Each alarm action in the list has a checkbox next to it, the actions that are checked will be run when the selected alarm counts down to zero. Note that the alarm action list will be disabled when a timer in stopwatch mode is selected, since only timers in alarm mode will trigger alarm actions.

By default there are only two alarm actions, but you can use applescript and plugins to create your own custom alarm actions. Visit the contribution section to find script and plugins that customize Clockwork.

Setting Alarm Repeat Rules

Alarms can also have a repeat rule. This rule is used to reschedule the alarm after it has reached zero. The current repeat rule for the selected alarm is displayed in the Info Drawer under the list of alarm actions. Here’s how you can create an alarm that will remind you to take a break and stretch every hour:

  1. Choose the menu File > New to create a new alarm.
  2. Give the alarm a name such as “Take a Break!!!”.
  3. Use the menu Timer > Mode to change the timer from stopwatch mode (default for new timers) to alarm mode.
  4. Use the menu View > Show Info Drawer to show the info drawer.
  5. At the bottom of the info drawer select the repeat rule “1 Hour”.
  6. Now start the alarm (Timer > Start).

After starting the alarm you will see an immediate alert, since you started the alarm with zero time on it. Then (because of the repeat rule) you will see the alarm restart itself with the time of 1 hour. It will continue restarting itself until you stop the timer.

Working with Clockwork

Clockwork tries to provide enough options to be fast and useful, but not overwhelming.

Setting the Time

Clockwork provides a number of ways to set a timers time from both the keyboard and with your mouse. To set the time with your mouse:

  1. Make sure that the timer is not running, if it is running stop it with the menu item Timer > Stop.
  2. Once the timer is stopped set the time by clicking on the timer face numbers. Click once to highlight the number, once highlighted each new click will make the number go up by one. Hold down the shift key to instead make the number go down by one.

To set the time with the keyboard:

  1. First make sure the timer is stopped, since you can’t change the time of a running timer.
  2. Next click on the timer face number that you wish to change so that it is highlighted.
  3. Once the number is highlighted you can use the keyboard to enter a new time. Or you can use the up and down arrow keys to make the number go up or down.

Note that you can use the Tab key to quickly move the keyboard focus so that you can edit a different number.

To set the time with keyboard shortcuts:

  1. First make sure the timer is stopped, since you can’t change the time of a running timer.
  2. Now use the keyboard shortcuts defined in the Timer menu to increase and decrease the time.
Changing the View

Clockwork comes with a number of different view options that can be set from the View menu:

Note, you can quickly switch between Multiple Timers and Mini Timer views by clicking on the windows green “zoom” button.

Preferences

Clockwork has a number of preference panes. To open the preferences window:

  1. Choose the menu Clockwork > Preferences.

The “Wake & Startup” preference pane lets you tell Clockwork to wake your computer from sleep when an alarm goes off. Selecting this option requires you to first unlock the preference pane because Clockwork is not allowed to wake your computer from sleep without your permission.

The “Software Update” preference pane lets you check for new versions of Clockwork when you have an internet connection. By default Clockwork will check for updates when you start the application.

The “Plugin Config” option shows you what Clockwork plugins are currently installed.

Plugins & Scripts

Clockwork can be automated and customized with scripts and plugins. You can find Clockwork plugins and scripts here. To install a plugin drag and drop the plugin onto Clockwork's application icon.

Writing Scripts

Clockworks interacts with your AppleScripts in two ways. First it supports a scripting dictionary that allows you to control Clockwork from your script. Here’s a simple script that illustrates those capabilities:

tell application "Clockwork"
    -- get selected timer
    set t to selected timer

    -- many properties can only be changed when a timer is stopped
    stop t

    -- access each timer property
    log days of t as string
    log alarm date of t as string
    log start date of t as string
    log seconds of t as string
    log minutes of t as string
    log running of t as string
    log display time of t as string
    log step interval of t as string
    log subseconds of t as string
    log hours of t as string
    log name of t as string
    log mode of t as string

    -- clear time, set to five minutes, set alarm mode and start.       
    set display time of t to 0
    set minutes of t to 5
    set mode of t to alarm

    -- finish up by starting t
    start t
end tell

Second Clockwork can call your scripts when certain events happen. A simple example of this is when you select a script in the script menu, but a more interesting example is when an alarm timer reaches zero. When the alarm reaches zero the handler “performAlarmAction” will be called in each applescript that is checked in the alarm actions table for that timer. For example:

-- This script implements the performAlarmAction event. To use:
--  1. Move this script into Clockworks Scripts folder (Script Menu > Open Scripts Folder)
--  2. Restart Clockwork
--  3. Create a new alarm and open the "Alarm Actions" drawer. Check the box next to this script in the alarm actions table.
--  4. Start the alarm.
--  5. When the alarm finished this scripts performAlarmAction handler should be called.
using terms from application "Clockwork"

    on alarmStarted(anAlarm)
        log "started " & name of anAlarm
    end alarmStarted

    on alarmStopped(anAlarm)
        log "stopped " & name of anAlarm
    end alarmStopped

    on alarmFinished(anAlarm, anAlarmDate)
        log "finished " & name of anAlarm & " on " & anAlarmDate
    end alarmFinished

end using terms from

This can be used to create a “Yoga timer”. A Yoga timer needs a custom repeat interval because you are supposed to hold positions for (in this case) 20 seconds and then 40 seconds. You can do this with Clockwork with this script:

-- Yoga alarm. 
property repeatInterval : 20

using terms from application "Clockwork"

    on alarmStarted(anAlarm)
        log "started " & name of anAlarm
    end alarmStarted

    on alarmStopped(anAlarm)
        log "stopped " & name of anAlarm
    end alarmStopped

    on alarmFinished(anAlarm, anAlarmDate)
        stop anAlarm
        if repeatInterval = 20 then
            set repeatInterval to 40
        else
            set repeatInterval to 20
        end if

        set seconds of anAlarm to repeatInterval
        start anAlarm
    end alarmFinished

end using terms from

Writing Plugins

Clockwork is built on the Blocks plugin framework. When you download the Blocks framework you also get a SDK that contains a number example plugins, including example Clockwork plugins.

Release Notes

Upgrades are free for registered users, but I ask for donations when you find the new features useful. If you see a new feature that you find useful please let me know by donating. Thanks.

June 19, 2007 - Clockwork 1.4.2

January 23, 2007 - Clockwork 1.4.1

January 11, 2007 - Clockwork 1.4

November 9, 2006 - Clockwork 1.3

Sept 1, 2006 - Clockwork 1.2

Aug 18, 2006 - Clockwork 1.2b

May 18, 2006 - Clockwork 1.1

May 8, 2006 - Clockwork 1.1 Beta

December 1, 2005 - Clockwork 1.0

July 17, 2005 - Clockwork '05 Beta v25

July 11, 2005 - Clockwork '05 Beta v24

June 15, 2005 - Clockwork '05 Beta v22

June 1, 2005 - Clockwork '05 Beta v19

May 24, 2005 - Clockwork '05 Beta v14

May 18, 2005 - Clockwork '05 Beta v13

May 16, 2005 - Clockwork '05 Beta v12

April 13, 2005 - Clockwork '05 Beta v11

April 3, 2005 - Clockwork '05 Beta v9

Keyboard Shortcuts

These are the Clockwork specific keyboard shortcuts. Look in Clockwork’s menus to find the standard OS X shortcuts that are supported.

Action Shortcut
Start / Stop Return or Cmd-Return
Clear Shift-Cmd-C
Mode Shift-Cmd-M
Increase Hours Up Arrow or Cmd-1
Decrease Hours Down Arrow or Option-Cmd-1
Increase Minutes Up Arrow or Cmd-2
Decrease Minutes Down Arrow or Option-Cmd-2
Increase Seconds Up Arrow or Cmd-3
Decrease Seconds Down Arrow or Option-Cmd-3
Multiple Timers Cmd-[
Mini Timer Cmd-]
Full Screen Timer Cmd-\

Menu Commands

Application Menu

About Clockwork Show information panel with Clockwork’s version information and license status.

Preferences Open Clockwork’s preferences panel.

Services Display the OS X services menu. Services are one way that OS X applications can share information. This menu can get unwieldy, but donationware Service Scrubber can help solve that problem.

Hide Clockwork Hide all open Clockwork windows.

Hide Others Hide all open windows on your desktop except for those belonging to Clockwork.

Show All Restore and display all hidden windows.

Quit Clockwork Quit Clockwork. Your current timers will be saved and will continue to run, but you won’t be notified if an alarm sounds until the next time you open Clockwork.

File Menu

New Create a new timer.

Close Close the front-most window.

Timer Menu

Start Start the selected timer.

Clear Clear the selected timer’s time to zero. You can only clear a timer that is stopped.

Mode Toggle the selected timer’s mode. Stopwatch mode will count up from zero. Alarm mode will count down until the time reaches zero. When an alarm reaches zero its alarm actions will run and if a repeat rule is set the alarm will be restarted. You can only change the mode of a timer that is stopped.

Increase Hours/Minutes/Seconds Increase the display time. You can only change the display time if the timer is stopped. You can also change the display time by clicking on the time digits and entering numbers with the keyboard.

Decrease Hours/Minutes/Seconds Decrease the display timer. You can only change the display time if the timer is stopped. You can also change the display time by clicking on the time digits and entering numbers with the keyboard.

View Menu

Multiple Timers Select the default view mode. This mode allows you to view and manage multiple timers at the same time.

Mini Timer Displays the selected timer in a mini view that takes up less desktop space. Your other timers will continue to run in the background.

Full Screen Timer Displays the selected timer in full screen mode so that it’s visible across the room.

Show Tenths of Seconds Show tenths of seconds for the selected timer. This gives a more accurate display, but takes more computer power.

Show Alerts Window Show the alert window. The alert window contains a list of alert messages that are created when an alarm finishes.

Window Menu

Floating Window Check to make the current window float above all other windows, even when Clockwork is not the frontmost application.

Script Menu

Open Scripts Folder Open folder that contains the applescripts used to build scripts menu.

Update Scripts Menu Update script menu to reflect contents of the scripts folder.

Help Menu

User Guide Open the online user guide.

User Forums Open the online user forums.

Plugins & Scripts Browse plugins and scripts available for Clockwork.

Request New Feature Open online form to request a new feature.

Report New Bug Open online form to report new bugs.