# yesClock

#### 1.3.2

Current release (1.3.2, unix)
Current release (1.3.2, dos)

## Overview

### Abstract

yesClock is an application based on the Yes watch. The Yes watch uses a novel approach to displaying time, showing where in the day you are rather than just the time. The Yes watch approach, used by this companion yesClock software application for your desktop, is a way of measuring time that is more intuitive and natural than any other.

### Introduction

I'm a watch fanatic.

I love and collect watches. Normally, my tastes run to Jaeger LeCoultre, Movado, Maurice Lacroix, and Breguet. I tend to like the classics; white or light backgrounds, gold trimmings, analog rather than digital. Movado's Visio line is very attractive, as is Jaeger's "Chronograph" series; my current favorite watch, however, is the Breguet "Grande Complication" which ranges in price, unfortunately, from $100,000 to $150,000. I've seen Breguets list for a half million. They make them out of platinum. What the heck do you do with a half million dollar watch? Watch your jeweler develop a nervous tick? They are, despite the prices, marvelously beautiful timepieces. By the way, I don't own a watch that costs over $300 -- yet. I doubt I'll be buying a watch in the thousands anytime soon, but that isn't to say I wouldn't like to have one of these masterpieces.

Anyway, the point is that I don't normally go in for digitals, until I saw the yes watch. This thing is great. It displays the entire day as a shaded arc. The shaded part is when it is dark; the not shaded part is when it is light. The terminators are the sunrise and sunset, respectively. There is a single hand showing you where in the day you are. The whole thing makes a wonderful kind of sense, and since you can set it to also show the time digitally, you the regular time as well. You can tell what time it is by the hand position just as well as you can with a regular analog watch; I have a Movado that only has two hands and a gold dot where 12:00 is, and telling time with the yes watch is just as accurate than that. The best thing about the watch is that it is affordable, without being cheap. The watches run around $300, and they are fully featured, with alarms, multiple time zones, etc. If you like this application, visit yes watch's website and check out their wares. The watches are very nice.

I have a further reason for liking the yes watch: decimal time. I like the thought of decimal time, such as the BMT promoted by Swatch. The only problem with decimal time is that it doesn't provide any perspective to your daily life. Sure, the time is 500 everywhere in the world at the same time, which makes it nice for coordinating with people in different timezones, but it doesn't help you tell when park closes? When is lunch? If you travel to Paris, France and your home town is Boring, Oregon, USA, you still have to do conversions to figure out when the Bistros open. The yes watch pairs with digital time wonderfully, because it provides the perspective that EDT lacks.

I wrote this program so that I could have a desktop companion for the yes watch. It is fairly close to what you get with the yes watch, although it isn't as attractive as the watch. If you have a yes watch, or are going to get one, yesClock should make a good addition to your desktop applications.

### Features

- Digital time displayed in either EDT or Standard time
- Displays "yes" style sunrise and sunset
- Displays true solar noon and midnight
- Displays markers for full "hour" units, with special colored "jewels" for midday and midnight.
- Drawn with fully scalable vector graphics
- Includes a city list for choosing latitude/longitude, plus allowing for manual entry of lat/long
- Preferences (EDT/Standard, lat/long) are saved
- Functions as a desktop application, or as a web applet
- Time hand shape is configurable
- Dump to PNG image from the command line

## Screenshots

Bend, Oregon, U.S.A.
Decimal time
Preferences
Solar noon in Alaska in March is after 13:00!
A hand in the shape of the sun shows the sun just about to rise in Alaska

## Operation

### Requirements

Java 2, 1.2 or greater.

### Application

Rather than downloading the entire archive, you can now just download the executable jar file and run it. You'll also need the common jar file in the same directory. This jar file only contains the application classes -- no documentation. You don't need to unpack it. If you're on Windows and have Java2 installed, you should be able to just save the jar file to your desktop and double-click on it. If you run Linux and you have your binfmt_misc set up properly, you can also just run it like any other application. Otherwise, use the instructions below.

