home *** CD-ROM | disk | FTP | other *** search
/ The CDPD Public Domain Collection for CDTV 3 / CDPDIII.bin / pd / commodities / mouseblanker / mouseblanker.doc < prev    next >
Text File  |  1992-10-07  |  10KB  |  249 lines
  1.  
  2.                              MouseBlanker
  3.  
  4.                              (Commodity)
  5.  
  6.                                   by
  7.  
  8.                             Stefan Sticht
  9.  
  10.          This program (binary), sourcecode, documentation is
  11.  
  12.                             PUBLIC DOMAIN.
  13.  
  14.                      You may do anything with it!
  15.  
  16.  
  17. Purpose of this commodity:
  18. --------------------------
  19. MouseBlanker  is  a  commodity, which blanks the mouse pointer after a
  20. specified  timeout  period  since you moved the mouse the last time or
  21. after  pressing  a  specified  amount  of  keys  on the keyboard.  The
  22. pointer  is  restored  next  time you move the mouse.  This is done to
  23. prevent  the mouse pointer hiding any information while you are typing
  24. text for example.
  25.  
  26. Requirements:
  27. -------------
  28. This  commodity  requires  at least Kickstart 37.* and Workbench 37.*.
  29. Please  check  this out using Version in the Shell or "About" from the
  30. Workbench's   "Workbench"   menu.    You   also   need   to  have  the
  31. commodities.library  in your libs: directory.
  32.  
  33. How to start a commodity:
  34. -------------------------
  35. First  there  are  two  basically different ways to start a commodity:
  36. via Workbench or via Shell.
  37.  
  38.     Starting  it  via Workbench is extrem simple:  just doubleclick on
  39. its  icon  and  the  commodity gets started.  Perhaps you might change
  40. some  parameters of the commodity.  You do this with tool types.  Tool
  41. types can be changed by clicking at the commodities icon and selecting
  42. Information from the Workbench's Icon menu.  In the window which opens
  43. you  see a listview gadget in which all tool types are listed.  Please
  44. refer  to  your  Workbench  documentation  on  how to change this tool
  45. types.  Which parameters you can change for this specific commodity is
  46. described below.
  47.     Please  note  that  another  double  click on the commodity's icon
  48. forces  the  commodity  to  open  its window, if it's already running.
  49. Running  two  copies of MouseBlanker at the same time isn't useful and
  50. therefore possible.  Any changes in tool types aren't told the running
  51. copy  of  the Mouseblanker; you have to kill the running one and start
  52. it again.
  53.     To  start  a commodity via shell you type in its name.  If you get
  54. an  "Unknown  command  ???"  error  message,  you  have misspelled the
  55. commodity's  name  or the commodity isn't in your current directory or
  56. in the current search path.  The easiest way is to change your current
  57. directory  to the location of the commodity using the CD command.  You
  58. can  change  parameters  of  a commodity by command line options.  The
  59. available options are listed with ?  as the first parameter:
  60.  
  61.                             Mouseblanker ?
  62.  
  63. gives you a list of the command line options.  The explanation of each
  64. option is below.  Starting the commodity once more while it is already
  65. running  forces  the  commodity  to  open its window.  No command line
  66. option is parsed or updated if you start the commodity a second time.
  67.  
  68.     If  you  want  the  commodity to be started at every boot-up, it's
  69. best to add this line to your User-Startup file:
  70.  
  71.                      <path>Mouseblanker <options>
  72.  
  73. Don't  forget  to  replace  <path>  by  the  path to the commodities's
  74. location  and <options> by the options you want to change. For example
  75. add this line if your commodity is located in the Tools drawer of your
  76. boot disk and if you want the pointer to be blanked after 5 seconds:
  77.  
  78.                      Tools/MouseBlanker SECONDS=5
  79.  
  80.     Another way to start the commodity at every boot-up is to drag its
  81. icon  in  the  WBStartup drawer of your boot disk.  Then the commodity
  82. gets  started  as if you had double clicked on its icon.  But you have
  83. to  add the tool type DONOTWAIT to the icon.
  84.  
  85. Using Exchange:
  86. ---------------
  87. Exchange is the commodities controller program. With Exchange you can
  88. control all commodities: you can kill, disable, enable, show and hide
  89. commodities.
  90.     Start  the  Exchange  program,  which  usually is in the Utilities
  91. drawer  of your boot disk, by double clicking its icon.  Now you see a
  92. list  of  the available commodities.  Select the commodity you want to
  93. control.   The  commodities title, description and status is shown now
  94. below the listview gadget.
  95.     You  can  kill  the  commodity  using  the  Kill gadget...  If the
  96. commodity  has  a  window  to  open,  in which you usually change some
  97. parameters,  you  can  open  this window using Show.  Hide closes this
  98. window.
  99.  
  100.                         Changeable parameters:
  101.                         ----------------------
  102.  
  103. CX_Priority:
  104. ------------
  105. You  can  specify the priority of the Commodity within the commodities
  106. queue  using the tool type or commandline option CX_PRIORITY=<number>,
  107. where  <number>  is  the  decimal  value  for  the  priority.  Default
  108. priority is 0.
  109.  
  110. Seconds:
  111. --------
  112. With  the tool type or command line option SECONDS you can specify the
  113. initial  value  of  the  timeout period, after which the mouse pointer
  114. will  be  blanked.  Use SECONDS=<number>, where <number> is a positive
  115. decimal  value.  Setting SECONDS=0 disables this feature.  The default
  116. timeout is 3 seconds.
  117.     After  having  started  the  commodity, you can change the timeout
  118. value in a small pop up window, too.  To open this window you need the
  119. Exchange  program  or  a  hotkey  installed.   Open Exchange's window,
  120. select  the  MouseBlanker,  then  select  Show.  Now the window of the
  121. MouseBlanker  has  opened.   There  you  can change the timeout value.
  122. Using  the  Hide  gadget  the  window  closes  and the commodity keeps
  123. running.  The Quit gadget removes the commodity.
  124.  
  125. KEYPRESSES:
  126. -----------
  127. With  the tool type or command line option KEYPRESSES=<number> you can
  128. specify  after  how many keypresses the mousepointer shall be blanked.
  129. Please  note  that  only releases of keys are counting.  Default is 5.
  130. KEYPRESSES=0  disables  this  feature.  This option can be modified in
  131. the MouseBlanker's window, too.
  132.  
  133. REBLANKTIMEOUT:
  134. ---------------
  135. After  MouseBlanker  has  blanked  the  mouse  it  may happen that the
  136. pointer  reappears.   Unfortunatly  MouseBlanker can't recognize this.
  137. As  a  work-around  MouseBlanker  always  reblanks the pointer after a
  138. specified timeout as long it thinks the pointer should be blanked.  As
  139. this  requires  CPU  time, you may disable this option.  With the tool
  140. type  or  command  line option REBLANKTIMEOUT=<number> you can specify
  141. this  timeout  in  seconds.   REBLANKTIMEOUT=0  disables  this option.
  142. Default is reblanking after 2 seconds.
  143.  
  144. CX_POPKEY:
  145. ----------
  146. You  can  specify  a  hotkey,  with which you can open the commodity's
  147. window, using the tool type or command line option CX_POPKEY=<string>.
  148. <string>  is  any input description string as explained below.  If you
  149. omit  this  option, no hotkey will be installed.  Default is no hotkey
  150. installed.
  151.  
  152. Examples:
  153.  
  154.     CX_POPKEY=f1                (F1 opens the window)
  155.     "CX_POPKEY=lshift f1"       (left shift and F1)
  156.     "CX_POPKEY=alt m"           (either alt and M)
  157.  
  158. CX_POPUP:
  159. ---------
  160. With  the  tool  type  or  command line option CX_POPUP=YES|NO you can
  161. specify  wether  the commodity's window shall open at startup.  YES|NO
  162. means that you have to use either YES or NO, nothing else.  Default is
  163. NO.
  164.  
  165.                       Input description strings
  166.                       -------------------------
  167.  
  168. With  input  description  strings  you  can  specify  almost any input
  169. action,  for  example  the action lshift f1, which means that pressing
  170. the  left  shift  and  the  f1  key  together  is the action.  In this
  171. commodity  you  can specify the action to open the commodity's window,
  172. as described above.
  173.  
  174. Input description strings have the following template:
  175.  
  176.       [class] (([-]qual)|syn)* [[-]upstroke] [highmap|ANSIcode]
  177.  
  178. (* means zero or more occurances of the of the expression in brackets)
  179.  
  180. class   is one of the following strings:
  181.         rawkey, rawmouse, event, pointerpos, timer, newprefs,
  182.         diskremoved, diskinserted.
  183.         If not specified, the class is taken to be "rawkey".
  184.  
  185. qual    is one of the strings:
  186.         lshift, rshift, capslock, control, lalt, ralt, lcommand,
  187.         rcommand, numericpad, repeat, midbutton, rbutton, leftbutton,
  188.         relativemouse
  189.         A preceding '-' means that the value of the corresponding
  190.         qualifier is to be considered irrelevant.
  191.  
  192. syn     (synonym) is one of the strings: shift, caps, alt
  193.         shift means "left or right shift"
  194.         caps means "shift or capslock"
  195.         alt means "either alt key"
  196.  
  197. upstroke (literally "upstroke")
  198.         if this token is absent, only downstrokes are considered
  199.         for rawmouse (mousebuttons) and rawkey events.  If it is
  200.         present alone, only upstrokes count.  If it preceded by
  201.         '-' it means that both up and down strokes are included.
  202.  
  203. highmap one of the strings:
  204.         comma, space, backspace, tab, enter, return, esc, del, up,
  205.         down, right, left, help, f1, f2, f3, f4, f5, f6, f7, f8, f9,
  206.         f10, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, (, ), /, *, -, +
  207.  
  208. ansicode a single character token is interpreted as a character code,
  209.         which is looked up in the system default keymap.
  210.  
  211. Some full examples:
  212. -------------------
  213.  
  214.     MouseBlanker Seconds=10
  215.     MouseBlanker Seconds=5 "cx_popkey=ctrl 1" cx_popup=yes
  216.     MouseBlanker Seconds=15 "cx_popkey=help" keypresses=10
  217.  
  218.  
  219. Version history:
  220. ----------------
  221. V1.20   small error removed
  222. V1.19   minor changes to reduce code size
  223. V1.18   now window opens on the frontmost screen (via hotkey), if the
  224.         frontmost screen is a public screen; else it opens on the de-
  225.         fault public screen as usual;
  226.         removed enforcer hit under low mem condition
  227. V1.17   internal changes
  228. V1.16   internal changes
  229. V1.15   Method of mouse blanking changed; blanking after certain
  230.         number of keypresses added; many small changes
  231. V1.14   SAS/Cs cback.o changed for 68040-compatiblity; relinked
  232.         with this changed cback.o
  233.  
  234.  
  235. Send bug-reports, enhancement-requests, questions, gifts(!) to:
  236. ---------------------------------------------------------------
  237. Stefan Sticht
  238. Bibereckerweg 40a
  239. D-8390 Passau 18
  240. FRG
  241.  
  242. or (better) EMail to:
  243. sticht@edith.deg.sub.org
  244. Fido-Net: Stefan Sticht (2:246/200.4)
  245.  
  246. Please include the version number of the commodity in every bug report
  247. You  get  the  version  number  using  the  Version  command:
  248.                      Version [<path>]<commodity>
  249.