Be a Keyboard Sleuth!

By Joel West, Contributing Editor, Vista, CA

See the world through a keyboard

In the last installment of Resource Roundup, the general concepts of resources were introduced, and passing mention was made of their role in Apple’s international marketing.

Among the stated justfications for the resource concept was to make it easier to support software in multiple countries. Most software previously had strings embedded in the software, such as

 write('File ', filenam,
 ' cannot be opened.')

which have to be completely rewritten by a programmer (using the proprietary source code) for any foreign market. However, with resources available, a properly designed Macintosh application can be translated by just about anybody using REdit. (I don’t know Steve Jobs personally, so I can’t say if this was a major factor, or merely an after-the-fact rationalization for the design.)

If you’ve ever studied a foreign language, you’ve probably come to the shocking realization that not all of the Indo-European languages content themselves with the letters A-Z and standard punctuation. I can certainly recall struggling in high school Spanish trying to approximate the ¡ key with a typewriter (the ¿ wasn’t even worth trying) or to come up with the ß in German.

If you’ve concluded by this introduction that resources are used on the Macintosh to support foreign keyboards, you’re right. But these resources are also used to support the differences between the Macintosh and the Macintosh Plus keyboards, as well as implementing basic keyboard functions. There are also some important electronic and mechanical differences between the various keyboards.

Smart, but not smart enough

If you ask Apple how to read input from the keyboard, you’ll get the response that you shouldn’t use anything other than the ASCII value. Apple has gone to great lengths to make various keyboards and nationalities behave similarly.

However, the return values from GetNextEvent (and other less documented interfaces) do include the actual key number that is down. You can use this value to support key combinations that are not defined by Apple -- as long as you are aware of keyboard differences.

There are a number of reasons why you might need to go to these lower levels. My interest in keyboards was prompted by the terminal program I’ve been working on in my spare time (at the rate I’m going, it should be ready in 1993).

A number of otherwise good Macintosh programs have tried to reach this low level and failed. My ears first picked up when I heard a number of terminal emulation programs don’t work with non-US keyboards, or with the Mac Plus. The problem hasn’t even escaped Apple; an early version of their Smalltalk-80 is one such program, as we’ll see later.

Output of the Keyboard Sleuth!

But there are ways to look at lower levels that are compatible with all current systems and should be compatible with all future systems. This article tells how you can take complete control over the keyboard without sacrificing portability. It describes the various un- and semi-documented resources associated with keyboards, including the Macintosh Plus and those sold outside the US.

This article concludes with “Keyboard Sleuth”, a program example that analyzes and reports what keyboard you’re using, and which keys you are pressing. The program was written in 'Rascal', a Pascal type language from Reed College. This language is a combination Pascal, Basic and Assembly. It has a very nice shell that makes Mac programming fast and easy because it allows you more flexibility for dealing with the various toolbox data structures than the traditionally strongly typed Pascal. This makes it more suited to "quicky" programs where the Mac interface is secondary to the programming problem. (The distributor for Rascal is given at the end of this article.) The complete Rascal version is available on the source code disk for this issue. It should be fairly easy to translate the program into TML Pascal, and in fact, our Editor took me up on that challenge and did just that! Since many of MacTutor's readers probably have not heard of Rascal, we are publishing his TML version of the program with this article (see Sleuth, Part II in the next article).

Keyboard Properties

The best place to start on keyboard input is the “Toolbox Event Manager” chapter of Inside Macintosh, if you haven’t read it already. There’s also a brief discussion in the “Macintosh Hardware” chapter, but ignore the key numbers shown in Figure 9 of that chapter. My interest is software, not hardware, so I’ll focus on the former in this article.

For many purposes, the keyboard resembles a standard teletype (TTY) input. When you type on the keyboard, a series of ASCII characters are available for you.

If you want to dig deeper (and if you didn’t, you wouldn’t subscribe to MacTutor), there are a number of differences from a glass TTY:

• Extended characters. Character values 0 to 127 are defined by the ASCII standard. For the Lisa and Macintosh, Apple has added a number of characters (128 to 216, thus far) to support foreign languages and typographic symbols. I’ll refer to these as extended ASCII characters. For simplicity’s sake, I’ll use ASCII to refer to any code in the range 0 to 216, and standard ASCII for those in the range 0 to 127.

• Key codes. In addition to the ASCII numeric value, the actual key number is available. For each keyboard and nationality, Apple defines a standard mapping of modifiers and key codes to ASCII characters, but for some purposes (e.g., a terminal emulator) you may wish to use a different mapping.

