home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 3 / goldfish_volume_3.bin / files / fish / disks / d1015.lha / Programs / StarBlank / StarBlank.docs < prev    next >
Encoding:
Text File  |  1993-06-24  |  9.8 KB  |  229 lines
  1. *==========================================================================*
  2. ||                                                                        ||
  3. ||                  StarBlank © 1993 by Brian Neal                        ||
  4. ||                                                                        ||
  5. ||            THIS PROGRAM IS COPYRIGHT 1993 BY BRIAN G. NEAL.            ||
  6. ||                  PLEASE READ THE FOLLOWING LEGAL MUSH                  ||
  7. ||                                                                        ||
  8. || Permission is hereby granted to distribute this program's              ||
  9. || executable and documentation for non-commercial purposes, so long as   ||
  10. || the executable and documentation are not modified in any way.          ||
  11. || This program may not be distributed for a profit without the express   ||
  12. || written consent of the author Brian Neal.                              ||
  13. ||                                                                        ||
  14. || This program is not in the public domain.                              ||
  15. ||                                                                        ||
  16. || Fred Fish is expressly granted permission to distribute this program's ||
  17. || executable and documentation as part of the "Fred Fish freely          ||
  18. || redistributable Amiga software library."                               ||
  19. ||                                                                        ||
  20. ||    MEGA-KUDOS GO TO LEO L. SCHWAB, WHOSE STAR ROUTINE 'STARS.C'        ||
  21. || INFLUENCED THIS PROGRAM.                                               ||
  22. ||                                                                        ||
  23. *==========================================================================*
  24.  
  25. StarBlank - brought to you by Brian Neal of Xarxas Technologies
  26.  
  27. StarBlank 3.1 Documentation - June 22, 1993
  28.  
  29. INTRO
  30. =====
  31.  
  32.    StarBlank is a screen blanker that can display a moving star field to
  33. protect your monitor from 'burn in'.  This release kicks StarBlank into
  34. the post 2.0 era, in the form of a 'commodity'.  This means the user has
  35. more control over StarBlank.  In addition to all the benefits of
  36. commodities, this version adds a user definable insty-blank (tm) hotkey.
  37.  
  38. REQUIREMENTS
  39. ============
  40.  
  41.    You need an Amiga running the 2.0 release of the Amiga operating system.
  42. Hopefully, this guy runs under 3.0 (see below).
  43.  
  44. HOW TO USE
  45. ==========
  46.  
  47.    StarBlank can be run from the Workbench or the shell.  StarBlank supports
  48. the following tool types/options/arguments/whatever: 
  49.  
  50. DONOTWAIT         (Tool type only)  The system won't wait for StarBlank to
  51.                   quit when launched from the WBStartup drawer.
  52.  
  53. PRIORITY=n        The priority to run StarBlank.  The valid range for n is
  54.                   from -128 to 127.  IT IS STRONGLY SUGGESTED THAT YOU KEEP
  55.                   THE PRIORITY BETWEEN -20 AND 20.  Setting it above 50, for
  56.                   example will lock your machine up since you are running at
  57.                   a higher priority than the input.device.  On a multitasking
  58.                   system such as the Amiga it is very desirable to set the
  59.                   priority of your screen blanker fairly low so it won't
  60.                   slow up more important tasks such as downloads, raytracing,
  61.                   or compiling programs.  The default is -10.
  62.  
  63. CX_PRIORITY=n     StarBlank will have priority n with respect to other
  64.                   commodities in your system.  The valid range for n is from
  65.                   -128 to 127.  The default is 0.
  66.  
  67. CX_POPUP=answer   Answer should be either YES or NO.  If answer is not
  68.                   NO, StarBlank will open its control window upon startup.
  69.                   The default is YES.
  70.  
  71. CX_POPKEY=hotkey  The key sequence to use to cause StarBlank to open its
  72.                   control window.  See the HOTKEYS section below.  The
  73.                   default is control alt b.
  74.  
  75. SECONDS=n         Where n is the amount of time (in seconds) of inactivity
  76.                   StarBlank will wait before blanking the screen.  The
  77.                   default is 60 seconds.
  78.  
  79. TOP=n             This esoteric feature tells StarBlank to open its blanking
  80.                   screen n pixels from the top, in case you want to keep a
  81.                   memory gauge or something always visible.  The default is
  82.                   0.  Be careful about goofy values!!
  83.  
  84. STARBLANK=answer  Answer should be either YES or NO.  If answer is not NO,
  85.                   StarBlank will use the moving star field effect when
  86.                   blanking.  Otherwise it will throw up a black screen
  87.                   (less cpu intensive).  The default is YES.
  88.  
  89. BLANK_HOTKEY=key  The key sequence to instantly blank the screen.  See the
  90.                   HOTKEYS section below.  The default is control alt del.
  91.  
  92. PUBSCREEN=screen  When asked to open its control window, StarBlank will try
  93.                   to do so on the public screen named 'screen'.  If the
  94.                   screen is not open, StarBlank will try and open on the
  95.                   Workbench.  The default is Workbench.
  96.  
  97. WARP=n            This feature allows you to tune StarBlank's star field
  98.                   display rate to your specific system and preference.
  99.                   The 'warp factor' n is the number of microseconds to
  100.                   wait between drawing successive star fields.  The default
  101.                   is 0.  To slow things down on my A3000, for example, a
  102.                   good value to use is 1500.  (This feature was provided
  103.                   for A4000 owners, since the new 3.0 version of the
  104.                   graphics function WritePixel() uses the cpu instead
  105.                   of the blitter, and is considerably faster.)
  106.  
  107.  
  108.    Use quotes if you start StarBlank from the shell and your arguments
  109. have embedded spaces, eg.
  110.  
  111. StarBlank pubscreen MegaComm blank_hotkey="ctrl alt f10"
  112.  
  113.    If you start StarBlank from a shell (or user-startup) and will later want
  114. to close that shell, remember to use "run StarBlank >NIL: <NIL: ...".
  115. Typing "StarBlank ?" from the shell will remind you of the options.
  116. When running from the shell, StarBlank will abort with an error code and
  117. print some kind of diagnostic message if it fails.  From the Workbench,
  118. StarBlank will die silently if it fails.
  119.  
  120.    StarBlank can be aborted from a shell with <ctrl><c> or by the BREAK
  121. command.
  122.  
  123. HOTKEYS
  124. =======
  125.  
  126.    StarBlank allows the user to customize the two hot keys.  The method
  127. used is simple to keep program size down and is very flexible, but the
  128. drawback is that the novice user may have some trouble with it.  To
  129. customize a hot key, simply type the key sequence into the appropriate
  130. string gadget, or use the tool type or command line argument.  The tricky
  131. part is the key sequence syntax.  I will paraphrase from pages 736-737
  132. of the _Amiga_ROM_Kernel_Reference_Manual_Libraries_.  For our purposes
  133. use the following syntax:
  134.  
  135.    { [-] QUALIFIER } [KEY]
  136.  
  137. For the regular expression impaired, this means zero or more QUALIFIERs,
  138. each of which may be preceeded by an optional '-', followed by an
  139. optional KEY.
  140.  
  141. QUALIFIER can be one of the following:
  142.  
  143.    lshift      (the left shift key)
  144.    rshift      (the right shift key)
  145.    shift       (any shift key)
  146.    lalt        (the left alt key)
  147.    ralt        (you guessed it - the right alt key)
  148.    alt         (any alt key)
  149.    capslock
  150.    caps        (either shift or capslock)
  151.    control     (ctrl also seems to work)
  152.    lcommand    (the left amiga key; lamiga also seems to work)
  153.    rcommand    (the right amiga key; ramiga also seems to work)
  154.    numericpad
  155.    leftbutton  (the left mouse button; lbutton also seems to work)
  156.    rbutton     (the right mouse button)
  157.    midbutton   (the middle mouse button; of course you have to have
  158.                 one for this to be useful :^) )
  159.  
  160. The optional preceeding '-' sign says "do not care if this qualifier
  161. is present".
  162.  
  163. KEY can be any single letter on the keyboard (eg x) or one of these:
  164.  
  165.    space, backspace, tab, enter, return, esc, del, up, down, right,
  166.    left, help, f1, f2, f3, f4, f5, f6, f7, f8, f9, f10
  167.  
  168. StarBlank simply passes your hot key sequence to the commodities library.
  169. If it doesn't like your hot key, StarBlank will not accept it and reset
  170. the hot key to the last legal sequence.
  171.  
  172. Examples:   ctrl lshift f1
  173.             lshift alt esc
  174.             ralt ctrl up
  175.             alt lshift x
  176.             leftbutton esc
  177.  
  178. CAVEATS
  179. =======
  180.  
  181.    IT IS VERY EASY TO FIND HOT KEYS THAT WONT WORK AS ADVERTISED!!
  182.  
  183.    I was very surprised at what hot keys will and will not work.
  184. The commodities library seems to be inconsistent and a little buggy
  185. in this area.  Why does 'ctrl -shift |' work, but 'ctrl -shift *' does
  186. not?  The numeric keypad is also tricky: 'ctrl lalt -numericpad *'
  187. works but 'ctrl lalt -numericpad enter' won't.  So if StarBlank doesn't
  188. like your key sequence, it may be the commodities library's fault.
  189. You'll have the best luck on simple sequences, so you may have to
  190. experiment a little.
  191.  
  192.    This version was developed on an Amiga 3000 running 2.1.  Please
  193. let me know if it runs on your 2.0+ machine.  It "should" run under 3.0,
  194. but I could not verify this.
  195.  
  196. ETC
  197. ===
  198.  
  199.    The rest of StarBlank is your standard Amiga interface, so I won't
  200. insult your intelligence :^).  Especially handy are the dozen or so
  201. string gadget editing keys like ctrl-x, tab, shift-tab, ctrl-w, ctrl-k,
  202. ctrl-a, ctrl-z,... Remember to hit return (or tab/shift tab) after
  203. entering something in the string gadgets!
  204.  
  205. CREDITS
  206. =======
  207.  
  208.    A big thank-you goes to Leo L. Schwab for his stars.c program on
  209. Fred Fish disk #33.  His piece of code inspired my own star routine.
  210. Thanks Leo!!!
  211.  
  212. The following people gave useful advice and bug reports on earlier
  213. versions of StarBlank:
  214.  
  215.    Eric Penn, John T. Merryman, Jeffrey Booker, Phillip Klien,
  216.    C. Rick Bramham II, & Karl Laun
  217.  
  218. The current thank-you list:  Eric Penn again!
  219.  
  220.    Please send me your comments, suggestions, and bug reports!
  221.  
  222. Brian Neal
  223. 106 Mabel Court #D
  224. Morris, IL 60450
  225. U.S.A.
  226.  
  227. GEnie: B.NEAL2
  228.  
  229.