home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format 109 / af109sub.adf / NISClock.lzx / NISclock / NISClock.doc < prev    next >
Encoding:
Text File  |  1998-02-05  |  13.3 KB  |  303 lines
  1.                        NISClock 2.20  (1998.Feb.21)
  2.                    © Copyright 1995-97, 1998 John Muir
  3.                            Written by John Muir
  4.  
  5. ___________________________________________________________________________
  6. Introduction
  7.  
  8.     NISClock is a small clock program that displays the time and date
  9.     on the active public screen. Locale.library is used to format the
  10.     time and the date that you define. The text of your choosing (the
  11.     time by default) is displayed in a small window that matches the
  12.     screen's title-bar colour, or as a screen gadget button look-alike.
  13.     A mouse click on the window will display a second text (usually the
  14.     date).
  15.  
  16.     The E-Clock timer is used to time the update intervals so that
  17.     the time is always updated even if the clock is adjusted backwards.
  18.  
  19.     NISClock is written in C, and compiled with SAS/C 6.58.
  20.  
  21.   Screen Notification
  22.  
  23.     NISClock can make use of Stephan Becker's screennotify.library which
  24.     patches a few intuition.library functions so that the clock will
  25.     automatically close its window if the Public screen that it inhabits
  26.     is closed by another program. If NISClock is on the Workbench screen,
  27.     it will be notified of the close and opening of the Workbench screen
  28.     by IPrefs for a preferences change or by any other program which calls
  29.     CloseWorkbench().  The window will then not open until OpenWorkbench()
  30.     is called.
  31.  
  32.   Other Options
  33.  
  34.     Other options include window position, justification of the text within
  35.     the window, a specified amount of time (seconds) to update the clock
  36.     display, and the ability to avoid certain public screens.
  37.  
  38. ___________________________________________________________________________
  39. Requirements
  40.  
  41.     NISClock has the following simple requirements:
  42.  
  43.       - Amiga OS V37 (2.04). Uses V39 features if present.
  44.       - locale.library.
  45.       - RECOMMENDED: screennotify.library by Stephan Becker. See
  46.        'Installation' for more information on screennotify.library.
  47.       - NISClock must be run from the Workbench; perfect for the WBStartup
  48.        drawer.
  49.  
  50. ___________________________________________________________________________
  51. Installation
  52.  
  53.     Use the Workbench to copy NISClock into the WBStartup drawer to have
  54.     the program execute as you startup.  If you have a 68000, use the CLI
  55.     to delete NISClock, and rename NISClock_000 as NISClock before copying
  56.     it.
  57.  
  58.     If you decide to use screennotify.library by Stephan Becker for the
  59.     enhanced features, the library must be installed in LIBS: or PROGDIR:
  60.     (the directory where NISClock is started from).  Get
  61.     screennotify.library from the distribution archive on AmiNET:
  62.  
  63.       /pub/aminet/util/libs/ScreenNotify10.lha (19K)
  64.  
  65. ___________________________________________________________________________
  66. Usage
  67.  
  68.   Execution
  69.  
  70.     To run NISClock, simply double-click on the icon! To run NISClock at
  71.     startup, place the program in the WBStartup drawer. NISClock can be
  72.     halted by executing the program again.
  73.  
  74.     NISClock will not run from the CLI.
  75.  
  76.   Date and Time Display
  77.  
  78.     NISClock will by default display the text defined by TIMEFORMAT. The
  79.     text defined by DATEFORMAT can be displayed for four seconds by
  80.     clicking on the NISClock window.
  81.  
  82.     If the time text or date text is too big for the current window size,
  83.     then the window is enlarged to fit the text. The window is never
  84.     shrunk back. The window will enlarge to the left if EDGE is negative,
  85.     or if the window does not fit any further right. Similarly, the
  86.     window will enlarge to the right if EDGE is positive, or the window
  87.     reaches the left edge of the screen.
  88.  
  89.     Use the TOP and EDGE tooltypes to define the position of the NISClock
  90.     window. Use the JUST tooltype to justify the text within the NISClock
  91.     window.
  92.  
  93.   Active Public Screen
  94.  
  95.     NISClock will automatically jump to the active public screen. If
  96.     NISClock is using screennotify.library, then screen closures will
  97.     automatically be detected, and the window will be re-opened on the
  98.     active public screen.
  99.  
  100.   Avoiding Public Screens
  101.  
  102.     Screens can be avoided through the AVOIDSCR tooltype. That is,
  103.     NISClock will not open its window on screens that match the pattern
  104.     given with this tooltype. Custom screens (such as your screen blanker)
  105.     are automatically avoided. The Workbench screen cannot be avoided, so
  106.     you can keep the NISClock window on the Workbench screen with by
  107.     setting "AVOIDSCR=#?".
  108.  
  109.   Tooltypes
  110.  
  111.     Icon tooltypes are used to control the appearance of NISClock. NISClock
  112.     will automatically update itself if the icon tooltypes are changed.
  113.     NISClock accepts the following tooltypes:
  114.  
  115.       UPDATE - Numeric; eg: UPDATE=1
  116.            - DEFAULT: UPDATE=60
  117.            - specifies the window update time in seconds.
  118.            - the E-Clock timer is used to time this period, with the
  119.             result that backward time changes do not affect the clock.
  120.  
  121.       BUTTON - Boolean
  122.            - DEFAULT: FALSE
  123.            - if FALSE, the time is displayed in the title bar colours,
  124.             otherwise a box is drawn on the edge of the window to match the
  125.             screen gadget.
  126.            - NOTE: V37: Backpen = 2 (White) and FrontPen = 1 (Black).
  127.  
  128.       EDGE - Numeric; eg: EDGE=400
  129.            - the value represents the edge of the NISClock window.
  130.            - DEFAULT: EDGE=-1
  131.            - if the value is negative, this is the right edge of the
  132.             window + 1, ie: EDGE=-1 signifies that the window is all the
  133.             way to the right of the screen, except that it must fit around
  134.             the screen gadget.
  135.            - the window cannot be positioned with the mouse, so make good
  136.             use of the file notificaiton on NISClock.info! :)
  137.  
  138.       TOP - Numeric; eg: TOP=-4
  139.            - Top or bottom edge of the window.
  140.            - DEFAULT: TOP=0
  141.            - if the value is negative, this is the bottom edge of the
  142.             window + 1, ie: TOP=-1 signifies that the window is against
  143.             the bottom of the screen.
  144.  
  145.       JUST - Enumerated
  146.            - display the time and/or date with justification;
  147.             JUST = CENTER, RIGHT, LEFT, or NONE.
  148.            - DEFAULT: JUST=NONE
  149.            - NONE means CENTER when BUTTON is true, and RIGHT otherwise.
  150.  
  151.       TIMEFORMAT - Text; eg: TIMEFORMAT=Time: %H:%M:%S
  152.            - DEFAULT: TIMEFORMAT=%Q:%M %p
  153.            - specifies the format of the time text as defined by
  154.             the locale.library FormatDate() function.
  155.            - this is constructed just like C-language printf() statements,
  156.             except that different formatting codes are used. Just like in
  157.             C, formatting codes are a % followed by the formatting command.
  158.             The following commands are accepted by this function (from
  159.             AutoDocs):
  160.                  %a - abbreviated weekday name
  161.                  %A - weekday name
  162.                  %b - abbreviated month name
  163.                  %B - month name
  164.                  %c - same as "%a %b %d %H:%M:%S %Y"
  165.                  %C - same as "%a %b %e %T %Z %Y"
  166.                  %d - day number with leading 0s
  167.                  %D - same as "%m/%d/%y"
  168.                  %e - day number with leading spaces
  169.                  %h - abbreviated month name
  170.                  %H - hour using 24-hour style with leading 0s
  171.                  %I - hour using 12-hour style with leading 0s
  172.                  %j - julian date
  173.                  %m - month number with leading 0s
  174.                  %M - the number of minutes with leading 0s
  175.                  %n - insert a linefeed
  176.                  %p - AM or PM strings
  177.                  %q - hour using 24-hour style
  178.                  %Q - hour using 12-hour style
  179.                  %r - same as "%I:%M:%S %p"
  180.                  %R - same as "%H:%M"
  181.                  %S - number of seconds with leadings 0s
  182.                  %t - insert a tab character
  183.                  %T - same as "%H:%M:%S"
  184.                  %U - week number, taking Sunday as first day of week
  185.                  %w - weekday number
  186.                  %W - week number, taking Monday as first day of week
  187.                  %x - same as "%m/%d/%y"
  188.                  %X - same as "%H:%M:%S"
  189.                  %y - year using two digits with leading 0s
  190.                  %Y - year using four digits with leading 0s
  191.            - Note: for some reason, %W and %U don't work properly. Bug in
  192.              locale.library?
  193.  
  194.       DATEFORMAT - Text; eg: DATEFORMAT=%Y/%m/%d
  195.            - display the date in the requested format.
  196.            - DEFAULT: DATEFORMAT=%Y.%b.%e
  197.            - formatting text is as described above.
  198.            - this text is only displayed for four seconds after the mouse
  199.             is clicked on the window.
  200.  
  201.       AVOIDSCR - Text; eg: AVOIDSCR=(DOPUS.?|PAGESTREAM?)
  202.            - pattern matching names of screens that NISClock will not jump
  203.             to. Uses the standard pattern matching that is part of
  204.             dos.library.
  205.            - DEFAULT: AVOIDSCR=DOPUS.?
  206.            - available pattern tokens (from AutoDocs):
  207.              ?       Matches a single character.
  208.              #       Matches the following expression 0 or more times.
  209.              (ab|cd) Matches any one of the items seperated by '|'.
  210.              ~       Negates the following expression.  It matches all
  211.                      strings that do not match the expression (aka ~(foo)
  212.                      matches all strings that are not exactly "foo").
  213.              [abc]   Character class: matches any of the characters in the
  214.                      class.
  215.              [~bc]   Character class: matches any of the characters not in
  216.                      the class.
  217.              a-z     Character range (only within character classes).
  218.              %       Matches 0 characters always (useful in "(foo|bar|%)").
  219.              *       Synonym for "#?", not available by default in 2.0.
  220.                      Available as an option that can be turned on.
  221.            NOTES:
  222.            - DOPUS 4.x will attempt to close visiting windows (not a good
  223.             thing) when it closes its screen. This is a very bad idea, and
  224.             definitely not good for NISClock which will shortly thereafter
  225.             cause your machine to crash.
  226.            - < V39: Put your pattern in uppercase; there was a bug
  227.             in MatchPatternNoCase().
  228.            - You cannot avoid the Workbench screen. Sorry! ;)
  229.  
  230. ___________________________________________________________________________
  231. Comments? Talk to me!
  232.  
  233.     EMail: John D. Muir <jmuir@poboxes.com>
  234.     My PGP private key is available on my home page at
  235.     http://www.poboxes.com/jmuir .
  236.  
  237. ___________________________________________________________________________
  238. History
  239.  
  240. 1.81 (13.1.97)
  241.     - Fixed a display bug which occured when the Full-Date mode was
  242.      set.
  243.     - Moved most of the .readme into .doc for uploading purposes; this
  244.      file's size was getting rediculous for a .readme.
  245.     - Default NISClock is now the 020 version, NISClock_000 is the
  246.      68000 version.
  247.  
  248. 2.0 (29.9.97)
  249.     - Localized.
  250.     - Changed a lot of stuff...
  251.     - Re-read the documentation.
  252.     - Automatically resizes the window for the given text. (Previously
  253.      guessed the maximum...)
  254.     - Size went from 4272 to 3960, but processing time probably went
  255.      up due to new calls to Locale.library.
  256.  
  257. 2.1 (1997.Oct.8)
  258.     - Fixed bugs regarding tooltypes (BUTTON=FALSE didn't work..).
  259.     - LEFTEDGE -> EDGE, negative values == distance from right side + 1.
  260.     - EDGE determines in which direction the window is sized.
  261.     - added TOP tooltype, negative values == distance from bottom + 1.
  262.     - JUSTIFICATION -> JUST.
  263.     - Automatically jumps to the active public screen every UPDATE
  264.      seconds. (You may have to wait if UPDATE=60). Force it by clicking
  265.      on the window for the date, and moving to the other screen before
  266.      the time is re-displayed.
  267.  
  268. 2.11 (1997.Oct.14)
  269.     - BUGFIX: gets stuck on the DOPUS screen because DOPUS is aware of
  270.      visitor windows, and will attempt to  close (!!!!!) them when it
  271.      quits or iconifies, instead, it should attempt to close and wait for
  272.      the signal telling it that no windows are on the screen. Fix: added
  273.      the AVOIDSCR tooltype. When DOPUS closes the NISClock window, the
  274.      computer WILL crash at the next UPDATE period.
  275.  
  276. 2.20 (1998.Feb.4)
  277.     - Now uses the E-clock as a timer rather than the time clock, and is
  278.      thus not affected by time changes, backward or forward.
  279.     - Window change when text is smaller as well.
  280.     - If the text-size change is less than four pixels smaller, and there
  281.      are less than 8 pixels on either side of the text, then the window
  282.      remains the same size.
  283.     - Mouse clicks which are released outside the window nolonger cause
  284.      the date to be displayed.
  285.     - Uses the size of the screen's depth gadget rather than a hard-coded
  286.      value.
  287.     - Can now be run from the CLI, but does not create itself a separate
  288.      process.
  289.  
  290. ___________________________________________________________________________
  291. To Do
  292.  
  293.     - Custom time/date formatting command characters.
  294.      eg: - Kludge to fix the week number problem.
  295.          - Small letters for 'am' or 'pm'.
  296.     - Force the NISClock window to close for a short period of time. May be
  297.      useful for allowing public screens (eg: MUI's IBrowse screen) to close
  298.      when the main user program is quit.
  299.     - Attach to windows that are on top of the NISClock window. (eg:
  300.      your Web Browser).
  301.  
  302.     Let me know if you have a favorite or suggestions.
  303.