Documentation for JoyStick 1.2; A multi-purpose joystick interface for the Amiga. This software IS NOT public-domain, or redistributable; see restrictions below. OVERVIEW JoyStick allows a joystick connected to the Amiga's gameport to be used in conjunction with the mouse and keyboard. JoyStick can simulate the normal mouse movement actions of positioning, clicking, dragging, and accessing menus. It can also be configured to send character strings to the computer as though they were entered from the keyboard. COMMAND LINE JoyStick [-w] [-?] [-q] [-m] [-i#] [-t#] [Quit|Mouse] | [Increment|Threshold #] | [Menu [TRUE]] | [Mode5|Mode8 [filename]] Flags: Any flags must be prefaced by '-' and located before the optional command. Flags are only interpreted by the 'local' JoyStick executable; They will not be sent to an already-running copy. Thus, they are most useful when starting JoyStick from a CLI. Flags do not toggle. -w: Suppress banner window. Upon startup JoyStick opens a banner window on the Workbench screen showing the copyright and author messages. After a preset time, the window is either resized to occupy only the screen titlebar, or is closed completely (if the -w flag is specified). An executing JoyStick program w/o a window may be terminated by using the 'Quit' command, or by sending the appropriate ARexx message (See ARexx interface section below). -q: Quiet mode. JoyStick will not output any information to CLI. This will only be overridden by a trailing -? parameter. -m: Menu action setting. JoyStick will only simulate an Right-Mouse-Button (RMB) action if the pointer is located at the top of the screen (See Mouse command below). If this flag is set, the currently active window must have a menu attached or the menu action will be ignored. -i: Increment specification. This flag allows command line control similar to the 'Increment' command (See below). -t: Threshold specification. This flag allows command line control similar to the 'Threshold' command (See below). -?: This displays a list of all flags and commands recognized by JoyStick. COMMANDS Only one command is valid per invocation, and it must be located after any specified flag(s). Quit: Forces an executing JoyStick program to close down. This is exactly the same as closing the default Workbench window. Mouse: JoyStick defaults to 'Mouse' operation. In this mode, actions performed on the attached joystick are sent to the Amiga as though the analogous actions were performed on the system's mouse. Cursor positioning is performed by positioning the joystick's handle in one of its eight positions. Clicking is performed by depressing the joystick's button. All activations of the joystick's button are translated into left-mouse-button actions UNLESS the cursor is at the very top of the active screen. Only then are menu button actions simulated. The presence/absence of menus for the currently selected window may be used to determine if an RMB action is performed. This may be controlled by the -m flag and/or the 'Menu' command. The speed and acceleration of the pointer may be controlled by the Increment and Threshold commands described below. Threshold: The required parameter (t) allows control over the number of moves before the pointer accelerates. After 2^t moves the pointer will start moving twice as far each time. The maximum number of these accelerations may be controlled by the Increment command. Increment: The required parameter specifies the maximum number of accelerations. When this value is reached, the speed of the pointer will remain constant until the user releases the stick. Menu: This command allows setting the restrictions on JoyStick's generation of RMB actions. If a 'TRUE' parameter is specified, RMB actions will occur only when the currently active window has an attached menu. Otherwise, RMB actions are performed whenever the pointer is at the top of the screen. This command duplicates the actions of the -m flag. Mode5: When in this mode, keyboard actions are simulated while leaving the computer's pointer unaffected. When the joystick's button is depressed, the state of the handle is checked, and one of five (5) character sequences is initiated. If the handle is centered, a simple 'Click' is reported, otherwise, one of the actions 'Up', 'Down', 'Left' or 'Right' is selected. JoyStick does not contain the default strings for these settings. When it is switched into 'Mode5', it attempts to read the file 'S:JoyStick.KeyStrings'. This is simply an ASCII string file which may be edited to contain any strings desired. (See 'String files' below). The default file is scanned unless the name of a specific string file is specified, similar to: JoyStick Mode5 Work:TestStrings This will force the reading of the 'Work:TestStrings' instead of the default. This filename may not contain spaces. Mode8: This mode operates similar to Mode5 above, but generates more strings. To do this, activation is sensed when the joystick handle is moved into one of the four primary positions. When this happens the state of the button is checked, and if depressed simulates a SHIFT action. Mode8 will not generate a string if one of the diagonal settings is selected, but will wait until the handle is moved into one of the four primary positions. STRING FILES JoyStick uses files containing ASCII string specifications of the command character sequences. One line is used for each sequence, including all characters up to a carriage-return. Characters not easily entered from the keyboard (, for example) may be specified by entering their ASCII-numeric codes inside '\' characters. These numbers may be specified in decimal, hex, or binary. For example, a sequence to generate a directory listing could be specified as: 1. using a decimal number: dir\13\ 2. using a hexidecimal number with a trailing 'X' or 'x': dir\dx\ 3. or using a binary number with a trailing 'B' or 'b': dir\01101b\ When the '\' character is to be used in the command, specify with two adjacent slashes, ie: '\\'. The file currently may contain up to nine (9) strings. The table below shows how the strings are interpreted, and which modes use each of the stings. Any blank lines are simply ignored. String # Interpretation Mode5 Mode8 --------------------------------------------------------- 1 Click X 2 Up X X 3 Down X X 4 Left X X 5 Right X X 6 Shift Up X 7 Shift Down X 8 Shift Left X 9 Shift Right X ARexx interface. (ARexx IS NOT needed to run JoyStick.) After JoyStick is operational, all further communication with it is done through ARexx messages; Subsequent command line activations send messages to the already-running program instructing it to change modes, quit, etc. Any program with an ARexx port may control a running JoyStick in the same manner. The port named 'JoyStick' currently accepts Rexx string messages of these types: Quit Mouse Increment Number Threshold Number Menu State Mode5 Filename Mode8 Filename Number is required, and must be between 1 and 9 inclusive. State is optional, and interpreted as FALSE unless the first character is 't' or 'T'. Filename is optional, and may not contain spaces. WORKBENCH OPERATION JoyStick may be started or stopped by double-clicking on its icon. If JoyStick is already running, it will be terminated by an activation from Workbench (as well as by using the 'Quit' command from CLI or ARexx). Upon startup from Workbench, the ToolTypes of the icon are checked for the following settings. WINDOW=False Suppresses the screen-title window after startup. Default: TRUE MENU=[TRUE] This restricts RMB actions to windows with menus. Default: FALSE INCREMENT=# The number specified is used as the increment setting. See usage and default discussion above. THRESHOLD=# The number specified is used as the threshold setting. See usage and default discussion above. MODE5=filename JoyStick is started in MODE5 mode, and the specified control file is loaded. MODE8=filename JoyStick is started in MODE8 mode, and the specified control file is loaded. RESTRICTIONS JoyStick IS NOT public-domain. This program has been licenced to Commodore. It may not be distributed by other parties without the expressed consent of Commodore.