• Modifier keys. The movement of certain keys is not normally available to your program. Instead, these keys modify the values returned by other, primary keys. These modifier keys are the Option, Command (), Shift and Caps Lock. A key code and a particular modifer pattern will (usually) determine the ASCII value your program sees.

• Function Keys. Apple has reserved certain special key combinations to invoke general-utility memory resident programs. These all take the form of Command-Shift-digit, of which only four are currently assigned. You may wish to disable these keys for some purposes. For example, cmd-shift-3 will capture the screen and save it to disk in a paint document. These are known as 'FKEYS' or function keys. You can create and install your own function key routines in the system file in a manner similar to writing desk accessories.

• “Dead” keys. In most cases, the accented letters used in French, Spanish, German and Italian are produced by first typing the accent, then typing the letter. Your program won’t normally see the first key; instead, the ASCII value of the two-key combination is returned. The first accent key is considered “dead” because it doesn’t return a separate ASCII value or key code.

• Different Keyboards. The Mac 128/512 and the Mac Plus have slightly different keyboard configurations. In addition, Apple has defined a whole family of keyboards for various countries and languages.

The resources and global variables used to implement these properties are listed in Fig. 1.

Figure 1: Keyboard-related resource and global variables

Character Set

The standard ASCII/ISO character set defines 95 printable characters (including space), which are directly supported by the Mac. There are also nine non-printing characters which can be typed, as shown with their corresponding hex codes in Figure 2. Backspace, Tab, and Return have meanings similar to their accepted ASCII usages, while Apple has adopted arbitrary ASCII values for the other six keys.

If you are echoing input characters to the screen, you will have to interpret these control characters yourself. Although TextEdit understands the Return key, in general, these keys won’t produce any meaningful display when using standard output routines, such as DrawString or TEUpdate.

Additionally, there are the 89 extended ASCII characters, as shown in Figure 3. A few support mathematical and word processing symbols, such as the copyright (©) and paragraph (¶) symbols.

However, most of these are used to support foreign languages and typography. A number of languages have extended alphabets. These include accented letters (such as á, à, â, ä, ã, å), combinations (æ, œ) and as well as characters that do not have English equivalents (ß).

In addition, each language has its own typographic customs. In Spanish, exclamatories and interrogatories require a leading punction mark, as in

¿Que? ¡Hola!

The German language prints quotations as

«Deises ist ein Zitat.»

Ironically, the extended set also includes American style quotation marks, as in

“This is a quotation.”

