home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 8 Other / 08-Other.zip / pmp016.zip / README < prev   
Text File  |  1998-01-13  |  10KB  |  237 lines
  1.                                 PMPAUSE 0.16
  2.                       Written by Ewen McNeill, Dec 1997
  3.                         Copyright Ewen McNeill, 1997.
  4.                               <ewen@naos.co.nz>
  5.  
  6. WARNING: This is BETA test software.  Because of the way it operates
  7. it must hook into the OS/2 message queue.  Thus undiscovered bugs in
  8. this software may seriously affect the stability of your system.
  9. Please read the information below carefully.
  10.  
  11.  
  12. INTRODUCTION
  13.  
  14. PMPause is a small (7K executable, plus 3K DLL) OS/2 PM based program
  15. designed to remind you that it is time to take a break from typing and
  16. stretch a little.  It does this by monitoring your keyboard usage, and
  17. mouse usage, and displaying a small (or if you wish, large) graph
  18. which rises when you have been using the keyboard/mouse recently, and
  19. falls when you have not been using the keyboard/mouse recently.
  20. Optionally it can make a small beep when the graph reaches the top limit, 
  21. as an additional hint that you should take a break.
  22.  
  23. This program could form part of your strategy to avoid, or manage, OOS
  24. (RSI), but you SHOULD NOT rely on the program alone.  It is intended
  25. to remind you to take micropause type breaks, but does not force you
  26. to take them.  
  27.  
  28. For additional information on OOS, and techniques for avoiding or
  29. managing the problem see type Typing Injury FAQ which can be found at:
  30.  
  31.          http://www.tifaq.com/
  32.  
  33.  
  34. COPYRIGHT
  35.  
  36. This program is free software; you can redistribute it and/or modify
  37. it under the terms of the GNU General Public License as published by
  38. the Free Software Foundation; either version 2 of the License, or
  39. (at your option) any later version.
  40.  
  41. This program is distributed in the hope that it will be useful,
  42. but WITHOUT ANY WARRANTY; without even the implied warranty of
  43. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  44. GNU General Public License for more details.
  45.  
  46. You should have received a copy of the GNU General Public License
  47. along with this program; if not, write to the Free Software
  48. Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  49.  
  50.  
  51. INSTALLATION
  52.  
  53. There is no installation program at present.  The program can be run
  54. from the command line, or you can create a suitable object that causes
  55. the program to run and place that in your Startup folder.
  56.  
  57. The only requirement is that the program be able to find its companion
  58. DLL (pmpdll.dll); either change to the directory where the program and
  59. DLL are present before running the program (or set the objects working
  60. directory to that directory), or copy the DLL into a directory on your
  61. LIBPATH.
  62.  
  63.  
  64. USAGE
  65.  
  66. The program is configurable from the command line (only; well you can
  67. recompile the enclosed source too if you wish).  The following command
  68. line options are supported:
  69.  
  70. Runtime options (all optional):
  71.   -h      meter grows horizontally   \___ mutually exclusive
  72.   -v      meter grows vertically     /    (default vertical)
  73.   -m <n>  maximum meter value (default 180)
  74.   -n <n>  notify threshold (change to notify colour) (default 90)
  75.   -w <n>  warn threshold (change to warn colour) (default 150)
  76.   -u <n>  go UP this many units if busy during period (default 4)
  77.   -d <n>  go DOWN this many units if idle during period (default 12)
  78.   -c <s>  check every <s> seconds to see if busy/idle (default 4)
  79.  
  80.   -b      beep when reaching top level, as an alert.
  81. Note: 0 < notify threshold < warn threshold < maximum meter value
  82.  
  83.   -?      output this help and exit (catch by piping to less, more, etc)
  84.  
  85. Size/Position is specified with a standard X Windowing System command line
  86. argument, of the form:
  87.   <width>x<height>{+-}<xoffset>{+-}yoffset
  88. Positive offsets relative to bottom, left, negative top, right (OS/2 style)
  89.   -x       positive relative to top, left negative to bottom, right (like X)
  90.  
  91. (The above information comes from the program's internal help obtained
  92. by running: pmpause | more.)
  93.  
  94. There are two separate things which can be configured about the
  95. program.  One is the logical size of the meter, that is its limits and
  96. boundaries, and the other is the physical size that it is displayed
  97. (and where it is displayed).
  98.  
  99. The logical size is set with the "-m" parameter to set the maximum
  100. value; the meter will then logically run from 0 through to that value.
  101. Within that range are two thresholds, the notify threshold ("-n") and
  102. the warn threshold ("-w").  On crossing each threshold the graph
  103. colour will change to a more "urgent" colour as a visual indication
  104. that the meter level is getting higher.
  105.  
  106. The next three values interact to determine how long it will take for
  107. the meter to reach the top limit.  The "-c" value determines how often
  108. the program checks to recent keyboard/mouse activity.  Then the "-u"
  109. value is how far up the meter will go if keyboard/mouse activity was
  110. detected in that time; the "-d" value is how far down it will go if
  111. there was NO keyboard/mouse activity in that time.  The "-c" value
  112. should be kept reasonably small, so that the program can notice when
  113. you take small pauses.
  114.  
  115. If you specify the "-b" flag, when the meter reaches the top limit it
  116. will beep once to alert you to that fact. The beep is a very short
  117. blip to avoid distracting other people in the office (this can be
  118. changed in the source).
  119.  
  120. The physical display of the meter is controlled by the display string,
  121. which is in the format:
  122.  
  123.     <width>x<height>{+-}<xoffset>{+-}yoffset
  124.  
  125. that is that the string:
  126.  
  127.     10x100+0+0
  128.  
  129. would display a window 10 wide, by 100 high, at 0 offset from the left
  130. edge, and 0 offset from the bottom edge.  Negative values are
  131. interpreted as being relative to the opposite edge of the screen.
  132.  
  133. By default this string is NOT interpreted exactly the same way that
  134. programs written for the X Windowing System interpret the string;
  135. instead it is interpreted in OS/2 coordinates (where 0,0 is the lower
  136. left of the screen).  If you wish it to be interpreted as an X program
  137. would, give PMPause the "-x" parameter as well.
  138.  
  139. This table shows the way that positive and negative values are interpreted:
  140.  
  141.     Without -x:  positive relative to bottom, left,
  142.                  negative relative to top, right
  143.     With    -x:  positive relative to top, left,
  144.                  negative relative to bottom, right
  145.  
  146. The PMPause window is displayed without sizing bars because they take
  147. up far too much space for such a small window.  For the same reason,
  148. the window does not have a title bar.  It is recommended that the
  149. window is kept fairly small, and put in one corner of the screen.
  150.  
  151. Finally the "-v" flag says that the meter should grow vertically
  152. (upwards), and the "-h" flag says that the meter should grow
  153. horizontally (left to right).  These flags are mutually exclusive.  It
  154. is permissible to use the vertical mode with a window that is wider
  155. than it is high, but it is not particularly useful to do so.
  156.  
  157. To quit the program either make the window active (move the mouse into
  158. the window, and click on it), and then type "q", or close it from the
  159. OS/2 Window List, or with a command line program.
  160.  
  161.  
  162. HOW IT WORKS
  163.  
  164. PMPause comes with a small DLL (pmpdll.dll) which hooks the OS/2
  165. PM message queue looking for keystroke messages, and mouse messages.
  166. (The supplied binary looks only for button click messages because the
  167. OS/2 Lockup uses mouse movement messages while it is working.)
  168.  
  169. Because it has hooked the system message queue, the DLL is effectively
  170. part of every PM program running on your system, so it can see the
  171. keystrokes and mouse messages sent to all those programs.
  172.  
  173. The DLL then counts the number of keystrokes and mouse messages since
  174. the value was last reset.  The main program queries this value
  175. periodically and uses what it finds out (some activity versus no
  176. activity) to determine how to move the graph.
  177.  
  178. The program does not hook, or count, keystrokes sent to full screen
  179. OS/2 sessions.  A future version may be able to do this, but this is
  180. not a priority, as there would be no way to view the graph while a
  181. full screen session was active. 
  182.  
  183. I do not know if the program is able to count keystrokes to a windows
  184. Win-OS/2 session; I do not use Win-OS/2 myself.  (Reports on this part
  185. appreciated.)
  186.  
  187.  
  188. BETA TEST
  189.  
  190. Because of the way that the program operates (see above), undiscovered
  191. bugs in this program can cause serious system instability.  This
  192. program has been tested on my system (OS/2 Warp 3 Connect, fixpack 26)
  193. for several weeks prior to this BETA release.  I am not aware of any
  194. problems which affect system performance.  However this BETA release
  195. is being made to allow wider testing of the program and uncover any
  196. lurking bugs.
  197.  
  198. Use of this BETA software is completely at your own risk.  I recommend
  199. against using this software on production systems at this time; a non
  200. BETA version will be released later after some time for testing has
  201. passed, and any bugs noticed fixed. 
  202.  
  203. If you do encounter problems while running the PMPause program, the
  204. first thing you should do is quit the program (click on its window
  205. then type "q"), and see if the problem persists.  If the problem goes
  206. away, you may wish to try running PMPause again and see if the problem
  207. reoccurs.  If the problem does not go away, you may have to reboot
  208. your system to clear the problem.
  209.  
  210. I would appreciate reports of any problems, or success, using this
  211. program, particularly from users of OS/2 Warp 4, and people running
  212. other fixpacks from the one I have installed (Warp 3, fixpack 26).
  213. Please send all reports to: ewen@naos.co.nz
  214.  
  215.  
  216. REBUILDING THE PROGRAM
  217.  
  218. This program is supplied with a Makefile (for GNU make), and can be
  219. rebuilt using the gcc compiler supplied with the EMX package by 
  220. Eberhard Mattes.  GNU make and the EMX development environment can be
  221. downloaded from OS/2 FTP sites around the world.
  222.  
  223.  
  224. CONCLUSION
  225.  
  226. The source code has been included with this program.  I would
  227. appreciate copies of any changes that you make.  
  228.  
  229. I would also appreciate feedback as to whether the program has been
  230. useful for you, and suggestions of extra features.  Please keep in
  231. mind, though, that one of the aims of the program is to be very small
  232. so that it has a minimal impact on even memory constrained systems.
  233.  
  234.  
  235. Ewen McNeill <ewen@naos.co.nz>
  236. Jan 1998.
  237.