Diversi-Key(tm) By Bill Basham Copyright 1987 DSR, Inc. Version 1.0 INSTRUCTIONS PLEASE COPY THIS DISK AND GIVE IT TO EVERYONE YOU KNOW! It is legal to copy and distribute this disk. However, to legally use the Diversi-Key program on this disk, you must send payment within 2 weeks. Please send $45 directly to: DSR, Inc. 34880 Bunker Hill Farmington, MI 48018-2728 You will receive a user support number, and a new disk with the latest version of Diversi-Key. Your honesty will help us distribute future programs in this same, low-cost way. ******** INTRODUCTION ******** Diversi-Key is a keyboard macro utility for the Apple //gs, which can be used to automate the keyboard input for most programs which run on the //gs. You install Diversi-Key permanently into the //gs expansion memory, where it stays available while you run other programs (such as Appleworks). Your other programs run normally, until you activate Diversi-Key by holding down the "option" key on the //gs keyboard. While holding down the option key, the next keys you press are interpreted as a "Macro" call. When you call a macro, Diversi-Key takes over your keyboard, and rapidly types a pre-defined sequence of keystrokes for you. You'll find that Diversi-Key greatly increases the power and utility of your other programs. When you hold down the option key, your program will pause temporarily, and resume when you let the option key up. You can press the option key to stop the program any time, i.e. to read a screen message which is scrolling by. Whenever the option key is down, you will see an inverse "K" in the upper right corner of the text screen (when in text mode only). Diversi-Key requires an Apple //gs with at least 512K. The Apple //gs comes with 256K, so you must buy a memory card with at least 256K, which plugs into the //gs memory expansion slot. ******** START WITH APPLEWORKS ******** When you boot your Appleworks disk, if it says "ProDOS 1.1.1", then you should update the "PRODOS" file with a //gs version (ProDOS 1.2 or later). Use the //gs system utility program to transfer the file named "PRODOS" from the Diversi-Key disk to your Appleworks disk, replacing the old "PRODOS". This gives the correct time and date stamping of your files, and allows Diversi-Key to function. Note: Don't transfer the file named "PRODOS" on the //gs system disk to any other disk. Use the "PRODOS" on the Diversi-Key disk. Diversi-Key comes with built-in macros for use with Appleworks 2.0. To get started, boot the Diversi-Key disk and choose the menu option to install Diversi-Key. This also installs the Appleworks macros. To verify that Diversi-Key is active, press the option key. An inverse "K" should appear in the upper right corner of the screen. Now boot your Appleworks disk, and choose the options to start a new word processing file from scratch. Name the file "KEYMAC". Appleworks should be in the mode where what you type appears on the screen, as if you were going to type a letter. While holding the option key down (inverse "K" appears), press the minus key, "-", on the KEYPAD, twice. Diversi-Key will now display all the built-in Appleworks macro definitions, typing them into a word processing file. If you aren't in the right Appleworks mode to be able to type input, you may hear a lot of beeps, and the screen will go "crazy" as Diversi-Key continues typing. Don't panic! Hit the panic button. Press: OPEN-APPLE_CONTROL_DELETE (halts Diversi-Key any time) Your "KEYMAC" file should begin like this: [0001=] | Appleworks Macros: May 15, 1987 [0008=][A-Repeat:020]{}[End-A]| Jump to start of line [0009=][A-Repeat:020][End-A]| Jump to right margin [0010=]{f}ONP| Find next page break .... more definitions follow You trigger a macro by holding the option key down, and pressing the key to the right of the first "=" sign. The first macro, option-ctrl-A, is just a comment, and does nothing. To trigger the second macro, hold the option key down and press the left arrow key. The cursor will jump to the start of the line. The words under the macro tell you what the macro does. option- jumps to the right margin, for example. Use Appleworks to print out the "KEYMAC" file, and look through all the macro options. One very useful macro is the date macro, which you trigger by pressing option-semi-colon. Its definition looks like this: [0059=;][99.] [93.], 19[94.]| Date Don't be concerned with the number before the "=", or with the definition itself for now. Just look for the macro key, and read the description of what it does on the line below the definition. Keep your "KEYMAC" printout handy as a reference. You may find the pre-defined macros are enough, in which case you can stop reading right here! Later, if you want to use the full power of Diversi-Key, you can study the rest of these instructions. USING PINPOINT: Many Appleworks add-ons, such as Pinpoint, use the option key as a trigger. To use Diversi-Key with these programs, change the Diversi-Key "trigger" key before booting Appleworks, as follows: 1. Boot the Diversi-Key disk and install Diversi-Key with the Appleworks macros. 2. Holding the option key down, enter the number "42." on the keypad. That is, enter: "4", then "2", then ".", all on the KEYPAD. 3. Now boot Appleworks, and use the option key to trigger Pinpoint as usual. 4. You now trigger Diversi-Key by pressing the OPEN-APPLE key AND the OPTION key together. Note: Be sure you change the trigger key BEFORE booting Appleworks. Then, install Pinpoint before using Diversi-Key. If Pinpoint won't install, try re-booting Appleworks and don't use Diversi-Key until it Pinpoint is installed. ******** DEFINING SIMPLE KEYBOARD MACROS ******** To define a macro, hold the option key down and press the "=" on the numeric KEYPAD. Then, press the key on the KEYBOARD which you want to define. Now, type the macro definition on the KEYBOARD. When you're through with your definition, press the KEYPAD key. For example, to define the option-D key as a macro which types "Hello", enter the following keystrokes: [option-keypad-=]D Hello More details on defining macros are described later. ******** SAVING AND LOADING MACROS ******** After you define a macro, it is held in memory until you turn the machine off. To save it to disk, you must first enter BASIC. You can do this by booting the Diversi-Key disk, and choosing the "Exit to BASIC" option. Or, from the system disk, choose "BASIC.SYSTEM" from the launcher or desktop. When you enter BASIC, you will see the Applesoft prompt, ]. To save your macro file, hold the option key down and enter the following on the KEYPAD: 1.2. You should see the word "BSAVE", and a prompt to enter a filename. Pick a name for your file, and enter it. Then, press return. The file will be saved to disk. To install the new macros later, get to BASIC and enter: BRUN filename (where filename is the name you entered when saving) Note: To get back to the launcher after entering BASIC, enter: BYE ******** APPLE //E UPGRADE ******** If you upgrade your Apple //e with the new //gs motherboard, you won't have the full //gs numeric keypad. To simulate keypad keys on the //e upgrade, hold the open-apple and option(solid-apple) keys down together, and press one of the following: Digits 0..9 =/*+-. (same as keypad ******** INTERRUPTS ******** Diversi-Key activates 60-cycle interrupts on the //gs. This may cause problems with some programs which read or write to a 5.25 drive without disabling the interrupt. In particular, Copy II+ versions before 7.4 will destroy 5.25 disks if you write on them with interrupts active (there is no problem with 3.5 drives). If you plan to use Copy II+ with 5.25 drives, be sure you get version 7.4 or greater. This problem also shows up if you try to boot ProDOS from a 5.25 drive using PR#6. To avoid the problem, boot with open-apple-ctrl-reset, or use special macro [10.] (described later). The Diversi-Key disk contains a file named BOOTFIX which will update the boot tracks on a 5.25 ProDOS disk to correct this problem. Exit to BASIC and enter: BRUN BOOTFIX Then, put in your 5.25 disk and press to fix it. ******** INSTALLATION ******** Diversi-Key may be installed automatically from the menu when you boot the Diversi-Key disk. You only boot this disk once, at power on. The Diversi-Key program is actually a binary file named "DIVKEY". Diversi-Key may be installed under ProDOS or DOS 3.3 with: BRUN DIVKEY Once Diversi-Key is installed, it stays in memory permanently until a power off re-boot. That is, Diversi-Key stays installed even if you reboot with open-apple-ctrl-reset. ERRORS: When you BRUN DIVKEY, you will hear a "beep" if the installation was unsuccessful. The usual reason for this is that you tried to install Diversi-Key again, when it was already installed. You also get this error if you don't have a //gs memory expansion card, or if there is no memory available to install Diversi-Key. If this occurs, try installing Diversi-Key from a power-off boot. Note: To avoid the beep, POKE 0,0. NO RESPONSE? If Diversi-Key ever stops working, particularly after booting a new program, try pressing the "flush" key sequence: open-apple_control_delete (Flush key sequence) The Diversi-Key disk contains a pre-defined set of macros in a file names "DIVMAC", which are installed when you boot the DIversi-Key disk. You can also install them from BASIC with: BRUN DIVMAC The Diversi-Key program comes on a 5.25 ProDOS floppy disk. We recommend you boot this disk when you power on, to install Diversi-Key. You can then boot from the 3.5 drive with "PR#5". You can also use the Apple //gs system utility program to transfer all of the Diversi-Key files to a newly formatted 3.5 inch disk. ******** AUTOMATIC STARTUP ******** You can add Diversi-Key to any ProDOS disk, and have it install automatically when you boot that disk. Use menu option #2 on the Diversi-Key disk to do this (not available on the demo). This option adds the DIVKEY and DIVMAC files to your disk. It then changes the name of the PRODOS file on your disk to OLDPRO, and changes the DIVKEY file to PRODOS. When your disk boots, it should execute these files: PRODOS (installs Diversi-Key) DIVMAC (installs macros) OLDPRO (starts up ProDOS 8 or 16) To remove Diversi-Key from your disk, enter BASIC and type the following: DELETE DIVMAC DELETE PRODOS RENAME OLDPRO,PRODOS To put Diversi-Key back on the disk, use menu option #2. With the demo disk, you can transfer the files, DIVKEY, and DIVMAC, to your disk, and enter: RENAME PRODOS,OLDPRO RENAME DIVKEY,PRODOS ******** COLD REBOOT ******** You can remove Diversi-Key by turning the power switch off for 10 seconds or so, but this will eventually wear out the switch. You can simulate a power-off re-boot as follows: 1. Hold OPEN-APPLE_SHIFT_CONTROL keys down (3 keys). 2. Press and release RESET key. 3. Wait for 2 beeps. 4. Release OPEN-APPLE_SHIFT_CONTROL keys. This will remove Diversi-Key, and clear your Ramdisk (if any). ******** CALLING MACROS ******** Macros in Diversi-Key are numbered from 1 to 9999. There are two different ways to call the same macro. You can call a macro by number by holding down the option key, and entering the macro number on the numeric KEYPAD. This is called a "Numeric Macro". You can also call a macro by holding the option key down, and pressing any keyboard key. This is called a "Keyboard Macro". ******** NUMERIC MACROS ******** To call a numeric macro, hold the option key down and type the macro number on the numeric keypad. The macro is triggered when you press the keypad key, or let up the option key. Press the keypad key if you make an error. Diversi-Key displays a Numeric macro as [nnnn], where nnnn is a number from 1 to 9999. Some Numeric macros are: [0124], [0001], [9047]. ******** KEYBOARD MACROS ******** Triggering a Numeric macro requires more than one keystroke, and numbers are hard to remember. To get around these problems, you may also trigger macros with single-keystrokes on the KEYBOARD. You do this by holding down the option key, and pressing any keyboard key, that is, any key not on the numeric keypad. The macro is triggered immediately when you hit the keyboard key. Be sure to let up the option key, to allow the program to continue after the macro is completed. Diversi-Key displays a keyboard macro as: [k], where "k" is any keyboard key. Here are some keyboard macro examples: [N], [$], [1]. Note that [1] is a keyboard macro triggered by pressing "1" on the keyboard. [0001] is a Numeric macro, triggered by pressing "1" on the numeric keypad. There are 96 possible keyboard macros, which correspond to Numeric macros numbered from 0 to 95. Each keyboard macro corresponds to its ASCII equivalent Numeric macro. For example, the "A" key is an ASCII 65. Therefore [A] is the same as [0065]. Note that lowercase keyboard macros are converted to uppercase. That is, [a] is the same as [A]. For keyboard keys with ASCII values from 96 through 127, subtract ASCII 32 to find the Numeric equivalent (converts to lowercase). Numeric macros [0096] to [0099] have no keyboard macro equivalent. ******** REDEFINING THE KEYBOARD ******** You can re-define the entire keyboard by entering: [xx/] where xx=0..99 That is, hold the option key down, enter a number from 0 to 99 on the numeric keypad, and press the numeric keypad "/" key. When you do this, the keyboard macros will now correspond to Numeric macros [xx00] to [xx95] instead of [0000] to [0095]. For example, when you enter [02/], then [A] triggers macro [0265] instead of macro [0065]. You can use this feature when you switch programs, since your macro definitions will be very specific to each program. For example, you might enter [00/] for running Appleworks, and [01/] for programming in BASIC. Thus, you can keep up to 100 sets of keyboard macro definitions in memory at one time, in each 32K macro file. ******** SPECIAL MACROS ******** Diversi-Key contains 100 pre-defined "special" macros, which are always available, and cannot be modified. You call a special macro by holding the option key down, and entering a number from 1 to 99 on the numeric keypad. Then, hit the keypad "." to trigger the special macro (instead of ). Special macros are displayed as follows: [nn.] where nn=0 to 99 Special macro [00.] calls the "control panel". If you hold the option key down, and hit the keypad "." (without entering a number), the effect is the same as pressing OPEN-APPLE_CONTROL_ESCAPE. Other special macros functions are described throughout these instructions. For a list of all special macros, see the reference section. ******** DEFINING A MACRO ******** You can define a new macro, or edit an existing macro definition at any time. To define a Numeric macro, enter the macro number on the keypad, followed by the keypad "=": [nnnn=] where nnnn=0..9999 To define a keyboard macro, hold the option key down, press the keypad "=", followed by the keyboard key you want to define. [=k] where k is any keyboard key When you enter macro define mode, the current definition for this macro, if any, will appear on the top line of the screen. The macro definition begins with: [nnnn=k] where nnnn is Numeric macro number you are defining, and k is its keyboard macro key equivalent (if any). For example: [0065=A] You define the macro by typing it on the keyboard. When finished, press the keypad key to accept, or the keypad key to cancel. Note that the first time you press it clears any definition you have typed, if any. Press again to exit macro define mode without changing anything. While defining a macro, you can call another keyboard macro by holding the option key down when you press the keyboard key. The status of the open-apple key (up or down), is saved in the macro definition, which is especially useful with Appleworks. During the macro definition, the following keypad keys have special functions: Keypad Key Function * Delete last character entered - Move cursor back 1 + Move cursor forward 1 Cancel definition Accept definition = End of macro definition, comments follow (optional) / Enter special macro functions The keypad "/" key is used to enter Numeric macro calls, special macro calls, and all the other special macro functions described later. To call Numeric macros enter: /nnnn where nnnn is Numeric macro number 1..9999 To enter a special macro call: /xx. where xx is special macro number 00..99 ******** SCREEN DISPLAY DURING MACRO DEFINITIONS ******** As you type your macro definition, each character is displayed on the top line of the screen. If you hold the open apple key down while typing a character, the character appears as {k} where "k" is the character. Open-Apple A is shown as {A}, for example. Other display features are as follows: [k] keyboard macro call [nnnn] Numeric macro call [xx.] special macro call control key / .. {A} open apple key down | end of macro, beginning of comments The arrow keys, tab, escape, delete, and return are printed as follows: Combinations of keys produce the following, for example: {} means open-apple- pressed [] call keyboard macro key Other special functions are displayed between [ ] brackets as described later. ******** PRINTING MACRO DEFINITIONS ******** Diversi-Key has a very flexible way of displaying the definitions in your current macro file. It types the definitions as a macro! You can use this feature to type a list of all your macro definitions into a word processing file. For example, to see all the built-in macro definitions, boot Appleworks and enter the word processor with an empty file. Hold the option key down, and press the keypad "-" key twice: This will type the definitions for macros 1 to 9999 into your word processor, regardless of which word processor you are using. In the following display options, the "-" key is the one on the keypad: -- Displays all macro definitions -nnnn- Displays all definitions starting with Numeric macro nnnn nnnn- Displays Numeric macro nnnn only -k Displays Numeric macro "k" -<@> <@> is ctrl-@ / Displays all current keyboard macros Note: Diversi-Key may pause for up to 12 seconds when displaying macros, as it searches for undefined macro numbers. Comments: You can put comments at the end of your macro definitions by pressing the keypad "=", followed by the comment. When displaying comments, i.e. with keypad --, Diversi-Key sends these comments as actual keystrokes. That is, a in a macro definition is sent as the 5 characters, "", during display. A in a comment, is sent as a real single keystroke carriage return, during display only. This allows you to send formatting commands in comments, to make them easier to read. For example, the built-in comments all start with space, to indent them on the next line. ******** FLUSH: CTRL_OPEN-APPLE_DELETE :THE PANIC BUTTON! ******** If you trigger the wrong macro, or hit keypad -- by mistake, Diversi-Key may go merrily along typing bad keystrokes for some time. Fortunately, you can stop Diversi-Key at any time by typing the FLUSH key sequence. To do this, hold down the control and open-apple keys, and then press the delete key. Try this whenever Diversi-Key seems to be acting "stangely", i.e. not working. ******** MACRO FILES ******** Diversi-Key macro files are saved on disk as binary files. You then BRUN the file to load it into memory for use. The Diversi-Key disk contains a standard file named "DIVMAC" which contains the pre-defined macro definitions for Appleworks (and other programs). To load this file, enter: BRUN DIVMAC When you do this, the macro definitions on disk in the DIVMAC file will replace the current macros in memory. However, you may keep up to 10 different macro files in memory at once, each with up to 9999 macros in 32K memory. Macro files in memory are numbered from 0 to 9. Normally, you will only use file #0. To switch to a new macro file number, hold the option key down, and press the keypad keys "=+n", where n is a KEYPAD digit from 0 to 9. For example, to load a second macro file named "MAC2" and still preserve the exisiting macros, enter =+1 (keypad keys with option key down) BRUN MAC2 To switch back to the original macro file, enter "=+0" (keypad-option key down). Finally, to release the memory allocated for the second macro file, if necessary, enter "=-*1" (keypad-option key down). We anticipate that you may someday buy commercial programs with custom Diversi-Key macro files included. ******** SAVING MACRO FILES ******** You can save your current macros in a file, either under ProDOS or DOS 3.3. To do this, you must first enter BASIC, and get to the Applesoft prompt, which is a: ] One way to do this is to choose "BASIC.SYSTEM" from the //GS program launcher or desktop. When you see this prompt, enter special macro [1.][2.]. That is, hold the option key down, and press the 4 keypad keys "1.2." without letting the option key up. Diversi-Key will type the word "BSAVE" for you, and wait for you to enter a file name. Type the name of the macro file you want to save, and hit . Diversi-Key will finish the BSAVE command for you. You may now reboot. Under ProDOS, you can return to the launcher by typing "BYE". WARNING!!!! Never enter [1.][2.] while executing a program. Doing this will crash the program (and possibly the whole system). Be sure you see the Applesoft prompt "]" before entering [1.][2.]. ******** STARTUP MACRO ******** After your new macros are installed with BRUN macro, Diversi-Key will automatically execute Numeric macro [9999], if you have defined one. Use this macro to initialize Diversi-Key set-up values, if you wish. You can specify a different macro as the startup macro. To do so, save the macro file as follows [nnnn+] (where nnnn is start-up macro number) [1.][3.] ******** FORCING FILE NUMBER ******** When you install a macro file, it normally loads into the current active file number, which you set with [=+n] before BRUN DIVMAC. To create a macro file which loads to a specific file number, enter: [=++n][1.][2.] (when saving the macro file) You can use this feature to set up a turn-key system which loads several macro files, using the startup macro of the first file to load the second file to a different file number. ******** CONVERTING TO SYSTEM FILES ******** You can convert your macro files to system files, in order to load them from a menu manager program, as follows: First CATALOG your disk and note the length of the DIVMAC file. BLOAD DIVMAC,A$1000 CREATE SDIVMAC,TSYS BSAVE SDIVMAC,TSYS,A$1000,Lxxxxx where xxxx is the length from the CATALOG ABOVE You can do this with any macro file, not just "DIVMAC". +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Advanced Features +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ++++++++ TIME AND DATE ++++++++ COUNTER ++++++++ KEYBOARD INPUT DURING A MACRO ++++++++ DISPLAYING MESSAGES (PROMPTING) ++++++++ REPEAT FUNCTION ++++++++ LIST FUNCTION ++++++++ OPTION FUNCTION ++++++++ IF/WHILE/TEST FUNCTIONS ++++++++ CHANGING BYTES IN MEMORY ++++++++ CHANGING KEYBOARDS ++++++++ CALLING MACROS FROM A PROGRAM ++++++++ NOTE: The documentation under the above headings was deleted from the demonstration disk, due to lack of space on the disk. You will receive the complete Diversi-Key documentation when you send your $45 payment. ++++++++ SLOWING DIVERSI-KEY DOWN / PROGRAM COMPATIBILITY PROBLEMS ++++++++ Diversi-Key sends its keystrokes just like you had typed them. That is, they appear at $C000, the normal keyboard location. This is how Diversi-Key can work with any program. Unfortunately, some programs throw away keystrokes if you type too fast. This is never necessary, but many programmers are in the habit of doing it. Diversi-Key automatically corrects this problem in Appleworks 2.0, and Pascal 1.3, by patching these programs in memory when they appear. For other programs, your only hope is to slow down Diversi-Key, (unless you can figure out how to patch them). Macros [61.] through [67.] slow down Diversi-Key ([67.] is slowest), and macro [60.] restores normal speed. Note that when you slow down Diversi-Key, you lose the ability to type ahead during a macro. Diversi-Key automatically slows down when you enter the control panel, so that's why you can't type ahead there. This problem only shows up with machine language programs, so if you know some machine language, you can try to patch the problem away. Typically, the problem is caused by clearing the keyboard strobe at $C010 unecessarily, usually as follows: LDA $C010 (NOT NEEDED, CHANGE TO NOP/NOP/NOP) GETKEY LDA $C000 BPL GETKEY STA $C010 (NEEDED) You can use the //GS monitor to find references to $C010 as follows: BLOAD program CALL -151 \10 C0\<800.9600P ++++++++ USING THE MOUSE ++++++++ Diversi-Key allows you to program your mouse to send macro keystrokes. You activate the mouse with the special macro: [51.] With the mouse activated, you can send a total of 10 different macros from the mouse. When the program starts, the mouse movements will send the following macros: With mouse button up: [

] left mouse motion [] right mouse motion [] down mouse motion [] up mouse motion [] sent when mouse button goes from down to up With mouse button down: [] left mouse motion [] right mouse motion [] down mouse motion [] up mouse motion [] sent when mouse button goes from up to down You can re-assign these mouse macros with the /B (BMOUSE) and /M (MOUSE) special functions. For example: /B/ will assign the mouse button down macros to be [} through []. /M/ does the same for the mouse button up. /B1000 will assign the mouse button down macros to be Numeric macro numbers 1000 to 1004, and similarly for /M1000. To use the mouse, first enter [51.] to enable it. Then, hold down the option key, and move the mouse, or press the mouse button. The mouse is only active when the option key is down. While holding the option key down, you can press the control key to enable the one way mouse function. With the control key down, mouse left-right motion is ignored. With the control key up, mouse up-down motion is ignored. If you prefer, you can use the control key to convert mouse left/right motion into up/down motion. Enter [54.] to enable this feature. You can lower the mouse sensitivity with [55.] for horizontal, or [56.] for vertical. You can enter these macros up to 255 times for minimum sensitivity (use repeat function). Macro [57.] increases the ability of the mouse to type ahead. Each time you call [57.], can typeahead one more macro call. You can increase typeahead 255 times. If you define mouse motion to do cursor movement keystrokes, then the typeahead behaves as follows: With no typeahead, the cursor moves in the same direction the mouse moves. When you stop mouse movement, cursor movement stops. If you move the mouse faster than the cursor can follow, nothing changes. With full typeahead, the mouse can get ahead of the cursor. If you move the mouse rapidly, the cursor will eventually catch up to the mouse. The cursor keeps moving after you stop moving the mouse. With typeahead, the location of the mouse on the table corresponds to the location the cursor will eventually reach on the screen. After you start moving the mouse, you can no longer trigger macros from the keyboard. You'll notice that the inverse "K" in the upper right corner disappears during mouse movements. Let up the option key for an instant to get the "K" to re-appear, and allow macro triggering from the keyboard again. This feature is included to avoid pausing the program during mouse movements. When using the mouse for a long time, you can enter [45.] to change the "trigger" key to , to avoid of having to hold down the