---

Specification for 'uchr'

The Unicode keyboard-layout ('uchr') resource contains the data necessary to map virtual key codes to Unicode character codes for a given keyboard layout. Each installed script system has one or more keyboard-layout resources, which may be of type 'uchr' or 'KCHR' (an older, non-Unicode keyboard-layout format). There may be one or more keyboard-layout resources for each language or region, depending upon the preference of the user.

The 'uchr' resource ID is determined as for the 'KCHR' resource, with one exception. That is, typically the resource ID for each Unicode keyboard-layout resource is within the range of resource ID numbers for its script system. The ID number of the default keyboard-layout resource for a script system is specified in the itlbKeys field of the script’s international bundle ('itlb') resource. The exception to this is that if a given 'uchr' resource specifies any Unicode characters that are not within the range of a single Mac OS encoding (or are not in any Mac OS encoding), then you must use a negative number for the resource.

For a given resource ID, the system may contain a 'KCHR' resource, a 'uchr' resource, or both. If both a 'KCHR' resource and a 'uchr' resource are present, they must have the same ID, and the 'uchr' resource should match the behavior of the 'KCHR' resource. The keyboard menu shows each keyboard layout as a single entry, regardless of whether it is specified by a 'KCHR', a 'uchr', or both.

Unicode Keyboard-Layout Resource Format

The 'uchr' format consists of a header information section and five key mapping data sections, as shown in Figure A-1.

The header section of a compiled 'uchr' resource contains a structure of type UCKeyboardLayout and an optional structure of type UCKeyLayoutFeatureInfo. See for an illustration of this section.

The elements in the header section of a 'uchr' resource are

• the resource header format

• the version of the data in this resource

• an offset to a UCKeyLayoutFeatureInfo structure, if any

• a count of the UCKeyboardTypeHeader structures that follow

• an array of structures of type UCKeyboardTypeHeader; each UCKeyboardTypeHeader entry specifies a range of physical keyboard types and contains offsets to each of the key mapping sections to be used for that range of keyboard types

  • first keyboard type in this entry

  • last keyboard type in this entry

  • offset to the UCKeyModifiersToTableNum structure (required)

  • offset to the UCKeyToCharTableIndex structure (required)

  • offset to the UCKeyStateRecordsIndex structure (optional, may be 0 if there is no table)

  • offset to the UCKeyStateTerminators structure (optional, may be 0 if there is no table)

  • offset to the UCKeySequenceDataIndex structure (optional, may be 0 if there is no table)

• the format of the UCKeyLayoutFeatureInfo structure

• a reserved field

• a value of type UniCharCount, specifying the longest possible output string to be produced by this 'uchr' resource

There may be a variable number of each of the following 'uchr' key mapping sections.

The first key mapping section contains a structure of type UCKeyModifiersToTableNum, which maps a modifier key combination to a particular key-code-to-character table number; and alignment bytes. There may be multiple instances of this entire key mapping section. See Figure A-3 for an illustration of this section.

The elements in the first key mapping section of a 'uchr' resource are

• the format of the UCKeyModifiersToTableNum structure

• the table number for modifier combinations that are outside of the range of the tableNum field’s array; that is, the default (fallback) table number

• the range of modifier bit combinations for which there are entries in the tableNum field’s array

• n an array of indexes into the key-code-to-character table offsets contained in the UCKeyToCharTableIndex structure in the next section

• alignment bytes (to a 4-byte boundary)

The second key mapping section contains a structure of type UCKeyToCharTableIndex; the list of key-code-to-character tables, each of which maps a virtual key code to a 16-bit UCKeyOutput value; and alignment bytes. There may be multiple instances of this entire key mapping section. See Figure A-4 for an illustration of this section.

The elements in the second key mapping section of a 'uchr' resource are

• the format of the UCKeyToCharTableIndex structure

• the number of virtual key codes supported by this resource

• a count of the key-code-to-character tables

• an array of offsets from the beginning of the resource to each of the key-code-to-character tables

• an array of key-code-to-character tables containing values of type UCKeyOutput

• alignment bytes (to a 4-byte boundary)

The third key mapping section is a map to dead-key state records. It contains a structure of type UCKeyStateRecordsIndex, which is an index to UCKeyStateRecord structures; a variable number of dead-key state records of type UCKeyStateRecord; and alignment bytes. There may be multiple instances of this entire key mapping section (or 0; this section need not be present if no UCKeyOutput value refers to a dead-key state record). See Figure A-5 for an illustration of this section.

The elements in the third key mapping section of a 'uchr' resource are

• the format of the UCKeyStateRecordsIndex structure

• a count of the dead-key state records to follow

• an array of offsets from the beginning of the resource to each of the UCKeyStateRecord values following

Immediately following the UCKeyStateRecordsIndex structure are a variable number of values of type UCKeyStateRecord. Any keycode-modifier combination which initiates a dead-key state or which is a valid terminator of a dead-key state refers to one of these records. However, these records also permit more complex dead-key state processing, such as a series of transitions from one dead-key state directly into another in which each transition can emit a sequence of one or more Unicode characters. Each record contains

• a value of type UCKeyCharSeq specifying the character(s) produced by the input keycode when no dead-key state is currently in effect

• a value specifying the dead-key state produced by the input keycode when no dead-key state is currently in effect

• a count of the elements in the stateEntryData field’s array

• the format of the data in the stateEntryData field’s array

• an array of dead-key state entry data; each entry maps from the current dead-key state to the character(s) that are produced or to the following dead-key state, if any

• alignment bytes (to a 4-byte boundary)

The fourth key mapping section contains a structure of type UCKeyStateTerminators and alignment bytes. This is an optional list of default terminators (characters or sequences) for each state; if this table is not present or does not extend far enough to have a terminator for the state, nothing is output when the state terminates. There may be multiple (or 0) instances of this entire key mapping section. See Figure A-6 for an illustration of this section.

The elements in the fourth key mapping section of a 'uchr' resource are

• the format of the UCKeyStateTerminators structure

• a count of default dead-key state terminators contained in the keyStateTerminators field’s array

• an array of default dead-key state terminators, described as values of type UCKeyCharSeq

• alignment bytes (to a 4-byte boundary)

The fifth key mapping section of the resource is an optional list of character sequences; it contains a structure of type UCKeySequenceDataIndex and Unicode character sequences. This permits a single keypress to generate a sequence of characters, or to generate a single character outside the range that can be represented directly by a UCKeyOutput or UCKeyCharSeq value. There may be multiple (or 0) instances of this entire key mapping section. See Figure A-7 for an illustration of this section.

The elements in the fifth key mapping section of a 'uchr' resource are

• the format of the UCKeySequenceDataIndex structure

• a count of the Unicode character sequences that follow the UCKeySequenceDataIndex structure

• an array of offsets from the beginning of the UCKeySequenceDataIndex structure to the Unicode character sequences that follow it

• an array of Unicode character sequences

• alignment bytes (to a 4-byte boundary)

---