NAME

astime - the AfterStep analogue clock

SYNOPSIS

astime [-h] [-H] [-V] [-iconic] [-withdrawn] [-standout] [-noborder] [-geometry [WxH][+|-]x[+|-]y] [-rc file name] [-u update rate] [-exe program name] [-shift hours] [-ns] [-nd] [-nap] [-display display] [-title name] [-bg color] [-fg color] [-sec color] [-min color] [-hour color] [-day color] [-date color] [-ampm color] [-nt] [-at] [-fs] [-ts] [-fh] [-nh] [-ht number] [-ot number] [-nf] [-label text] [-fn font name] [-lcol label color] [-ltop]

DESCRIPTION

The astime is a X11 application that acts as an analogue clock that we all are familiar with. It shows the current time on the dial. The day of the week is in the upper left corner and the current date is at the bottom. The AM/PM indicator is in the top right corner.

CONFIGURATION OPTIONS

-h or -H

Prints a short description and usage message.

-V

Version control. Prints out the version of the program.

-rc <file name>

Read the configuration from the given resource file. The default resource file read if none are given on the command line is ~/.astimerc. The settings on the command line overwrite any settings read from the resource file. A single '#' character can be used to "comment out" any line in the .astimerc file, which is useful for making temporary changes.

-geometry [WxH][+|-]x[+|-]y

Displays the window at the specified location on the screen and resizes the window to the specified size WxH. This works as standard X Windows geometry option. (See XParseGeometry (3x)).

-iconic

Starts the astime application in the iconized mode. The icon has the same appearance with the main window. When this option is given, the -position refers to the position of the icon window as well as the main window.

-withdrawn

Starts the astime application in the withdrawn mode. This option is necessary to be able to dock the astime in the WindowMaker dock. When this option is given, the -position refers to the position of the icon window as well as the main window. astime ignores the -iconic option when started in withdrawn mode.

-standout

This changes the appearance of the astime display from "pushed-in" to "popped-out". The first is the default look. The "popped-out" applets look much better in WindowMaker's dock according to some opinions. Give it a try in any case.

-noborder

The clock looses its border effectively becoming a 2D clock instead of having a raised or lowered faceplate. This option is reportedly recommended for FVWM use. When this option is used "-standout" is ignored.

-u <update rate>

Changes the polling rate for updating the clock. The update rate is specified in seconds. The value of 1 is the minimum. Default value is 1 second. Updating at a different value is hardly a good idea when you have the seconds hand on. Switch it off with the "-nosec" option.

-exe <program name>

Specifies which program should be executed when you click on the clock's face. If this switch is not specified, astime does not intercept the mouse clicks at all. So, by default, nothing is run. This option uses system(3) call to execute the specified program. The maximum length of the command is restricted to 255 characters (for no particular reason).

The icon does not usually respond to mouse clicks (you would want to be able to de-iconify the window, right?) unless you are running in the "withdrawn" mode (-withdrawn option). Then the icon responds the same way the clock face does.

-shift <hours>

Shifts the clock by the specified number of hours. This is a simple way of putting a clock in a different timezone. Useful when you want several clocks showing the current time in different places. The value can be both positive and negative. The values above 23 and below -23 are silently ignored.

Note that the date and day of the week are not adjusted.

-ns

Do not draw the seconds hand of the clock. Only the minutes and hours hands are drawn.

-nd

Do not show the current date.

-nap

Do not show the AM/PM indicator.

-display <name>

The name of the display to start the window in. It works just as X Windows display option.

-title <name>

Set the window title and the icon title to the specified name.

-bg <color>

Changes the color of the background of the dial. Default colour is #385971.

-fg <color>

Changes the color of the foreground of the dial. Default colour is #ffffff.

-sec <color>

Changes the color of the second hand of the clock. Default colour is #efc669.

-min <color>

Changes the color of the minute hand of the clock. Default colour is #ff3030.

-hour <color>

Changes the color of the hour hand of the clock. Default colour is #ef3838.

-day <color>

Changes the color of the day-of-the-week display. Default colour is #a0a0a0.

-date <color>

Changes the color of the date display. Default colour is #a0a0a0.

-ampm <color>

Changes the color of the AM/PM display. Default colour is #a0a0a0.

-nt

Don't draw the second ticks on the clock face.

-at

Draw all ticks, not only every 5 seconds.

-fs

"Floating" second indicator in the style of xclock.

-ts

Use a thin second hand - default in the regular mode. Use it to change the appearance of the second hand while in the -fh mode. It looks very good with the normal hands of large thickness too.

-fh

Fancy hands mode. Renders fancy xclock-style hands.

-nh

"Neon" hands. Try this with the fancy hands mode.

-ht <number>

Hand thickness. Can be a number from 0 to 200.

-ot <number>

Hand outline thickness. Can be a number from 0 to 200.

-nf

No foreground. Equal to "-nd -nap -nt".

-label <text>

Asks the astime to label the clock's face with the specified text. Useful when you want to distinguish between different instances of astime running on your desktop.

-fn <font name>

Use the specified font for the label. The default font is "-*-helvetica-medium-r-*-*-9-240-*-*-*-*-*-*". Don't ask me why, I do not know, I just found it fits my desktop well. If you have a better idea - send me a mail. The font is loaded only if you specify a label and has otherwise no effect.

-lcol <label color>

Draw the label using the specified color. The default color is #a0a0a0. Has no effect if you did not specify a label.

-ltop

Draw the label on the top of the clock's face instead of drawing it at the bottom by default. Does not do anything if a label was not specified.

RESOURCE FILE SYNTAX