To run the application, use the `-jar` option on the JVM and use the `yesClock.jar` file.

    java -jar yesClock.jar

Right-click anywhere in the window to get the menu. The menu has entries for configuration, changing the hand shape, changing the time display, and exiting the application. You may also quit the application by closing the window. You can specify the size of the starting app with the `--size` argument. The following will cause yesClock to open with a 200 pixel wide by 300 pixel tall window.

    java -jar yesClock.jar --size 200 300

You can also dump a snapshot of the current time to a PNG image file with the --dump argument.

    java -jar --size 1024 768 --dump current.png

This is useful for generating desktop backgrounds. KDE, in particular, has support for this sort of background generation.

### Applet

To embed this as an applet in a web page, add the following HTML code to the web page where you want the applet to appear. The files yesApplet.jar and yesCommon.jar must be in the same directory as the page that is embedding the applet, or you must specify where the jar files are in the APPLET tag. You can set the width and height of the applet to just about anything you like; the clock will scale to the appropriate size. You can also specify either EDT or Standard time with the `edt_on` flag. Set it to `true` for EDT time, or don't include the parameter or set it to `false` to use standard time.

    <APPLET WIDTH="200" HEIGHT="200" CODE="YesApplet.class"
    		ARCHIVE="yesApplet.jar,yesCommon.jar"
    		WIDTH="200" HEIGHT="200">
    	<PARAM NAME="longitude" VALUE="-121.31104"/>
    	<PARAM NAME="latitude" VALUE="44.06604"/>
    	<PARAM NAME="edt_on" VALUE="true"/>
    <APPLET>

### Configuring

Dynamic configuration is only available in the application.

There are three main configuration options. The first, accessed under the menu item "Configuration", allows you to change your geographic location and your time zone. You may want to change the time zone if you notice a skew in the time; on some computers the Java VM doesn't get the correct timezone from the operating system, so you may have to set this by hand. In the configuration window is a list of cities, and some text entry fields. Choosing a city will put the values for that city into the text entry field, and you can tweak them by hand if you like. If you select the `Cancel` button, your changes will be discarded. If you select the `Save` button, your changes will take effect, and your configuration will be saved to a file called `.YesClock` in your user home directory. This is a plain text file which you can edit by hand, or delete if it becomes corrupted.

The second configuration option is the time display; this toggles between Standard Time (24 hour day, 12 months a year, various days a month, years, local time zone) and EDT (years, 365 days a year, and 1000 ticks per day, universal time zone.) See the "Time format" section below for more information.

The third configuration option is the hand shape. Choosing this menu item will open a window displaying the various hand shapes available for selection. Choose one of these and click the `Save` button, and that shape will be used as the hand for the clock. If you click `Cancel`, your selection will be discarded. There is also a `Reload` button, which you can use to see a preview of your hands as you edit them. See "Adding hands" below for information about adding shapes.

### Adding hands

You may define your own watch hand shapes; it is not trivial, but it isn't hard once you understand the basic rules. First, you must create a file in your user home directory (the same directory that includes the `.YesClock` config file) named `.YesClockHands`. This file is a PYX file, and has the basic format:

    (hands
    (hand
    Aname someName
    ...
    )hand
    )hands

To add a new hand, add a new "(hand" entry. Drawing commands are given after the "Aname" line, and before the ")hand" line. Each "(hand ... )hand" section defines a hand shape. Multiple hand shapes can appear in a single file, but the "(hands" line must start the file, and the ")hands" line must end it.

