Classic Computer Magazine Archive START VOL. 2 NO. 3 / WINTER 1987


Getting the most from your keyboard

by John H. Jenkins

Hungry for a big macro? Then let John Jenkins show you how to redesign your ST keyboard with STARTKey, our super macros program. Call up special characters, words or phrases with the push of a button! You'll find the program on your START disk in the file STARTKEY.ARC.

File STARTKEY.ARC on your START disk

The Atari ST is a wonderful computer, but it does have a few minor flaws.

One of them is its keyboard. There's no simple way to use foreign symbols from the ST's keyboard, and though word processing programs usually let you use these special keys, many programs don't. In addition, it would be nice to be able to store words, phrases. or whole paragraphs that could be called up with a single keystroke. Such sequences are called keyboard macros.

In fact, what would really be nice is allowing a whole series of keystrokes (control keys as well as words or phrases) to be called up with a single keystroke - or even selecting items off menus with keystrokes.

That's what STARTKey can do.

STARTKey allows you to redesign your keyboard in a special way. Any keystroke can be assigned a string of keystrokes - up to 63 regular keystrokes on the keyboard. In addition, you can use a keystroke to select an item from the menu bar. Instead of reaching for the mouse and clicking on a menu item you can do it with a keystroke.

If that sounds a little confusing. keep in mind that keystroke can mean two different (but closely related) things. For you, a keystroke is the physical act of pressing one or more keys at once. To a program running on the ST, a keystroke is a number that the ST reports to the program whenever a key is pressed.

The STARTKey program sits between the keyboard and the program, collecting the keystrokes you type and then passing them off to the program. When you type a keystroke that has been assigned a macro, STARTKey intercepts it and replaces it with the macro - up to 63 keystrokes long.

Get the idea? Once STARTKey goes to work, your keyboard can become much more powerful.

But that's not all. You can also assign a menu item to a keystroke. That's right-instead of moving the mouse up to the menu bar and clicking on an item from a menu, you can use a keystroke!

Let's get a sample of how STARTKey works. The program is on your START Disk in the archive file STARTKEY.ARC. Copy this file and the program ARCX.TTP to a fresh disk. Double-click on ARCX.TTP. and in the box that comes on screen, type the filename STARTKEY.ARC and press the Return key. The disk will spin for a minute or so, and when it's finished you'll find the STARTKey programs on the disk.

Next, press the Reset button on the back of your ST to reboot the computer. You have to reboot because STARTKey is a desk accessory program. Once the Desktop returns, you can verify that STARTKey is there by pointing at the Desk menu on the menu bar at the top of the screen-you'll see STARTKey on the menu.

Now run another program-for example, ST Writer Version 2.0, the mouse-based version of ST Writer that you'll also find on this issue's START Disk. (Check the ST Writer article in this issue for how to uncompress and use ST Writer 2.0.) Everything in the program will work as usual - until you hold down a Shift key and type one of the keys on the numeric keypad. All 18 shifted keypad keys have been assigned special descriptive keystroke macros- try them and see!

Now return to the Desktop, pull down the Desk menu and click on STARTKey. You'll see the dialog box in Figure 1. From here you can load a macro file into STARTKey. turn it on or off, and set special paramenters for the macros you load.

To load a new macro file, click on Load (in the lower right corner), then choose a macro file from the file selector. There's a selection of macro files on your START Disk, including files designed for use with ST Writer and 1st Word-even one that gives your ST a Dvorak keyboard.

You'll also find the file MACROS.MAX- that's the sample file you tried out with ST Writer. STARTKey will always look for a file named MACROS.MAX and try to load it when you first boot up, so if you want to automatically boot a macro file, just rename your macro file to MACROS. MAX.

STARTKey goes
to work, your keyboard
is much more powerful.

From the STARTKey dialog box you can turn the macro system on or off, and enable it to pass extended key-codes. Most programs just ignore extended keycodes. but if you find your macros aren't working properly, try turning on extended keycodes by clicking on the keycode button. Sending messages and specifying the delay are special functions that we'll look at later-but if your keyboard seems sluggish with STARTKey, try clicking on Send messages to turn that function off.