astime can read and parse a configuration file. This configuration file describes the desired look of the applet (there are equialents to all command-line options) and specifies actions to be taken on particular events. The configuration file is usually ~/.astimerc but astime can be forced to read any file using the -rc option. Any options read from the configuration file may be overridden with the command-line options (if a corresponding command-line option exists, naturally).

The configuration file may contain only one option per line. Empty lines and lines starting with # are ignored.

geometry <geometry specification>

Your standard X Windows geometry specification.

background <color>

Specifies the background color.

foreground <color>

Specifies the foreground color.

secondColor <color>

Specifies the color for the second hand of the clock.

minuteColor <color>

Specifies the color for the minute hand of the clock.

hourColor <color>

Specifies the color for the hour hand of the clock.

secondOutColor <color>

Specifies the color for the second hand outline in fancy and outline modes.

minuteOutColor <color>

Specifies the color for the minute hand outline in fancy and outline modes.

hourOutColor <color>

Specifies the color for the hour hand outline in fancy and outline modes.

secondFillColor <color>

Specifies the fill color for the second hand in fancy mode.

minuteFillColor <color>

Specifies the fill color for the minute hand in fancy mode.

hourFillColor <color>

Specifies the fill color for the hour hand in fancy mode.

dayColor <color>

Specifies the color for the day of the week indicator.

AMPMColor <color>

Specifies the color for the AM/PM indicator.

dateColor <color>

Specifies the color for the current date indicator.

drawSecondHand <0 | 1>

A boolean variable (0 | 1) specifying if the second hand should be drawn.

drawDayDate <0 | 1>

A boolean variable specifying if the day/date indicator should be drawn.

drawAMPM <0 | 1>

A boolean variable specifying if the AM/PM indicator should be drawn.

drawTicks <0 | 1>

A boolean variable specifying if the second ticks should be drawn at all.

drawAllTicks <0 | 1>

A boolean variable specifying if all ticks should be drawn and not only every 5 sec.

drawForeground <0 | 1>

A boolean variable specifying if the foreground elements should be drawn. When zero is specified only the clock hands appear.

floatSeconds <0 | 1>

A boolean variable specifying if the second indicator should be a floating pointer (a bit like in xclock) rather than a hand.

thinSeconds <0 | 1>

A boolean variable specifying if the second hand should be thin.

handThickness <thickness>

Specifies the thickness of the hands. Can be a value between 0 and 200.

outThickness <thickness>

Specifies the thickness of the outline of the hands. Can be a value between 0 and 200.

fancyHands <0 | 1>

A boolean variable (0 | 1). Render polygonal, xclock-like hands.

outlinedHands <0 | 1>

A boolean variable (0 | 1). Render polygonal, xclock-like hands without fill.

neonHands <0 | 1>

A boolean variable (0 | 1). Darken the hand fill colors with respect to their outlines, useful with fancy hands.

execProg <command line>

Specifies a command to be executed when the clock face is clicked. The command line must be enclosed in double quotes.

withdrawn <0 | 1>

A boolean variable (0 | 1). This option is necessary when running with WindowMaker. Produces a withdrawn window that can be docked.

iconic <0 | 1>

A boolean variable (0 | 1). Specifies if the applet should start as an icon rather than a full window.

standout <0 | 1>

A boolean variable (0 | 1). Changes the appearance of the display from "pushed-in" to the "standing out".

noborder <0 | 1>

A boolean variable (0 | 1). Changes the appearance of the display from 3D to plain 2D by removing the shaded border around the faceplate.

shift <+-hours>

Specifies that the clock should show the local time shifted by the given number of hours. Useful to see the time in different timezones.

title <name>

Specifies which title should be given to this clock.

at hh:mm:ss <command line>

Specifies program to be run at a particular time. The command line must be enclosed in double quotes.

Label <text>

Asks the astime to label the clock's face with the specified text. Useful when you want to distinguish between different instances of astime running on your desktop. Equivalent to the command-line '-label' option.

Font <font name>

LabelColor <color>

Draw the label using the specified color. The default color is #a0a0a0. Has no effect if you did not specify a label. Equivalent to the command-line '-lcolor' option.

LabelTop <0 | 1>

If the value is 1 draws the label on the top of the clock's face; if the value is 0 - at the bottom (default). Does not do anything if a label was not specified.

INVOCATION

astime can be called in different ways. The most common invocation is the command line:

	user@host[1]% astime -bg blue -fg white &

Another way to call astime is from the window manager:

	*Wharf "astime" nil Swallow "astime" astime -nosec &

This line, when placed in the wharf file in the user's Afterstep configuration directory will cause astime to be a button on the Wharf (1) button bar under the afterstep (1) window manager.

If you run WindowMaker then you should use the "-withdrawn" option:

	user@host[1]% astime -withdrawn -standout &

and then drag the icon to the dock.

If you run fvwm2 I think you will like to try this one:

	astime -geometry 120x120+890+0 -bg black 
	-fg \#0000ff -sec \#efc669 -min \#20b2aa 
	-hour \#8141d7 -day \#7766aa -ampm \#7766aa 
	-date \#7766aa -at -fs -fh -nh

Of course, it looks less scary if you put all those settings in the ~/.astimerc file. The example .astimerc file (sample.astimerc) included in the distribution provides the aforementioned settings.

BUGS

My programs do not have bugs, they just develop random features ;-)

Well, there are limitations. All the strings for the color names, display name, and the geometry have the length limit of 64 characters (terminating zero included). The string copying routine cuts the names that are longer.

COPYRIGHTS

Distributed under GNU General Public License v2 ; see LICENSE file for more informations.

AUTHORS

Albert "Tigr" Dorofeev <albert@tigr.net>

William Kostis <kostis@ee.cornell.edu>

See the README file for details and credits.