Hands are drawn with a simple logic and three basic operations: move, line, and quad. Operations are drawn in the order they are encountered. Move moves the "cursor" to a location without drawing a line. Line draws a line from the last point to a new point. Quad is a quadratic curve, defined by three points: the starting point, the ending point, and a control point. Quad is the most difficult to work with, but allows you to draw smooth arcs and curves. You may also change the color of the fill and the border of the shape. All command lines must start with a '-' and have no extra space between the command and the "-". The following lists the commands and their arguments.

    m x y          -- Move to point (x,y)
    l x y         -- Draw a line to point (x,y)
    q x y x2 y2   -- Quad arc to (x2,y2) with control point (x,y)
    s #rrggbb     -- Shape border in color #rrggbb (like HTML hex colors)
    f #rrggbb     -- Shape fill in color #rrggbb (like HTML hex colors)
    c             -- Close the path (line to where you started

Here is an example of a path; this will draw the default watch hand shape:

    (hand
    Aname Default
    -m 0 -5
    -l -7 -15
    -l -3 -18
    -l -5 -20
    -l 0 -100
    -l 5 -20
    -l 3 -18
    -l 7 -15
    -c
    )hand

This moves to (0,-5), draws a line from there to (-7,-15), draws another line from there to (-3,-18), and so on, until it ends back up at the starting point (0,-5) again.

Here is a more complex example; this will draw the "Fancy" watch hand shape:

    (hand
    Aname Fancy
    -m 0 7
    -q 10 -10 -5 -10
    -l -2 -70
    -q -10 -70 -3 -90
    -l 0 -100
    -l 3 -90
    -q 10 -70 2 -70
    -l 5 -10
    -q -10 -10 0 7
    -c
    )hand

Remember to close your shapes! A box has 5 points, not four, because the start point must also appear at the end, or you must '-c' close it. Closing the path produces a better join, and '-c' can appear anywhere in the file.

### Time format

EDT.

### User Submitted Hands

I'll be linking to user submitted hand shapes here. To use them, copy and past the hand entries into your `~/.YesClockHands` file.

## Status

### Change Log

- 1.3.2: Added a map to the config panel, for selecting lat/lon values.
- 1.3.1: Made the border for the hand list thicker. Added the names of the hands to the list widget. Fixed the double-buffering thing -- no more flashing (how did I miss this in the first place??). Added another (fairly nice) hand. Added the 'c' close path command, and changed the stroke join from miter to rounded; it looks better. Broke up the jar files; this reduces the size of the distribution, but requires users to download two files if they're only interested in the binary. Documentation fixes. Had to remove the jar distribution, because, once again, JavaSoft has proven their complete incompetence by not including an "exclude" option in 'jar'. Duh.
- 1.3.0 Features added. The hands are now configurable. Added `--dump` and `--size` arguments.
- 1.2.0 Bug fixes. Added a timezone function, as a fix for the problem where the JVM isn't picking up the proper timezone from the OS. Changed the menu title for "Location" to "Configuration". Updated the screenshots. Fixed some problems with the config panel.
- 1.1.0 Initial release

### Troubleshooting

If you should observe really strange behavior in the application, such as the hand and the sunrise/sunset settings look really wrong, you may be having a problem with your timezone. I've observed that, on some machines, the JVM doesn't get the right timezone from the operating system. Make sure you check the zone settings in the preferences for accuracy.

The clock automatically adjusts for daylight savings time (DST). If you observe that the times seem wrong, it is probably this. There is no fix yet.

### Known Bugs

- I suspect I'm going to have to add a DST adjuster to the configuration, too.

### To Do

- Add toggle for digital time display
- Add a "hand_name" param to the applet
- Add moon phases (as with the yes watch)
- Add a moon hand
- Allow users to customize colors
- Add twilight
- Save the window position
- Document the sourcecode better
- Add --dump and --size for embedding in desktop
- Make the border for the selected hand thicker
- Add the names of the hands to the hand list widget
- Add configurable hands

### Requested features

- Change the hand to SVG->PYX format.
- Add real shadows for hands and text
- Add display for additional time zones
- Add a world map for selecting lat/lon/tz

## Credits

- The astronomy functions are based on sunriset.c by Paul Schlyter
- The yes watch provided the inspiration for this project