home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format 68 / af068sub.adf / BarClock / BarClock.DOC < prev    next >
Text File  |  1994-11-25  |  14KB  |  470 lines
  1.  
  2.  
  3. If anyone actually reads this I'll be amazed.... anyway, here goes:
  4. -------------------------------------------------------------------------
  5.  
  6.                               BARCLOCK  1.2
  7.                               ~~~~~~~~  ~~~
  8.        It's a clock that sits in your Workbench screen's title bar
  9.        ~~~~ ~ ~~~~~ ~~~~ ~~~~ ~~ ~~~~ ~~~~~~~~~ ~~~~~~~~ ~~~~~ ~~~
  10.                              By David Boucher
  11.                              ~~ ~~~~~ ~~~~~~~
  12. -------------------------------------------------------------------------
  13. Created: 24-Oct-94                          This guide created: 30-Oct-94
  14.  
  15.  
  16. Contents:
  17.          WHAT IS BARCLOCK?
  18.          RUNNING THE PROGRAM.
  19.          TOOLTYPES AND CLI PARAMETERS.
  20.          DISTRIBUTION & LEGAL STUFF.
  21.          PROGRAM HISTORY.
  22.          CREDITS.
  23.          AND FINALLY...
  24.  
  25.  
  26.  
  27.  
  28. What is BarClock?
  29. ~~~~ ~~ ~~~~~~~~~
  30.    BarClock is a clock that sits on the Workbench title bar... 
  31.    
  32.    Oh, you want more, ok...  BarClock is a combined clock and calender 
  33. commodity program for Workbench 2.04 or better. It can display time, date 
  34. and day in the Workbench screen's title bar and can be configured through 
  35. Workbench TOOLTYPES of CLI PARAMETERS. The program's commodity interface 
  36. can be used to enable, disable and quit the program.
  37.  
  38.     Options available through ToolTypes/Parameters are:
  39.     
  40.    ·Display of DAY/DATE/TIME can be toggled on or off.
  41.    ·DATE FORMAT can be changed to any one of four available.
  42.    ·Clock mode can be 12 OR 24 HOURS, with or without SECONDS.
  43.    ·TASK PRIORITY and COMMODITY PRIORITY can be changed.
  44.    ·ENABLE option allows commodity to be started enabled or disabled.
  45.    ·QUIT option allows program to be closed down without EXCHANGE.
  46.  
  47.  
  48.  
  49.  
  50. Running the Program
  51. ~~~~~~~ ~~~ ~~~~~~~
  52.    BarClock can be run run from either Workbench or CLI. If the program 
  53. is to be run from the WBSTARTUP drawer the DONOTWAIT Tooltype must be 
  54. added. When running from the CLI the program will not "lock up" the CLI 
  55. and there is no need to use RUN, RUNBACK or any other such programs. 
  56.  
  57.    If the program is run twice, the new copy of the program will replace 
  58. the old, so settings can be changed by just re-running the program.
  59.  
  60.    Once the program is running, the Commodities EXCHANGE program 
  61. can be used to Enable Disable and Quit the program. Simply open Exchange, 
  62. select BarClock from the list and select the relevant option. These 
  63. operations can also be performed by using the ENABLE and QUIT options.
  64.  
  65.    IMPORTANT NOTE:
  66.  
  67.    When BarClock is enabled it will prevent the Workbench screen from 
  68. closing. To close the WorkBench you must disable or quit the program. 
  69. This can cause a problem if IPrefs needs to close the screen to update 
  70. preferences. IPrefs will repeatedly try to close the WorkBench, and fail 
  71. because BarClock is running (this is a problem with IPrefs NOT BarClock).
  72. If this happens you should either:
  73.  
  74.    ·Open EXCHANGE with it's hotkey and disable BarClock from there
  75.    ·Try to hit the CANCEL button of the "Close all windows..." requester 
  76.     in the brief second it appears.
  77.    ·Try to open a program window (e.g. a CLI) to stop IPrefs opening and 
  78.     closing things.
  79.  
  80.  
  81.  
  82.  
  83. ToolTypes and CLI Parameters
  84. ~~~~~~~~~ ~~~ ~~~ ~~~~~~~~~~
  85.    BarClock's various options are set through TOOLTYPES and 
  86. CLI PARAMETERS. There are ten options in all, but you don't have to 
  87. specify a value for all of them. If an option is not specified or 
  88. specified incorrectly, a default value will be used. 
  89.  
  90.    The available options are:
  91.     
  92.       CX_PRIORITY                                    SHOWDAY
  93.       SHOWDATE                                       SHOWTIME
  94.       HOURS                                          SECONDS
  95.       FORMAT                                         TASKPRI
  96.       ENABLE                                         QUIT
  97.  
  98.  
  99.  
  100.  
  101. WorkBench ToolTypes
  102. ~~~~~~~~~ ~~~~~~~~~
  103.    ToolTypes allow a program to have options attached to it's icon. 
  104. ToolTypes for a program can be edited be selecting the icon and selecting 
  105. Information... from the WorkBench Icons menu. BarClock's icon in this 
  106. distribution has all the available tooltypes specified with their default 
  107. value, with the exception of QUIT which has been commented out. If any of 
  108. the tooltypes are not specified or specified incorrectly then the default 
  109. value for what option will be used. 
  110.    The guide pages for each option give the values that are allowed for 
  111. each option. The general format is:
  112.  
  113.       OPTION=<VALUE>
  114.  
  115.    For more information on ToolTypes, consult your Workbench manual.
  116.  
  117.  
  118.  
  119.  
  120. CLI Parameters
  121. ~~~ ~~~~~~~~~~
  122.    When a program is run from the CLI parameters van be entered after 
  123. it's name to allow options to be specified. BarClock allows it's options 
  124. to be specified using CLI parameters. If a certain option is not 
  125. specified or is specified incorrectly then the default value for that 
  126. option will be used.
  127.    The guide pages for each option give the values that are allowed for 
  128. each option. The general format is:
  129.  
  130.       OPTION=<VALUE>
  131.  
  132.    For more information on CLI parameters, consult an AmigaDOS manual.
  133.  
  134.  
  135.  
  136.  
  137. CX_PRIORITY Option
  138. ~~~~~~~~~~~ ~~~~~~
  139.    The CX_PRIORITY option controls the priority of BarClock in the 
  140. commodities system. The only visible effect of this is that it can move 
  141. barclock up or down in the commodity list in the WorkBench 2 Exchange 
  142. program.
  143.  
  144. SYNOPSIS:
  145.       CX_PRIORITY=<priority value>
  146.  
  147.    The priority value is a number from -128 to +128. 
  148.    The default value is 0.
  149.  
  150. E.G.:
  151.       CX_PRIORITY=-5   Gives BarClock a CX_PRIORITY of -5. (No! ;-)
  152.  
  153.  
  154.  
  155.  
  156. ShowDay Option
  157. ~~~~~~~ ~~~~~~
  158.    The ShowDay option controls whether the clock display includes the day 
  159. name. (for example "Monday"). If your machine supports locale, the day 
  160. name will appear in your selected language.
  161.  
  162. SYNOPSIS:
  163.       SHOWDAY=<ON|OFF>
  164.  
  165.    Turns day names on or off.
  166.    The default value is ON.
  167.  
  168. E.G.:
  169.       SHOWDAY=ON   Could produce: Wednesday 12-10-94 21:15:16. While...
  170.  
  171.       SHOWDAY=OFF  Could produce 12-10-94 21:15:16.
  172.  
  173.  
  174.  
  175.  
  176. ShowDate Option
  177. ~~~~~~~~ ~~~~~~
  178.    The ShowDate option controls whether the clock display includes the 
  179. date. The format of the date can be controlled with the format option.
  180.  
  181. SYNOPSIS:
  182.       SHOWDATE=<ON|OFF>
  183.  
  184.    Turns date display on or off.
  185.    The default value is ON.
  186.  
  187. E.G.:
  188.       SHOWDATE=ON   Could produce: Wednesday 12-10-94 21:15:16. While...
  189.  
  190.       SHOWDATE=OFF  Could produce Wednesday 21:15:16.
  191.  
  192.  
  193.  
  194.  
  195. ShowTime Option
  196. ~~~~~~~~ ~~~~~~
  197.    The ShowTime option controls whether the clock display includes the 
  198. time. The format of the date can be controlled with the hours and 
  199. seconds options.
  200.  
  201. SYNOPSIS:
  202.       SHOWTIME=<ON|OFF>
  203.  
  204.    Turns Time display on or off.
  205.    The default value is ON.
  206.  
  207. E.G.:
  208.       SHOWTIME=ON   Could produce: Wednesday 12-10-94 21:15:16. While...
  209.  
  210.       SHOWTIME=OFF  Could produce Wednesday 12-10-94.
  211.  
  212.  
  213.  
  214.  
  215. Hours Option
  216. ~~~~~ ~~~~~~
  217.    The Hours option controls whether the clock display format is 12 or 24 
  218. hours. 12 hour notation will display a AM/PM indicator. This option has 
  219. no effect if SHOWTIME has been set to NO.
  220.  
  221. SYNOPSIS:
  222.       HOURS=<12|24>
  223.  
  224.    Sets clock mode to 12 or 24 hour.
  225.    The default value is 24.
  226.    
  227. E.G.:
  228.       HOURS=12   Could produce  9:15:16 PM. While...
  229.  
  230.       HOURS=24   Could produce 21:15:16.
  231.  
  232.  
  233.  
  234.  
  235. Seconds Option
  236. ~~~~~~~ ~~~~~~
  237.    The Seconds option controls whether the clock display includes the 
  238. number of seconds. This option has no effect if SHOWTIME has been set to 
  239. NO.
  240.  
  241. SYNOPSIS:
  242.       SECONDS=<YES|NO>
  243.  
  244.    Sets seconds on or off
  245.    The default value is ON.
  246.    
  247. E.G.:
  248.       SECONDS=12   Could produce 21:15:16. While...
  249.  
  250.       SECONDS=24   Could produce 21:15.
  251.  
  252.  
  253.  
  254.  
  255. Format Option
  256. ~~~~~~ ~~~~~~
  257.    The Format option controls how the date will be displayed. There are 
  258. four possible styles for the date, which are:
  259.  
  260.    DOS: This is the default style. The date will be displayed as a two 
  261. digit day-of-the-month number, followed by a dash (-), followed by a two 
  262. or three character month name, another dash, and a two digit year number.
  263.    If your machine supports locale, the month name will appear in your 
  264. chosen language. 
  265.    Example of DOS: 12-Oct-94.
  266.  
  267.    INT: (International) This format has two digit year number, dash, two 
  268. digit month number, hash, and two digit day-of-the-month. 
  269.    Example of INT: 94-10-12.
  270.  
  271.    USA: (American) This format has two digit month number, dash, two 
  272. digit day-of-the-month, dash, and two digit year number.
  273.     Example of USA: 10-12-94.
  274.  
  275.    CDN: (Canadian) This format has two digit day-of-the-month, hash, two 
  276. digit month number, hash, two digit year number.
  277.    Example of CDN: 12-10-94.
  278.  
  279.    This option has no effect if SHOWDATE has been set to NO.
  280.  
  281. SYNOPSIS:
  282.       FORMAT=<DOS|INT|USA|CDN>
  283.  
  284.    Sets date format.
  285.    The default value is DOS.
  286.    
  287. E.G.:
  288.       FORMAT=CDN   Could produce 12-10-94.
  289.  
  290.  
  291.  
  292.  
  293. TaskPri Option
  294. ~~~~~~~ ~~~~~~
  295.    The TaskPri option controls the priority of BarClock relative to other 
  296. tasks running on the system. The Higher the priority, the faster the 
  297. program will be in updating the clock. However, running at a high 
  298. priority will slow down other tasks on the system. Although the Amiga 
  299. allows priorities from -128 to +127, BarClock limits this to +5 to -5. 
  300. This prevents the program from slowing up vital system tasks or from 
  301. becoming "swamped" by programs running at a higher priority.
  302.  
  303. SYNOPSIS:
  304.       TASKPRI=<priority value>
  305.  
  306.    The priority value is a number from -5 to +5. 
  307.    The default value is 0.
  308.  
  309. E.G.:
  310.       TASKPRI=1   Gives BarClock a higher than normal priority.
  311.  
  312.  
  313.  
  314.  
  315. Enable Option
  316. ~~~~~~ ~~~~~~
  317.    The Enable option controls whether barclock starts up enabled or 
  318. disabled. This option was added for testing but has been left in in case 
  319. anyone needs it.
  320.  
  321. SYNOPSIS:
  322.       ENABLE=<YES|NO>
  323.  
  324.    Sets the program to start up enabled or disabled.
  325.    The default is YES.
  326.  
  327. E.G.:
  328.       ENABLE=NO   Starts the program disabled
  329.  
  330.  
  331.  
  332.  
  333. Quit Option
  334. ~~~~ ~~~~~~
  335.    The quit option, if present, instructs the program to quit as soon as 
  336. it has started up. This is to allow you to "kick out" an existing copy of 
  337. the program without the need for Exchange.
  338.  
  339. SYNOPSIS:
  340.       QUIT
  341.  
  342.    Causes the program to quit.
  343.    This command has no parameters.
  344.  
  345.  
  346.  
  347.  
  348. The WBStartup Drawer
  349. ~~~ ~~~~~~~~~ ~~~~~~
  350.    Programs placed in the WBStartup drawer are run automatically when 
  351. Workbench is loaded. If BarClock is to be run in this way, the DONOTWAIT 
  352. ToolType should be added to it's icon. You can also use the STARTPRI 
  353. ToolType to specify the order in which programs in WBStartup will run.
  354.  
  355.    For more information on DONOTWAIT and STARTPRI, consult your Workbench 
  356. manual.
  357.  
  358.  
  359.  
  360.  
  361. The DONOTWAIT ToolType
  362. ~~~ ~~~~~~~~~ ~~~~~~~~
  363.    The DONOTWAIT ToolTypes simply instructs the Amiga not to wait for a 
  364. program run from the WBStartup drawer to finish. BarClock requires this 
  365. ToolType when run from WBStartup
  366.  
  367.  
  368.  
  369.  
  370. The Exchange Program
  371. ~~~ ~~~~~~~~ ~~~~~~~
  372.    The Exchange program is used to control the activity of commodity 
  373. programs. Since BarClock is a commodity it can be controlled from 
  374. Exchange. From Exchange, it can be enabled, disabled and made to quit. 
  375. BarClock does not have SHOW and HIDE features and therefore these options 
  376. will be ghosted when using Exchange.
  377.  
  378.     For more information on Exchange, consult your Workbench manual.
  379.  
  380.  
  381.  
  382.  
  383. Distribution & Legal Stuff
  384. ~~~~~~~~~~~~ ~ ~~~~~ ~~~~~
  385.    BarClock is © 1994 David Boucher. It is freely distributable as long 
  386. as the following conditions are observed:
  387.    
  388.    (1) The program (BarClock) is only distributed with it's associated 
  389. documentation (BarClock.guide, this file) and icon files (BarClock.info 
  390. and BarClock.guide.info) and that none of these files are changed in any 
  391. way (Exception: The program may be packed or archived).
  392.  
  393.    (2) No charge is made for the program. (Exception: a small charge may 
  394. be made by PD libraries distributing the program).
  395.  
  396.    (3) The program is not included on any commercial package (This 
  397. INCLUDES any disks supplied with magazines e.g. coverdisks) without my 
  398. (David Boucher's) prior consent.
  399.  
  400.    WARNING: Although the program has been extensively tested there may 
  401. still be bugs, therefore: USE AT YOUR OWN RISK! No guarantees whatsoever 
  402. are given of this program.
  403.  
  404.    All trademarks/copyrights used in this file are hearby acknowledged.
  405.  
  406.  
  407.  
  408.  
  409. Program History
  410. ~~~~~~~ ~~~~~~~
  411.    Version 1.0 (12.10.94):
  412.       First release (Released to Chris, and the thieving little %£^$ who 
  413. stole my disk at uni when I wasn't looking. May it melt their CPU.)
  414.  
  415.    Version 1.1 (22.10.94):
  416.       First bug fix: BarClock now runs correctly on KickStart 3.0 (and 
  417. probably 3.1) and uses the user defined screen title bar colours. Fixed a 
  418. few spelling mistakes in the .guide.
  419.  
  420.    Version 1.2 (24.10.94):
  421.       Second bug fix: 12 hour mode now displays correctly and doesn't 
  422. cut the first digit of the hour off (oops!). Finally decided to spell 
  423. check the .guide file.
  424.  
  425.  
  426.  
  427.  
  428. Credits
  429. ~~~~~~~
  430.    BarClock was conceived, designed and written by David Boucher using 
  431. Dice C on an Amiga 500 running KickStart 2.05 with 3Mb ram (0.5 chip, 
  432. 2.5 fast).
  433.  
  434.    Thanks to:
  435.  
  436.    Chris Hurst: For allowing me use of his A1200 to fix bugs and general 
  437.                 testing.
  438.    
  439.    Simon Bromley: For lifts back from uni (Saves me from the bus :-)
  440.  
  441.    Lots of Amiga Programmers: For writing all the progs I use.
  442.    
  443.    All my fellow layabouts at Staffordshire University: For err... what?
  444.  
  445.  
  446.  
  447.  
  448. And Finally...
  449. ~~~ ~~~~~~~~~~
  450.    Yes, here's the bit in every .guide file where the author whaffles for 
  451. about a page. Skip this bit if you want, I won't mind.
  452.  
  453.    BarClock was brought to you by DAVID BOUCHER, author of the world's 
  454. favorite Amiga programs(?).
  455.  
  456.    If you wish to contact me, then send your comments, bug-reports(!), 
  457. suggestions, banknotes, blank cheques, gold ingots, diamonds, etc. to:
  458.  
  459.           DAVID BOUCHER, 37, SMITH STREET, LONGTON, STOKE-ON-TRENT, 
  460.                      STAFFORDSHIRE. ST3 1DR. ENGLAND.
  461.  
  462.    Or you could try: cm3bcdjb@s47a.staffs.ac.uk (if you're feeling lucky)
  463.  
  464.    This program is not shareware, but as you may have guessed from the 
  465. above paragraph, I won't be offended if you send me money (I'll be very 
  466. surprised though).
  467.  
  468. Byeee!....
  469.  
  470.