The first field of the key map is a version number:

The version number doesn't change when the user configures the keyboard, and shouldn't be changed programmatically either. You can ignore it.

Modifier keys set states that affect other user actions on the keyboard and mouse. Eight modifier states are defined—Shift, Control, Option, Command, Menu, Caps Lock, Num Lock, and Scroll Lock. These states are discussed under "Modifier Keys" in the Keyboard Information appendix. They fairly closely match the key caps found on a Macintosh keyboard, but only partially match those on a standard PC keyboard—which generally has a set of Alt(ernate) keys, rarely Option keys, and only sometimes Command and Menu keys. Because of these differences, the mapping of keys to modifiers is the area of the key map most open to the user's personal judgement and taste, and consequently to changes in the default configuration.

Since two keys, one on the left and one on the right, can be mapped to the Shift, Control, Option, and Command modifiers, the keyboard can have as many as twelve modifier keys. The key_map structure has one field for each key:

Each field names the key that functions as that modifier. For example, when the user holds down the key whose code is set in the right_option_key field, the B_OPTION_KEY and B_RIGHT_OPTION_KEY bits are turned on in the modifiers mask that the modifiers() function returns. When the user then strikes a character key, the B_OPTION_KEY state influences the character that's generated.

If a modifier field is set to a value that doesn't correspond to an actual key on the keyboard (including 0), that field is not mapped. No key fills that particular modifier role.

One field of the key map sets initial modifier states:

The mask can be 0 or may contain any combination of these three constants:

• B_CAPS_LOCK

• B_SCROLL_LOCK

• B_NUM_LOCK

It's 0 by default; there are no initial locks.

Altering the lock_settings field has no effect unless the altered key map is made the default.

The principal job of the key map is to assign character values to keys. This is done in a series of nine tables:

Each of these tables is an array of 128 offsets into another array, the chars array of Unicode UTF-8 character encodings. get_key_map() provides a pointer to the chars array as its second argument.

Key codes are used as indices into the character tables. The offset stored at any particular index maps a character to that key. For example, the code assigned to the M key is 0x52; at index 0x52 in the option_caps_map is an offset; at that offset in the chars array, you'll find the character that's mapped to the M key when an Option key is held down and Caps Lock is on.

This indirection—an index to an offset to a character—is required because characters are encoded as Unicode UTF-8 strings. Character values of 127 or less (7-bit ASCII) are just a single byte, but UTF-8 takes two, three, or (rarely) four bytes to encode values over 127.

The chars array represents each character as a Pascal string—the first byte in the string tells how many other bytes the string contains. For example, the string for the trademark symbol (™) looks like this:

x03xE2x84xA2

The first byte (x03) indicates that Unicode UTF-8 takes 3 bytes to represent the trademark symbol, and those bytes follow (xE2x84xA2). Pascal strings are not null-terminated.

Here's an example showing you how to decode the character tables. This sample prints out a simple chart of the normal_map, shift_map, option_map, and option_shift_map characters:

#include <interface/InterfaceDefs.h>
#include <stdio.h>
#include <string.h>
#include <stdlib.h>

static void print_key( char *chars, int32 offset )
{
   int size = chars[offset++];

   switch( size ) {
   case 0:
      // Not mapped
      printf( "N/A" );
      break;

   case 1:
      // 1-byte UTF-8/ASCII character
      printf( "%c", chars[offset] );
      break;

   default:
      // 2-, 3-, or 4-byte UTF-8 character
      {
         char str[5];
         int i = (size <= 4) ? size : 4;
         strncpy( str, &(chars[offset]), i );
         str[i] = '0';
         printf( "%s", str );
      }
      break;
   }

   printf( "\t" );
}

int main( void )
{
   // Get the current key map.
   key_map *keys;
   char *chars;
   get_key_map( &keys, &chars );

   // Print a chart of the normal, shift, option, and option+shift
   // keys.
   printf( "Key #tNormaltShifttOptiontOption+Shiftn" );
   for( int idx = 0; idx < 128; idx++ ) {
      printf( " %3dt", idx );
      print_key( chars, keys->normal_map[idx] );
      print_key( chars, keys->shift_map[idx] );
      print_key( chars, keys->option_map[idx] );
      print_key( chars, keys->option_shift_map[idx] );
      printf( "\n" );
   }

   // Free our copy of the key map.
   free( chars );
   free( keys );

   return EXIT_SUCCESS;
}