since the quote mark (") is strictly a typewriter convenience that does not extended to publishing.

All of the ASCII values in the range 32 to 216 (except for non-printing standard ASCII value 127, DEL) have corresponding characters in at least one font. (The various font-related resources will be discussed in depth in a future article.)

Keyboard Events

When a key is pressed, it generates a keyboard event. Normally, you will only receive a keyboard event when the key goes down, with the GetNextEvent function returning the EventRecord.what field set to keyDown. Unless you specifically enable keyDown events, such as with

SetEventMask(everyEvent)

GetNextEvent will not return keyUp events.

You will, however, get autoKey events by default. These are generated by the system after the key has been down for a specified delay, and are repeated automatically.

If the event mask you pass to GetNextEvent includes keyDownMask, it should also include autoKeyMask. If not, the consequences are hilarious, as I discovered in writing a desk accessory in which I decided not to bother with the repeating key case. The first letter goes to your program, and any subsequent letter will go to some other program or desk accessory.

The delay and repeat rate can be changed by the user with the “Control Panel” desk accessory, and are stored in global variables KeyThresh and KeyRepThresh, respectively, in units of ticks (1/60 of a second).

The values set by the user are also saved in the non-volatile parameter RAM,which are then used to initialize KeyThresh and KeyRepThresh. These permanent values can be accessed by the following fragment:

{1}

CONST
 aKeyRate = 8;
 aKeyThresh = 12;
VAR
 sysparm: SysParmType;
 num: LongInt;
 ...
BEGIN
 sysparm := GetSysPPtr;
 num := ORD4(sysparm^.kbdPrint);
 rate := BitAnd(BitShift(num,aKeyRate),
 ORD4(15))*2;
 thresh := BitAnd(BitShift(num,
 aKeyThresh), ORD4(15))*4;

(The value sysparm^.kbdPrint is also available as global variable SPKbd; this is the preferred interface for assembly language programmers).

If you want to change the permanent value for some reason, you can modify the value of kbdPrint (or SPKbd) and then call WriteParam to make the change permanent. See the “Operating System Utilities” of Inside Macintosh for more details.

Four of the keys on the keyboard are not considered to generate keycodes normally, but instead act as modifiers. These are the Shift, Caps Lock, Option, and Command key. The state of first three keys are mapped -- along with the key struck -- to generate an ASCII value.

The Command key is always a modifier, and never affects the ASCII value. On the US keyboard, there are six modifier combinations that affect the ASCII mapping:

(none)

Caps Lock

Shift

Option

Caps Lock-Option

Shift-Option

On the US keyboard, the Caps Lock is ignored if Shift is down, but there’s no guarantee that other keyboards will behave the same way. Note, however, your program can always detect if the Caps Lock key was down through the EventRecord.modifiers field. For example, the screen dump function key does this to distinguish Command-Shift-4 (print current window) from Command-Shift-CapsLock-4 (print entire screen).

Figure 6. Mac Classic Keyboard (Fr)

Function Keys

A number of function keys are defined; they are listed in in Technical Note #3, “List of Command-Shift-Number Keys”.

Function Keys #3 and #4 are contained as resources in the System file. Function Keys #1 and #2, which eject the disks, are presumably embedded in ROM.

Some applications (such as a terminal emulator or macro processor) may want to map all key combinations, including the function keys. If you wish to disable the effect of function keys, then the following subroutine will modifiy global variable ScrDmpEnb to do the job:

{2}

FUNCTION FKeyEnable(new: BOOLEAN):
 BOOLEAN;
TYPE
 boolptr = ^BOOLEAN;
CONST
 ScrDmpEnb = $2F8;
VAR
 old: BOOLEAN;
 bp: boolptr;
BEGIN
 bp := BOOLPTR(ScrDmpEnb);
 FKeyEnable := bp^;{ current state }
 bp^ := new;{ change state }
END;

Passing TRUE to FKeyEnable will enable function keys (your program will not see these key combinations), while FALSE will allow your program to receive function key inputs.

If you’re trying to take full control of the keyboard, you’ll also want to turn off the Switcher control codes, Command-[,] and \. These are contained in ESCK #256 and CFIG #0 resources in the Switcher application. The byte at offset 1 (second byte) of the CFIG #0 disables keyboard switching if true. The ESCK with ID 256 contains the keycodes (which will be discussed later) and ASCII values for the characters that control switching, as described by the following Pascal data structure:

{3}

TYPE

ESCKRsrc = RECORD
 unused: Byte;
 swRightKc: Byte;{ right keycode }
 swLeftKc: Byte; { left keycode }
 swBackKc: Byte; { back keycode }
 swRightChr: Byte; { right ASCII char }
 swLeftChr: Byte;{ left ASCII char }
END;

Different Keyboards

The original Mac 128 and 512 have a by now familiar keyboard, which, in the tradition of a certain beverage, I have dubbed the “classic” keyboard. For purposes of illustration, the keycaps for the original Mac are shown in Figure 4. (All keymaps show the unshifted output, except that letters are shown as capital letters.)

The new Mac Plus keyboard is shown in Figure 5. Note the addition of the four arrow keys, and the disappearance of the right-hand option key. More significant is the disappearance of the Enter key from the main keyboard, as we will see in a moment.

The various non-US keyboards are mechanically and electrically the same; all return the same keycode when you strike a particular key. However, the keycaps (hardware) are labelled differently, and the system disk contain different keyboard mapping procedures (software). The most successful foreign Macintosh market is France, so the key assignments for the original French keyboard are shown in Figure 6.

Fig. 7 Key code numbers (all boards)

There are three main differences between the US and non-US “classic” keyboard. The third row has an extra key, while the return is more vertical. Also, the lower left-hand corner has one additional key.

Fortunately, the situation with the Mac Plus is much cleaner. The physical layout of all “new” keyboards is identical; in fact, some Apple documentation refers to this as the “universal keyboard”, which should be reassuring to those developers who came to grief over the previous distinctions.

If we distinguish between printing keys (including space), control keys (Return, Backspace, Tab, Enter), and modifier keys, this is how the various (main) keyboards compare:

Keyboard Print Control Modifier

US classic 47 4 6 (2 Option)

Euro-classic 48 4 6 (2 Option)

Plus 47 8 (arrows) 4 (no Enter)

You can see that the Plus is very similar to the US classic keyboard, but with one less Option key, a missing Enter, and four additional arrow keys.

Note that while particular keyboards are shipped with the corresponding Macs, there is no guarantee, for example, that a Mac 512 will have the original keyboard. Or, some users will pay for the Level 1 and Level 2 upgrades to a Mac 512, resulting in the hardware equivalent of a Mac Plus, but still use their original keyboard.

The only way to tell the two US keyboard types apart is the global variable KbdType. It contains the following values, which were empirically derived and don’t seem to be documented anywhere:

KbdType=3 classic keyboard

KbdType=11 new keyboard

Both the US and non-US original keyboards return a value of 3, so it takes a little sleuthing to tell the difference.

Key Mappings

When the Macintosh boots, two of the INIT resources are reserved for establishing nation-specific keyboard mappings. The INIT resource with ID #0 installs the main keyboard mapping routine in low memory and places a pointer to its entry point in Key1Trans. The INIT 1 resource does the same thing for the keypad mapping, storing its routine pointer in Key2Trans.

These resources -- and thus the software keyboard mappings can be changed by simply replacing the INIT 0 and 1 resources. The Localizer (May 1985 supplement, disk “5/85 MacStuff 1” provides the INIT resources for the following countries:

US (256,257)

UK (768,769)

France (512,513)

Germany (1024,1025)

Italy (1280,1281)

Sweden (2048,2049)

Spanish/Latin American (2304,2305)

French Canadian (3072,3073)

The numbers shown in parentheses are the resource ID’s of the corresponding INIT 0 and 1 resources in Localizer, if you ever need to access them directly.

The Localizer also changes other international parameters, and thus supports the Netherlands and Belgium. But these use the same keyboard assignments (hardware and software) as one of the previous eight countries.

In fact, there are some suprises in the mappings, which do not follow expected political boundaries. The sun has set on the British Empire, and this can be seen in those countries that share the same keyboard mappings:

UK

Ireland, Netherlands

US

Canada, Australia, New Zealand

Sweden

Norway

France

Belgium, french-speaking Switzerland

German

German-speaking Switzerland

In Japan, Apple sells a version of the Macintosh called the DynaMac, which supports a subset of three ideographic character sets in use there. The Japanese user types words phonetically using one of about a hundred characters from one of the two Kana character sets, Katakana or Hiragana. Next, the software takes the combination of phonetic characters and guesses as to which of several thousand pictographic words (Kanji) is appropriate. As with English, the translation of phonetic to written spellings is approximate, using contextual information to distinguish between homonyms.

The Kana and Kanji use the standard two-byte encoding scheme promoted by the Japanese Institute of Standards. However, when not being used for the entering Kana, the ASCII keycodes generated by the DynaMac are identical to those of the U.S. (and Australian and New Zealand) Mac 512!

In addition to setting the standard keyboard mapping, the Localizer also installs a new INTL resource; this includes a code that allows you to tell what the actual host country is. The KeyboardSleuth will use this to confirm its guesses.

Note that installing the non-US key mappings (on a classic keyboard) won’t do you any good unless you have one of the European keyboards. For example, with a French keyboard, I could use Localizer to try the U.K., German, Italian, etc. mappings, but the US keyboard was useless with these key mappings, and vice versa. Also, although the Localizer changes key mappings and the various international formats (date formats, month names, etc.), it does not translate applications or system software. Using Localizer on a French system disk allowed me to convince my test program that it was running on a Swedish system, but the Finder prompts were still in French!

Figure 9: Partial comparison of US keyboards (cf Figure 6)

Generating Keycodes

When you type a key, GetNextEvent returns the ASCII value of the key and its modifiers in the lower byte of EventRecord.message. The number of the primary key is also returned in the next most significant byte, and can be found by the expression

BitShift(BitAnd(msg, keyCodeMask),8)

This key number is known as a keycode. These keycodes are the lowest level of information available to your program.

The keycodes for the three previously mentioned keyboards are shown in Figure 7. Most of the key codes are common to all three keyboards. Where different, the key codes for the Plus and the non-US 512 are shown on the side.

Figure 8 shows the keycodes for both the optional Mac 512 keypad and the Mac Plus’s standard keypad. Note that the keycode for a 1 on the keypad is not the same as the keycode for the 1 on the main keyboard, although the ASCII value returned will be the same.

There are three suprisingly major differences between the two keypads:

• The “,” has become an “=”.

• The numeric operators and their corresponding keycodes have been shuffled around.

• The numeric operator keys return a “Shift” modifier, even when pressed without the Shift key.

This last feature is perhaps the oddest of all, but was done in the name of compatibility, so that although the arrow and numeric operator keys have been separated, no new key codes have been introduced.

If you want to continuously monitor which keys are down, including detecting multiple primary keys down at one time (presumably for a game or an organ keyboard), the global variables KeyMap and KeypadMap are byte arrays containing a bit map (PACKED ARRAY OF BOOLEAN) indicating which keys are currently depressed. The “official” way to read these bit maps is to call GetKeys.

Likely Problem Areas

If there are incompatibilities between your Mac 512-based program and the other keyboards, here are where they are likely to occur:

Physical layout.. If you draw a map of the keyboard, you will have to change it, depending on the keyboard type, as shown in the figures.

Different keycodes. Key #42 on the US machines produces “\”, while key #39 is a “Return”. On the non-US, #42 is “Return” and #39 is a printing character. The space and “Enter” keys are similarly reversed, while the bottom row is shifted over one.

Different keycodes. Key #10 is accessible only on the non-US keyboards. Key #52 (US Enter) is not available anywhere on the Plus.

Let’s look back at Mac Smalltalk, which expects click-Enter to simulate the “blue” (right) button of the original Xerox three-button mouse. This would be click-Space on the non-US Macs, but it is completely inaccessible on a Mac Plus. Fortunately, there’s another way to simulate the blue button in Mac Smalltalk, by clicking on the top edge of a Smalltalk window.

National Idiosyncracies

There are a number of significant differences between the various non-US keyboards. If you refer back to the French keyboard in Figure 6, you can see two notable differences from the standard US layout:

• The top row does not produce numbers unless shifted; and

• The layout is AZERT instead of QWERTY. Note also the M is to the right of the L, instead of on the bottom row.

Oddly, the Italians follow the French form, except that the A and Q are reversed; both of these patterns are the same on the Mac Plus.

Otherwise, the national differences are largely confined to the mappings of the 12 printing keys assigned to neither letters nor numbers. Figure 9 shows the output of the right-hand edge of the classic keyboard (unshifted) for six countries, which should be compared to the complete French keyboard shown in Figure 6. For the Plus, the key mappings differ yet again, although they are largely similar to those shown.

We will use these mappings in building our keyboard sleuth.

Identifying keyboards

This following sample program identifies the keyboard in use. It was written in Rascal, a real-time Pascal-like language developed at Reed College and distributed by MetaResearch (1100 SE Woodward, Portland, OR 92702; price $129) Rascal includes a built-in development environment (editor, compiler, linker, executor), although not one as elaborate as LightSpeedC, which it predates. [The Rascal source is on the source code disk. The TML version is presented in the next article as a courtesy to our readership, most of whom do not yet have Rascal. -Ed.]

I’ve tried to stick to the Pascal-like syntax as much as possible. KeyboardSleuth is short enough to translate into any language that includes a built-in assembler. (I don’t have MDS, and didn’t feel like hand-assembling the code in TML Pascal using $INLINE directives.)

KeyBoardSleuth uses several techniques. First, it prints the country, as determined by the INTL resource. Second, it tells whether the classic Mac or Mac Plus keyboard is in use, by examining the keyboard type.

If it is a classic keyboard, it decides whether this is a US or non-US keyboard. The best way is to check the keycode of the Space key, which differs between the two keyboards. For the various non-US keyboards, it looks at the keycode mappings by directly calling the keyboard translation routine. I used derived results to figure out which of the UK, France, French Canadian, German, Italian, Spanish or Swedish mappings have been chosen. (I don’t own a Mac Plus, so I didn’t have a chance to Localize it to each country to test sleuthing clues for telling its national keyboards apart).

Fourth, KeyboardSleuth allows you to type keys and see what the result is; I used this to find out what the actual national mappings were. All the output is saved to a file, so you can print it out and examine it later.

Acknowledgements

Since the MacTutor’s travel budget is somewhat limited, I was unable to convince the editor that he should send me to each of the previously mentioned countries to examine the keyboards first-hand!

However, several foreign correspondents were kind enough to run earlier versions of the program on their machines. The assistance of Tohru Asami, John Dibble, and Tony Vignaux helped with countries not addressed by any of the documentation. Eric Zocher lent me the Airborne! French (classic) keyboard. Finally, Mark Baumwell of Macintosh Technical Support provided keycode and ASCII assignments for the Mac Pluses of the world.

Joel wins the Program of the Month award for this outstanding article covering a new topic not well understood. Congratulations, and a $50 night out on us! See the next article for the TML source.