Documentation, Version 1.0 Boston AppleFest, 1989 MouseTrap.CDA -- A keyboard mouse driver by David R. Hill Copyright (c) MaineFrame Software, 1989 Although copyrights are retained, this program is in the PUBLIC DOMAIN and must not be sold or commercialized in any way. Introduction: I hate to write desk accessories. It's like going to a party where there are a thousand people with the understanding that if just one single guest doesn't like you, you'll be shot. That's what a desk accessory or init file has to do -- get along with all the other software that's out there. With the permutations and combinations of hardware and software, it's a virtual certainty that full compatibility is an impossibility or, at best, a rarity. I'm sure this is the case with MouseTrap. My performance benchmarks for the program have been the Finder and JumpStart, my launcher and utility program which is designed to replace the Finder. MouseTrap works fine with them. If there are compatibility problems with other programs, please let me know and I'll fix it (if I can) in a future revision. This feedback is important to me, as it's the only way I'll be able to build a better MouseTrap. Program Description: MouseTrap is a combination Classic Desk Accessory and driver for the Apple IIgs which emulates mouse activity with input from the keyboard. It is intended for use by people who either don't have a working mouse or are unable to use one. It is not intended to be an improvement over the mouse; it's simply an alternative method of pointing and clicking. The program was developed and tested under GS/OS, but should also work with ProDOS-8 applications if the machine is booted under GS/OS or ProDOS-16 first (explained later). It will not work with DOS 3.3 mouse-driven applications, which are rare anyway. MouseTrap is not designed to work with text based-applications, only those using graphics. Most text-based application have a perfectly good keyboard interface. That said, however, MouseTrap could be easily fixed to handle text-based programs if people want it to. My main reason for this decision is to leave the CDA Menu and Control Panel easily accessible. Program Installation: Using the Finder or JumpStart, copy MouseTrap.CDA to the */System/Desk.Accs folder of your boot disk. "*" is the wildcard character denoting the name of your boot volume. It is recommended that you create one master volume to use when booting your machine. Please see the JumpStart documentation for more details. Re-boot your machine, and MouseTrap is installed and ready to use. Configuration: Several options exist for tailoring MouseTrap to your needs and preferences. To bring up the MouseTrap Control Panel, go to the list of Classic Desk Accessories by pressing MouseTrap's CDA Key or Open-Apple/Control/Escape. Then select MouseTrap. A screen will appear that includes a short description of the program and several highlighted options. Pressing toggles between this screen and a help screen listing the MouseTrap commands. Basically, two sets of options are available for the MouseTrap control keys: Keyboard and keypad. If you're doing a lot of work with the keypad, you'll want to make the keyboard keys the MouseTrap controls, and vice-versa. The options are as follows: 1. Master ON/OFF. This turns MouseTrap on and off. In the OFF position, nothing happens; when ON, the key described next activates MouseTrap. 2. ON/OFF Toggle key. This key makes MouseTrap active and inactive, alternatively (a toggle). The keyboard choice is the ]} key (next to the key. The keypad choice is the + key. 3. BUTTON key. This is the key that simulates a mouse down and up event, or click. The keyboard choice is the `~ key to the left of the spacebar, while the keypad choice is the * key. 4. CP key. This key takes you directly to the Classic Desk Accessory menu to access the GS and MouseTrap Control Panels. Keyboard option is the [{ key; keypad choice is the = key. 5. DRAG key. This key toggles dragging action for the mouse. The keyboard choice is the \| key to the right of the spacebar. The keypad choice is the / key. 6. Accelerator keys. These can be either the number keys from 0 to 9 on the keyboard or on the number pad. 7. Default movement. When the cursor is moved by the arrow keys, it will move in the amount set by this default setting, unless it is over-ridden by the accelerator keys. The lower numbers are smaller distances (as small as one character on a 640-mode screen) while the higher numbers approach screen height and width. Movement is adjusted for screen mode (640 or 320). When in the MouseTrap Control Panel, the up and down arrows are used to select the option and the left and right arrows are used to make the preferred choice. When the options are set to your liking, press the key to save the settings. This can be done under either GS/OS or ProDOS-8. Pressing takes you back to the CDA menu screen, and a second puts you back in the application you were running. MouseTrap Operation: The ON/OFF key controls whether or not MouseTrap is active. Use it to turn off MouseTrap when it's not needed or when you want to use a MouseTrap control key "as is." If MouseTrap doesn't respond to commands, try pressing the ON/OFF key to activate it. When MouseTrap is active, the four arrow keys move the cursor the distance that has been set by the default movement value. The cursor cannot be moved beyond the screen boundaries or beyond the clamping values set by the application you're running. "Clamping"" refers to the mouse travel limitations. The distance that the cursor moves can be changed by using the Accelerator Keys, <1> through <9>. Pressing an Accelerator Key ONCE changes the distance for the next arrow keypress ONLY. Pressing an Accelerator Key TWICE changes the distance until its changed again. However, the change is not permanent; instead, use the Control Panel to alter the default movement distance. Selecting the <0> key enables global mapping of the keyboard, which means that the position of the keys on the keyboard correspond to screen positions. The next keypress will move the cursor to a position which roughly corresponds to that key's position on the keyboard. _______________ \ \ \ 1234567890 \ \ qwertyuiop \ \ asdfghjkl; \ \ zxcvbnm,./ \ \______________\ For example, pressing MouseTrap <0> followed by <1> will move the cursor to the upper left corner; pressing will move it to the lower right corner. will put it in the lower middle. Clicking is done by pressing the Button Key. Double clicking is achieved by pressing the Button Key in fairly quick succession. However, a short delay is required to obtain the double click effect; pressing the key too quickly may result in only a single click action. If you accidentally press the Button Key in a menu bar item, thus making the pull-down menu appear, press the Drag Key twice to release the menu. To perform a dragging operation: (1) Press the Drag Key to initiate the dragging process. A clicking will be heard to indicate that dragging is in process. (2) Use the previously discussed motion keys to position the cursor and whatever is being dragged. (3) Press the Drag Key again to terminate the dragging and restore the mouse to its normal button-up state. NOTE #1: The #3 Accelerator Key is designed to be the height of items in normal pull-down menus. Use this distance setting to make menu selections. NOTE #2: Under System Disk 4.0, the dragging function has to be done stepwise. This can cause problems under applications such as the Finder, when an object is dragged and released in an unintended location. This problem will disappear with the im- pending release of System Disk 5.0. The outline of the object will appear and can be moved at will. Trust me! ProDOS-8 Applications: Although MouseTrap has not been tested with non-desktop applications, there's no reason why it shouldn't work with ProDOS-8 programs (famous last words!). However, the GS has to be booted with GS/OS or ProDOS-16 in order to load MouseTrap and install the keyboard driver. Once this is done, you need to launch your ProDOS-8 application using a launching program such as my JumpStart or the Finder. When in the ProDOS-8 application, you can still access the Control Panel to make adjustments to MouseTrap and save the settings. MouseTrap Support: Since this a public domain program from which I derive no income, my preferred method of support is by mail or electronic mail. I will grudgingly return telephone calls, but I may hang up on you when your three minutes are up. However, I do encourage feedback about MouseTrap. I will not be using the program in the same way most users will, and input from you is the only way I can learn what improvements are needed or desired. Methods of communication are: David R. Hill MaineFrame Software Box 315A, Cousins Island Yarmouth, ME 04096 CompuServe: 74425,1266 GEnie: D.Hill9 MCI Mail: MaineFrame AppleLink: Dave Hill Ma Bell: (207) 846-6745 My thanks go to Barbara and Larry Bechdol for initially suggesting this program and assisting in its development. Also, appreciation is due to Llew Roberts of Apple's Developer Technical Services for much needed help and advice. Good luck at the light- house, Llew! David R. Hill Cape Elizabeth, Maine May, 1989