The character map tables are ordered. Values from the first applicable table are used, even if another table might also seem to apply. For example, if Caps Lock is on and a Control key is down (and both Command keys are up), the control_map array is used, not caps_map. If a Shift key is down and Caps Lock is on, the caps_shift_map is used, not shift_map or caps_map.

Notice that the last eight tables (all except control_map) are paired, with a table that names the Shift key (…_shift_map) preceding an equivalent table without Shift:

• option_caps_shift_map is paired with option_caps_map,

• option_shift_map with option_map,

• caps_shift_map with caps_map, and

• shift_map with normal_map.

These pairings are important for a special rule that applies to keys on the numerical keypad when Num Lock is on:

• If the Shift key is down, the non-Shift table is used.

• However, if the Shift key is not down, the Shift table is used.

In other words, Num Lock inverts the Shift and non-Shift tables for keys on the numerical keypad.

Not every key needs to be mapped to a character. If the chars array has a 0-length string for a key, the key is not mapped to a character (given the particular modifier states the table represents). Generally, modifier keys are not mapped to characters, but all other keys are, at least for some tables. Key-down events are not generated for unmapped keys.

Next are the tables that map combinations of keys to single characters. The first key in the combination is "dead"—it doesn't produce a key-down event until the user strikes another character key. When the user hits the second key, one of two things will happen: If the second key is one that can be used in combination with the dead key, a single key-down event reports the combination character. If the second key doesn't combine with the dead key, two key-down events occur, one reporting the dead-key character and one reporting the second character.

There are five dead-key tables:

The tables are named after diacritical marks that can be placed on more than one character. However, the name is just a mnemonic; it means nothing. The contents of the table determine what the dead key is and how it combines with other characters. It would be possible, for example, to remap the tilde_dead_key table so that it had nothing to do with a tilde.

Each table consists of a series of up to 16 offset pairs—where, as in the case of the character maps, each offset picks a character from the chars character array. The first character in the pair is the one that must be typed immediately after the dead key. The second character is the resulting character, the character that's produced by the combination of the dead key plus the first character in the pair. For example, if the first character is 'o', the second might be '^'—meaning that the combination of a dead key plus the character 'o' produces a circumflexed 'ô'.

The character pairs for the default grave_dead_key array look something like this:

' ', ''',
'A', 'À',
'E', 'È',
'I', 'Ì',
'O', 'Ò',
'U', 'Ù',
'a', 'à',
'e', 'è',
'i', 'ì''o', 'ò',
'u', 'ù',
. . .

By convention, the first offset in each array is to the B_SPACE character and the second is to the dead-key character itself. This pair does double duty: It states that the dead key plus a space yields the dead-key character, and it also names the dead key. The system understands what the dead key is from the second offset in the array.

As mentioned above, for a key to be dead, it must be mapped to the character picked by the second offset in a dead-key array. However, it's not typical for every key that's mapped to the character to be dead. Usually, there's a requirement that the user must hold down certain modifier keys (often the Option key). In other words, a key is dead only if selected character-map tables map it to the requisite character.

Five additional fields of the key_map structure specify what those character-map tables are—which modifiers are required for each of the dead keys:

Each of these fields contains a mask formed from the following constants:

• B_CONTROL_TABLE

• B_CAPS_SHIFT_TABLE

• B_OPTION_CAPS_SHIFT_TABLE

• B_CAPS_TABLE

• B_OPTION_CAPS_TABLE

• B_SHIFT_TABLE

• B_OPTION_SHIFT_TABLE

• B_NORMAL_TABLE

• B_OPTION_TABLE

The mask designates the character-map tables that permit a key to be dead. For example, if the mask for the grave_tables field is,

B_OPTION_TABLE | B_OPTION_CAPS_SHIFT_TABLE

a key would be dead whenever either of those tables mapped the key to the character of the second offset in the grave_dead_key array ('Q' in the example above). A key mapped to the same character by another table would not be dead.

See also: get_key_info(), modifiers(), the Keyboard Information appendix, set_modifier_key()