home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / avis2041.dms / in.adf / Joystick / Read_Me.joy < prev   
Encoding:
Text File  |  1992-12-01  |  8.8 KB  |  227 lines
  1. Documentation for JoyStick 1.2; A multi-purpose joystick
  2. interface for the Amiga.  This software IS NOT public-domain, or
  3. redistributable; see restrictions below.
  4.  
  5.  
  6. OVERVIEW
  7.  
  8. JoyStick allows a joystick connected to the Amiga's gameport to
  9. be used in conjunction with the mouse and keyboard.  JoyStick can
  10. simulate the normal mouse movement actions of positioning,
  11. clicking, dragging, and accessing menus.  It can also be
  12. configured to send character strings to the computer as though
  13. they were entered from the keyboard.
  14.  
  15.  
  16. COMMAND LINE
  17.  
  18. JoyStick [-w] [-?] [-q] [-m] [-i#] [-t#]
  19.      [Quit|Mouse] | [Increment|Threshold #] | [Menu [TRUE]] | 
  20.         [Mode5|Mode8 [filename]]
  21.  
  22. Flags:  Any flags must be prefaced by '-' and located before the
  23. optional command.  Flags are only interpreted by the 'local'
  24. JoyStick executable; They will not be sent to an already-running
  25. copy.  Thus, they are most useful when starting JoyStick from a
  26. CLI.  Flags do not toggle.
  27.  
  28.   -w: Suppress banner window. Upon startup JoyStick opens a
  29. banner window on the Workbench screen showing the copyright and
  30. author messages.  After a preset time, the window is either
  31. resized to occupy only the screen titlebar, or is closed
  32. completely (if the -w flag is specified).  An executing JoyStick
  33. program w/o a window may be terminated by using the 'Quit'
  34. command, or by sending the appropriate ARexx message (See ARexx
  35. interface section below).
  36.  
  37.   -q:  Quiet mode.  JoyStick will not output any information to
  38. CLI.  This will only be overridden by a trailing -? parameter.
  39.  
  40.   -m:  Menu action setting.  JoyStick will only simulate an
  41. Right-Mouse-Button (RMB) action if the pointer is located at the
  42. top of the screen (See Mouse command below).  If this flag is
  43. set, the currently active window must have a menu attached or the
  44. menu action will be ignored.
  45.  
  46.   -i:  Increment specification.  This flag allows command line
  47. control similar to the 'Increment' command (See below).
  48.  
  49.   -t:  Threshold specification.  This flag allows command line
  50. control similar to the 'Threshold' command (See below).
  51.  
  52.   -?:  This displays a list of all flags and commands recognized
  53. by JoyStick.
  54.  
  55.  
  56. COMMANDS
  57.  
  58. Only one command is valid per invocation, and it must be located
  59. after any specified flag(s).
  60.  
  61. Quit:  Forces an executing JoyStick program to close down.  This
  62. is exactly the same as closing the default Workbench window.
  63.  
  64. Mouse:  JoyStick defaults to 'Mouse' operation.  In this mode,
  65. actions performed on the attached joystick are sent to the Amiga
  66. as though the analogous actions were performed on the system's
  67. mouse.  Cursor positioning is performed by positioning the
  68. joystick's handle in one of its eight positions.  Clicking is
  69. performed by depressing the joystick's button.
  70.  
  71. All activations of the joystick's button are translated into
  72. left-mouse-button actions UNLESS the cursor is at the very top of
  73. the active screen.  Only then are menu button actions simulated. 
  74. The presence/absence of menus for the currently selected window
  75. may be used to determine if an RMB action is performed.  This may
  76. be controlled by the -m flag and/or the 'Menu' command.
  77.  
  78. The speed and acceleration of the pointer may be controlled by
  79. the Increment and Threshold commands described below.
  80.  
  81. Threshold:  The required parameter (t) allows control over the
  82. number of moves before the pointer accelerates.  After 2^t moves
  83. the pointer will start moving twice as far each time.  The
  84. maximum number of these accelerations may be controlled by the
  85. Increment command.
  86.  
  87. Increment:  The required parameter specifies the maximum number
  88. of accelerations.  When this value is reached, the speed of the
  89. pointer will remain constant until the user releases the stick.
  90.  
  91. Menu:  This command allows setting the restrictions on JoyStick's
  92. generation of RMB actions.  If a 'TRUE' parameter is specified,
  93. RMB actions will occur only when the currently active window has
  94. an attached menu.  Otherwise, RMB actions are performed whenever
  95. the pointer is at the top of the screen.  This command duplicates
  96. the actions of the -m flag.
  97.  
  98. Mode5:  When in this mode, keyboard actions are simulated while
  99. leaving the computer's pointer unaffected.  When the joystick's
  100. button is depressed, the state of the handle is checked, and one
  101. of five (5) character sequences is initiated.  If the handle is
  102. centered, a simple 'Click' is reported, otherwise, one of the
  103. actions 'Up', 'Down', 'Left' or 'Right' is selected.
  104.  
  105. JoyStick does not contain the default strings for these settings. 
  106. When it is switched into 'Mode5', it attempts to read the file
  107. 'S:JoyStick.KeyStrings'.  This is simply an ASCII string file
  108. which may be edited to contain any strings desired.  (See 'String
  109. files' below). 
  110.  
  111. The default file is scanned unless the name of a specific string
  112. file is specified, similar to:
  113.  
  114.             JoyStick Mode5 Work:TestStrings
  115.  
  116. This will force the reading of the 'Work:TestStrings' instead of
  117. the default.  This filename may not contain spaces.
  118.  
  119. Mode8:  This mode operates similar to Mode5 above, but generates
  120. more strings.  To do this, activation is sensed when the joystick
  121. handle is moved into one of the four primary positions.  When
  122. this happens the state of the button is checked, and if
  123. depressed simulates a SHIFT action.
  124.  
  125. Mode8 will not generate a string if one of the diagonal settings
  126. is selected, but will wait until the handle is moved into one of
  127. the four primary positions.
  128.  
  129.  
  130. STRING FILES
  131.  
  132. JoyStick uses files containing ASCII string specifications of the
  133. command character sequences.  One line is used for each sequence,
  134. including all characters up to a carriage-return.  Characters not
  135. easily entered from the keyboard (<ENTER>, for example) may be
  136. specified by entering their ASCII-numeric codes inside '\'
  137. characters.  These numbers may be specified in decimal, hex, or
  138. binary.  For example, a sequence to generate a directory listing
  139. could be specified as:
  140.  
  141.      1. using a decimal number:
  142.             dir\13\
  143.      2. using a hexidecimal number with a trailing 'X' or 'x':
  144.             dir\dx\
  145.      3. or using a binary number with a trailing 'B' or 'b':
  146.             dir\01101b\
  147.  
  148. When the '\' character is to be used in the command, specify
  149. with two adjacent slashes, ie: '\\'.
  150.  
  151. The file currently may contain up to nine (9) strings.  The table
  152. below shows how the strings are interpreted, and which modes use
  153. each of the stings. Any blank lines are simply ignored.
  154.  
  155.        String #        Interpretation         Mode5        Mode8
  156.                   
  157. ---------------------------------------------------------
  158.           1             Click                   X
  159.           2             Up                      X            X
  160.           3             Down                    X            X
  161.           4             Left                    X            X
  162.           5             Right                   X            X
  163.           6             Shift Up                             X
  164.           7             Shift Down                           X
  165.           8             Shift Left                           X
  166.           9             Shift Right                          X
  167.  
  168.  
  169. ARexx interface. (ARexx IS NOT needed to run JoyStick.)
  170. After JoyStick is operational, all further communication with it
  171. is done through ARexx messages; Subsequent command line
  172. activations send messages to the already-running program
  173. instructing it to change modes, quit, etc.
  174.  
  175. Any program with an ARexx port may control a running JoyStick in
  176. the same manner. The port named 'JoyStick' currently accepts Rexx
  177. string messages of these types:
  178.  
  179.      Quit
  180.      Mouse
  181.      Increment Number
  182.      Threshold Number
  183.      Menu State
  184.      Mode5 Filename
  185.      Mode8 Filename
  186.  
  187. Number is required, and must be between 1 and 9 inclusive.
  188. State is optional, and interpreted as FALSE unless the first
  189. character is 't' or 'T'.
  190. Filename is optional, and may not contain spaces.
  191.  
  192.  
  193. WORKBENCH OPERATION
  194.  
  195. JoyStick may be started or stopped by double-clicking on its
  196. icon.  If JoyStick is already running, it will be terminated by
  197. an activation from Workbench (as well as by using the 'Quit'
  198. command from CLI or ARexx).  Upon startup from Workbench, the
  199. ToolTypes of the icon are checked for the following settings.
  200.  
  201. WINDOW=False  Suppresses the screen-title window after startup.
  202.               Default: TRUE
  203.  
  204. MENU=[TRUE]  This restricts RMB actions to windows with menus.
  205.              Default: FALSE
  206.  
  207. INCREMENT=#  The number specified is used as the increment
  208. setting. See usage and default discussion above.
  209.  
  210. THRESHOLD=#  The number specified is used as the threshold
  211. setting. See usage and default discussion above.
  212.  
  213. MODE5=filename  JoyStick is started in MODE5 mode, and the
  214. specified control file is loaded.
  215.  
  216. MODE8=filename  JoyStick is started in MODE8 mode, and the
  217. specified control file is loaded.
  218.  
  219.  
  220. RESTRICTIONS
  221.  
  222. JoyStick IS NOT public-domain.
  223.  
  224. This program has been licenced to Commodore. It may not be
  225. distributed by other parties without the expressed consent of
  226. Commodore.
  227.