(lf it's not convenient to pull down the STARTKey dialog box, you can also turn things on or off from the keyboard at any time. Holding down both Shift keys and pressing function key Fl turns STARTKey on; both Shift keys and F2 turns it off. Both Shift keys and F3 turns STARTKey on with extended keycodes.)

Of course, to get the most out of START-Key you'll probably want to create your own macro files-ones that are specifically designed for the way you use your ST. The first step in doing that is writing a macro text file.

A macro text file consists of a series of macros. You can create it with any text editor or word processor that can create an ordinary ASCII file. It's important to create an ASCII file; otherwise. special characters in a non-ASCII file may make it impossible to compile.

To see how it works, let's create a macro that assigns the sentence "This is a macro." to the keystroke Control-T Start out by using a text editor or word processor that can produce straight ASCII text files, such as 1ST Word, Word Writer or MicroEMACS. Now all you have to do is type in a macro definition for a Control-T "This is a macro." macro.

Here's one way to do it: Specify the keystrokes you want to create, one keystroke at a time. The macro looks like this:

s-t h i s space
i s space
a space
m a c r o .

Here's what it means. The first thing in the macro is the keystroke you're assigning it to. In this case, we want to assign it to Control-T, so we use c-t. Any letters on the left side of the hyphen indicate a Control, Shift or Alternate key is held down; the letter or word on the right side of the hyphen indicates the key that's pressed. Thus, there are several possible combinations using the T key:

c-t means Control-T
a-t means Alternate-T
s-t means Shift-T
ca-t means Control-Alternate-T
cs-t means Control-Shift-T
as-t means Alternate-Shift-T
cas-t means Control-Alternate-Shift-T

and, of course, without a hyphen, there's no Control, Alternate, or Shift key held down.

The next four lines are the keystrokes we want the macro to generate. In this case, we're specifying them character by character: s-t means Shift-T (an upper-case T), space means the space bar, and all the rest of the keys are just lower-case letters.

A few other keys besides the space bar have special names. The Clr/Home key is just home; the four cursor keys have the names up, down, left and right; the keys on the numeric keypad are indicated with an n in front of their names, so n6 is 6 on the keypad. All other keys, including the function keys, are specified by the letters or words printed on them.

The last line, macend, just indicates the end of the macro.

(There's no special reason for putting each word on its own line, by the way-it just makes it easier to read. But don't make a line too long, or it may not compile properly)

That's how to do it one keystroke at a time. Since this is just regular text, there's an easier way to do it:

"This is a macro."

Any text inside double-quote marks passes through as a string of keystrokes. (If you want a double-quote mark to be part of your macro, just use two double-quote marks in a row)

Finally, there's an exceedingly complicated way of doing it: specifying the four-byte internal keystroke code for each keystroke you want to generate. Most programs don't require the four-byte code, but it's available if you need it and you're technically inclined. (There's a file containing all the keystroke codes in the MACROS.ARC file on this issue's START Disk.)

03140054 00230068 00170069
001 F0073 00390020 00170069
001 F0073 00390020 001 E0061
00390020 0032006D 001 E0061
002E0063 00130072 0018006F
0034002E macend

You can include comments in your macros if you like. Wherever a colon appears on a line, except within quotation marks. the entire line from that character on will be treated as a comment and ignored.

:This is a comment line.

You can use any of the three ways to define your macro (the second one is probably easiest). Once you've typed it in, be sure to save the macro text file in ASCII form. Just to keep track of it, let's call it FIZZBANG.TXT.

Figure 1

You can have as many macros as you like in a macro text file. There is no particular limit built into the STARTKey system for the number of macros in a macro file, but there is a limit on the total number of keystrokes. since the final compiled version of the macro file cannot be larger than 22 K. That still gives you space for well over 1,000 one-keystroke macros - more than you're likely to need.

For more examples of macro text files, check out the .TXT files for the macro files that came on your START Disk.

Now comes the tricky part: using the STARTKey macro compiler program. It's called SKCOMPIL.TTP, and you'll find it among the files you uncompressed from STARTKEY.ARC.

Click on SKCOMPIL.TTP and you'll get a dialog box asking you for the name of the macro text file to compile. You'll want to type in the name of the macro text file you just created- F1ZZBANG.TXT- but don't press the Return key! You also need to type in the name you want the compiled macro file to have-say FIZZBANG.MAX. If you just type FIZZBANG.TXT and press the Return key, the compiler will compile the FIZZBANG macros and store them in a macro file called MACROS.MAX. (Remember, that's the default macro file that's always loaded when STARTKey boots up.)

To create a macro file with a different name, you must type -o in front of it. For example, to compile FIZZBANG.TXT into F1ZZBANG.MAX, type:


then press the Return key. SKCOMPIL.TTP will compile the macros in FIZZBANG.TXT and generate the macro file FIZZBANG.MAX. (Be sure to use the MAX extender, so you'll know it's a macro file.) As your macro text file compiles, SKCOMPIL will display each macro line on the screen. If SKCOMPIL encounters a word it doesn't recognize, it stops at the point it gets confused, and you should be able to spot where the problem is.

When SKCOMPIL has successfully compiled F1ZZBANG.TXT into FIZZBANG.MAX, it's ready to use with any ST program-and you're ready to compile more complex macros.

One of the most powerful features of STARTKey is that a macro can select a menu item. For example, if you load the original sample macro file MACROS.MAX and then run ST Writer 2.0, you'll find that holding down the Alternate key and typing a keypad key will automatically select menu items such as loading and saving files and  transforming screen colors. You'll find the complete list of functions the keypad can select in Figure 2.

Using a menu macro is as easy as using a keyboard macro -just press a key. But creating a menu macro is more difficult. For example, the menu macro that uses the Alternate key and 0 key to transform ST Writer 2.0's screen colors looks like this in the original file SAMPLE.TXT:

menu stwriter 6 2C

The first line, of course, specifies that this macro is for the Alternate-0 key and the final line indicates the end of the macro. In the middle line, "menu" indicates that this is a menu macro. "Stwriter" is the name of the program this macro works with - menu macros will only work with one program (keypad macros will work with any program). The two numbers indicate the menu number (6) and item number (2C) of the ST Writer 2.0 Colors menu item.

To help you find out what those numbers are for any application, START Technical Editor Patrick Bass wrote the MenuSpot program on your START Disk. Run MENUSPOT.PRG, then select the resource file for the program you want to write menu macros for. (The resource file usually has a .RSC extender If there's no resource file for your program, you probably won't be able to write a menu macro for it.)

MenuSpot will print a complete list of the menu items, along with the menu and item number for each item. Then all you need to do is copy down the numbers you need, and type them into your macro source file. Remember to copy the numbers exactly as they appear-the numbers are in hexadecimal, which may use the digits 0 through 9 and the letters A through F.

Once you have the item numbers, you can compile your macro text file the same as for keystroke macros. When your .MAX file is finished, you can load it and use it immediately with the program it's designed for.

By the way, a menu macro is a type of "message." Remember the "Send messages" line in the STARTKey dialog box? When the Yes button is highlighted, you can use menu macros. As I mentioned, that may make your ST seem a bit sluggish. If you still want to use messages, try setting a higher value for "Delay (milliseconds)." A value of 1 will probably make it intolerably sluggish; 10 (the default) should work fine, but even higher numbers will make it less sluggish still.

allows you to redesign
your ST keyboard.

You can also include the current date in your keyboard macros. There are seven keywords you can use in keystroke macro text files that have to do with the date:

day: Put the number of the day of the month here.
dayth: Put the number of the day of the month here, and make it an ordinal number (for example, "1st" or "14th").
mon: Put the abbreviated form for the month name here, without a period.
mon.: Put the abbreviated form for the month name here, and follow it with a period if possible.
month: Put the full name for the month here.
month#: Put the number of the month here.
year: Put the last two digits of the number of the year here.

Thus, the macro:

month ""day ",19" year

would assign the current date in the form "December 28, 1987" to the key Control-D.

STARTKey uses the date the macro is compiled-not the date when Control-D is pressed-for these keywords. If your ST has a battery-backed clock installed, though, the ST can automatically recompile the macro file whenever you reboot. The program SKAUTO.PRG on your START Disk provides you with the ability to automatically execute SKCOMPIL.TTP when your ST is turned on-just put SKAUTO.PRG in an AUTO folder.

Next, create an ASCII text file called SKAUTO.DAT and put it in the root directory of the same disk. SKAUTO.DAT requires two lines: The first is a number, the date in the ST's internal clock the last time SKAUTO.PRG was executed. The second line is a command-the name SKCOMP1L.TTP (with the full path name where it can be found) followed by the parameters to pass it (name of file to compile and name of file to create). Make sure that your program to set the ST's time and date is in the AUTO folder ahead of SKAUTO.PRG.

Now, whenever you turn on your ST or press the Reset button, SKAUTO will run. First it checks SKAUTO.DAT to see when it last executed; if it's the same day, it stops. If the day has changed, SKAUTO executes SKCOMPIL.TTP with the correct parameters, so that the date information in the macro file will be complete and accurate.

Again, a sample SKAUTO.DAT file is included for you to examine.

SKCOMPIL contains the names of all the months and day/date information. If you want to use your own month names-for example, in a foreign language-you can put them in a special month file, and name it when it's time to compile. For example. if your month file is called MONTHS.TXT, you could include it when compiling FIZZBANG.TXT by preceding MONTHS.TXT with "-m". In other words, after you double-click on SKCOMPIL.TTP, you type:


which means "Compile the macro text file FIZZBANG.TXT into a compiled macro file named FIZZBANG.MAX, using month information from a file called MONTHS.TXT"

You'll also find a sample MONTHS.TXT file, on your START Disk.
File menue Options menue
( Load 4 Insert
) Save 5 Type Over
/ Save As... 6 Lines
+ Receive 1 Mouse
- Format Disk 2 Deadkey
enter Print 3 Spec. Char.
. Delete 0 Colors
* Quit    
Edit menue    
7 Edit    
8 Create    
9 Global Format    

If you're really technically inclined, you can also create a macro to send an arbitrary message to a program. In this case, the body of the macro consists of the name of the program to which the message is sent, and then four long-words in hexadecimal, which form the body of the message. (Tom Hudson's article in the Summer 1987 issue of START is indispensible here.) The four long words are exactly the eight words of the message, with two exceptions:

Word 1 (the bottom half of the first long word) is the GEM ID number for the program sending the message; obviously this must be supplied by STARTKey at run time.

Word 3 (the bottom half of the second long word) is, for messages telling a program to do something with a window the handle of the window in question. Again, you don't know this until run-time, so if word 3 is "FFFF' (or -1), then when the message is sent, STARTKey substitutes the handle of the front window.

Because STARTKey uses 0 as a flag to signal the end of a macro, none of the long-words in the message can be 0. Fortunately the only time you'd really want a long-word to be 0 is if it's ignored and not part of the message, but only there to pad it out to sixteen bytes. Thus in the example, we set the last long-word to 1-since it'll be ignored anyway it doesn't matter what it is.

Thus, in the message macro in the 1st Word sample file on your START Disk, we send a message of type $1A, which is a WM_VSLID message telling a program to move the vertical scroll bar in a window; the sample macro tells the program named "1st_ Word" to move the vertical scroll bar to position 1000 (that is, to the bottom). Thus, pressing Control-B when STARTKey is active and 1ST Word is running moves you down to the bottom of the document you're working on.

Obviously, message macros aren't lightweight material- they're even more complex than menu macros, and require substantial technical background. But if you've got the technical expertise to use them, they can be invaluable.

STARTKey is a powerful keyboard macro system-but it's not the ultimate macro system possible. It can't "record" macros, for example. and it can't include mouse movement and clicking in macros. lf you'd like to expand STARTKey's capabilities-or just see how it was created-you'll find the source code in the file STARTKEY.SRC on your START Disk. In particular, I hope that people will write their own macro compilers, since that is a relatively easy job and SKCOMP1L is so much geared to the way 1 like it done. This way, you can more easily customize STARTKey to suit your own personal needs and desires.

I use STARTKey with virtually every program I run-I used it with ST Writer in writing this article-and I would feel lost without it. I cannot guarantee that it is 100 percent compatible with all programs, though, and I've encountered some problems myself. I have yet to find a program where it didn't work at all. The best news is that there are no problems in using it with either ST Writer or Thunder!

YOU can
build your own library
of useful macro files.

It works indifferently well with Zoomracks II and Power Writer, largely because they both use many keyboard commands already, and because they seem to filter out ASCII characters with the high bit set and don't allow them to be used. STARTKey still works with these programs, but you have to choose your keyboard equivalents carefully.

One of my favorite features of STARTKey is that it allows "standardization" of programs such as editors. The programming languages I work with tend to be happiest with their own editors, but each one uses different commands. I've set up macro files for each of the editors I run across so that now Control-F invokes the Find command in them all, for example.

You can build your own library of useful macro files for the programs you use-and even share them through your favorite user group or computer bulletin board. With STARTKey you really can harness the power of your ST's keyboard!