<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet type="text/css"
href="../documentation/documentation.css"
?>
<!DOCTYPE documentation SYSTEM "../documentation/documentation.dtd">
<documentation>
  <head>
    <title>yesClock</title>

    <version>1.3.2</version>

    <date>*2002-073</date>

    <home>http://germane-software.com/software/yesClock</home>

    <base>yesClock</base>

    <archive type="unix">Current release</archive>

    <archive type="dos">Current release</archive>

    <author email="ser@germane-software.com"
    href="http://www.germane-software.com/~ser">Sean Russell</author>
  </head>

  <overview>
    <purpose lang="en">
      <p>yesClock is an application based on the <link
					href="http://www.yeswatch.com/share/cgi-bin/site.cgi?site_id=yeswatch&amp;page_id=home">Yes watch</link>. 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.</p>
    </purpose>

    <general>
      <p>I&#39;m a watch fanatic.</p>

      <p>I love and collect watches. Normally, my tastes run to Jaeger
      LeCoultre, <link href="http://www.movado.com">Movado</link>, Maurice
      Lacroix, and <link href="http://www.breguet.com">Breguet</link>. I tend
      to like the classics; white or light backgrounds, gold trimmings, analog
      rather than digital. Movado&#39;s Visio line is very attractive, as is
      Jaeger&#39;s &#34;Chronograph&#34; series; my current favorite watch,
      however, is the Breguet &#34;Grande Complication&#34; which ranges in
      price, unfortunately, from $100,000 to $150,000. I&#39;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&#39;t own a watch that costs over $300 --
      yet. I doubt I&#39;ll be buying a watch in the thousands anytime soon,
      but that isn&#39;t to say I wouldn&#39;t like to have one of these
      masterpieces.</p>

      <p>Anyway, the point is that I don&#39;t normally go in for digitals,
      until I saw the <link href="images/Watch.jpg">yes watch</link>. This
      thing is great. It displays the entire day as a <link
      href="images/shaded.svg">shaded arc</link>. 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 <link
				href="http://www.yeswatch.com/share/cgi-bin/site.cgi?site_id=yeswatch&amp;page_id=home">yes watch&#39;s website</link> and check
      out their wares. The watches are very nice.</p>

      <p>I have a further reason for liking the yes watch: <link
      href="http://www.germane-software.com/software/edt">decimal time</link>.
      I like the thought of decimal time, such as the BMT promoted by <link
      href="http://www.swatch.com">Swatch</link>. The only problem with
      decimal time is that it doesn&#39;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&#39;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.</p>

      <p>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&#39;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.</p>
    </general>

    <features lang="en">
      <item>Digital time displayed in either EDT or Standard time</item>

      <item>Displays &#34;yes&#34; style sunrise and sunset</item>

      <item>Displays true solar noon and midnight</item>

      <item>Displays markers for full &#34;hour&#34; units, with special
      colored &#34;jewels&#34; for midday and midnight.</item>

      <item>Drawn with fully scalable vector graphics</item>

      <item>Includes a city list for choosing latitude/longitude, plus
      allowing for manual entry of lat/long</item>

      <item>Preferences (EDT/Standard, lat/long) are saved</item>

      <item>Functions as a desktop application, or as a web applet</item>

      <item>Time hand shape is configurable</item>

      <item>Dump to PNG image from the command line</item>
    </features>

    <screenshots>
      <screenshot href="images/shot1.png">Bend, Oregon, U.S.A.</screenshot>

      <screenshot href="images/edt.png">Decimal time</screenshot>

      <screenshot href="images/prefs.png">Preferences</screenshot>

      <screenshot href="images/alaska.png">Solar noon in Alaska in March is
      after 13:00!</screenshot>

			<screenshot href="images/sun.png">A hand in the shape of the sun shows
				the sun just about to rise in Alaska</screenshot>
    </screenshots>
  </overview>

  <operation lang="___">
    <subsection title="Requirements">
      <p>Java 2, 1.2 or greater.</p>
    </subsection>

    <subsection title="Application">
			<p>Rather than downloading the entire archive, you can now just download
				the <link href="yesClock.jar">executable jar file</link> and run it.
				You'll also need the <link href="yesCommon.jar">common jar file</link>
				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.</p>

      <p>To run the application, use the <code>-jar</code> option on the JVM
      and use the <code>yesClock.jar</code> file.</p>

      <example>java -jar yesClock.jar</example>

      <p>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 <code>--size</code> argument. The following will cause yesClock to
      open with a 200 pixel wide by 300 pixel tall window.</p>

      <example>java -jar yesClock.jar --size 200 300</example>

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

      <example>java -jar --size 1024 768 --dump current.png</example>

      <p>This is useful for generating desktop backgrounds. KDE, in
      particular, has support for this sort of background generation.</p>
    </subsection>

    <subsection title="Applet">
      <p>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
				<link href="yesApplet.jar">yesApplet.jar</link> and
				<link href="yesCommon.jar">yesCommon.jar</link> 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 <code>edt_on</code> flag.  Set it to
			<code>true</code> for EDT time, or don't include the parameter or set
			it to <code>false</code> to use standard time.</p>

		<example>&#60;APPLET WIDTH=&#34;200&#34; HEIGHT=&#34;200&#34; CODE="YesApplet.class"
		ARCHIVE=&#34;yesApplet.jar,yesCommon.jar&#34;
		WIDTH=&#34;200&#34; HEIGHT=&#34;200&#34;&#62;
	&#60;PARAM NAME=&#34;longitude&#34; VALUE=&#34;-121.31104&#34;/&#62;
	&#60;PARAM NAME=&#34;latitude&#34; VALUE=&#34;44.06604&#34;/&#62;
	&#60;PARAM NAME=&#34;edt_on&#34; VALUE=&#34;true&#34;/&#62;
&#60;APPLET&#62;</example>
    </subsection>

    <subsection title="Configuring">
      <p>Dynamic configuration is only available in the application.</p>

      <p>There are three main configuration options. The first, accessed under
      the menu item &#34;Configuration&#34;, 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&#39;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 <code>Cancel</code> button, your changes
      will be discarded. If you select the <code>Save</code> button, your
      changes will take effect, and your configuration will be saved to a file
      called <code>.YesClock</code> in your user home directory. This is a
      plain text file which you can edit by hand, or delete if it becomes
      corrupted.</p>

      <p>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 &#34;Time format&#34;
      section below for more information.</p>

      <p>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 <code>Save</code> button,
      and that shape will be used as the hand for the clock. If you click
      <code>Cancel</code>, your selection will be discarded. There is also a
      <code>Reload</code> button, which you can use to see a preview of your
      hands as you edit them. See &#34;Adding hands&#34; below for information
      about adding shapes.</p>
    </subsection>

    <subsection title="Adding hands">
      <p>You may define your own watch hand shapes; it is not trivial, but it
      isn&#39;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 <code>.YesClock</code> config file) named <code>.YesClockHands</code>.
      This file is a PYX file, and has the basic format:</p>

      <example>(hands
(hand
Aname someName
...
)hand
)hands</example>

      <p>To add a new hand, add a new &#34;(hand&#34; entry. Drawing commands
      are given <em>after</em> the &#34;Aname&#34; line, and before the
      &#34;)hand&#34; line. Each &#34;(hand ... )hand&#34; section defines a
      hand shape. Multiple hand shapes can appear in a single file, but the
      &#34;(hands&#34; line must start the file, and the &#34;)hands&#34; line
      must end it.</p>

      <p>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 &#34;cursor&#34; 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 &#39;-&#39; and have no extra space between the command and the
      &#34;-&#34;. The following lists the commands and their arguments.</p>

      <example>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</example>

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

      <example>(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 </example>

      <p>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.</p>

      <p>Here is a more complex example; this will draw the &#34;Fancy&#34;
      watch hand shape:</p>

      <example>(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</example>

      <p>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.</p>
    </subsection>

    <subsection title="Time format">
      <p>EDT.</p>
    </subsection>

		<subsection title="User Submitted Hands">
			<p>I'll be linking to user submitted hand shapes here.  To use them, copy
				and past the hand entries into your <code>~/.YesClockHands</code> file.</p>
		</subsection>
				
  </operation>

  <status>
    <subsection title="Change Log">
      <list>
				<item>1.3.2: Added a map to the config panel, for selecting lat/lon values.
				</item>
				<item>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.
				</item>

        <item>1.3.0 Features added. The hands are now configurable. Added
        <code>--dump</code> and <code>--size</code> arguments.</item>

        <item>1.2.0 Bug fixes. Added a timezone function, as a fix for the
        problem where the JVM isn&#39;t picking up the proper timezone from
        the OS. Changed the menu title for &#34;Location&#34; to
        &#34;Configuration&#34;. Updated the screenshots. Fixed some problems
        with the config panel.</item>

        <item>1.1.0 Initial release</item>
      </list>
    </subsection>

    <subsection title="Troubleshooting">
      <p>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&#39;ve observed that, on
      some machines, the JVM doesn&#39;t get the right timezone from the
      operating system. Make sure you check the zone settings in the
      preferences for accuracy.</p>

      <p>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.</p>
    </subsection>

    <bugs lang="en">
      <item>I suspect I&#39;m going to have to add a DST adjuster to the
      configuration, too.</item>
    </bugs>

    <todo lang="en">
			<item>Add toggle for digital time display</item>

      <item>Add a &#34;hand_name&#34; param to the applet</item>

      <item>Add moon phases (as with the yes watch)</item>

      <item>Add a moon hand</item>

      <item>Allow users to customize colors</item>

      <item>Add twilight</item>

      <item>Save the window position</item>

      <item>Document the sourcecode better</item>

			<item status="request">Change the hand to SVG->PYX format.</item>

      <item status="request">Add real shadows for hands and text</item>

      <item status="request">Add display for additional time zones</item>

      <item status="request">Add a world map for selecting lat/lon/tz</item>
			
      <item status="fixed">Add --dump and --size for embedding in desktop</item>
      <item status="fixed">Make the border for the selected hand thicker</item>
      <item status="fixed">Add the names of the hands to the hand list widget</item>
      <item status="fixed">Add configurable hands</item>
    </todo>
  </status>

  <credits>
    <list>
      <item>The astronomy functions are based on sunriset.c by Paul Schlyter</item>

      <item>The <link href="http://www.yeswatch.com">yes watch</link> provided
      the inspiration for this project</item>
    </list>
  </credits>
</documentation>
