Technical Note TE515

Keyboard Resource Q&As

CONTENTS Downloadables

This Technical Note contains a collection of archived Q&As relating to a specific topic - questions sent the Developer Support Center (DSC) along with answers from the DSC engineers. Current Q&A's can be found on the Macintosh Technical Q&A's web site. [Sep 01 1993]

Code for getting Macintosh system KCHR resource

How do I find the current KCHR resource?

Here's a method for getting a copy of the KCHR currently being used by the system. This method works for both System 6 and System 7.

{  long    keyScript, KCHRID;
  Handle  KCHRHdl;
  /*  First get the current keyboard script. */
  keyScript = GetEnvirons(smKeyScript);
  /*  Now get the KCHR resource ID for that script. */
  KCHRID = GetScript((short)keyScript, smScriptKeys);
  /*  Finally, get your own copy of this KCHR. Now you can pass
    a proper KCHR pointer to KeyTrans. */
  KCHRHdl = GetResource('KCHR',KCHRID);

Back to top

ResEdit and Macintosh Portable 'KCAP' resources

Date Written: 6/17/91

Last reviewed: 6/14/93

I am trying to use the 'KCAP' resource to draw the Macintosh Portable keyboard layout in our application. I used the ResEdit to check 'KCAP' in both System 7 and the Key Layout file, but the Portable keyboard type is not there.

The resource numbers 6 and 7 of 'KCAP' are contained in the ROM of the Portable and some other Macintosh models. Being located in ROM, the resources are not directly viewable with ResEdit. They do, however, exist in the resource chain, so a RGetResource for 'KCAP' number 6 should load and return a pointer to this resource. ROM resources and the resource chain are discussed in the Resource Manager chapters of Inside Macintosh Volumes IV and V. The 'KCAP' resource is documented in Inside Macintosh: Text, C-28 -6 C-34.

Back to top

Using Macintosh KCAP resource to draw a keyboard

Date Written: 1/10/92

Last reviewed: 6/14/93

How can I use the KCAP resource to draw the keyboard?

KCAP resources describe the key layout of Macintosh keyboards. They are intended for use by the Key Caps desk accessory, but applications can also take advantage of KCAPs for information about key arrangements. The program kcapApp demonstrates use of the KCAP resource and is available in the Snippets collection.

This is the format of the KCAP resource:

• rect, boundary for the keyboard (8 bytes)
• rect, appropriate for an editable line of text (8 bytes)
• integer, number of key shapes to follow (2 bytes)

for each key shape:

• integer, number of points defining this key shape - 1 (2 bytes)

for each point:

• point, opposite corner of a rect (2 bytes)

number of keys of this shape - 1 (2 bytes)

for each key:

• byte, modifier mask (1 byte)
• byte, OR/AND setting for modifier mask (1 bit) plus
• virtual keycode for this key (7 bits)
• integer, vertical offset from previous key (2 bytes)
• integer, horizontal offset from previous key (2 bytes)

The keyboard boundary rect may be offset from the origin. It can be realigned with

 OffsetRect(keybdRect, - keybdRect.left, - keybdRect.top)

Each key shape consists of one or more rectangles. The rectangles are defined by a series of points, with one point specifying each rectangle. The first point is the opposite corner of a rectangle anchored at the starting pen location for the key; the next point is the opposite corner of a rectangle from the last point; and so on. The key shape is the union of the rects defined by the points.

Note that a rectangle's point may be above or to the left of the previous point. To QuickDraw, this would define an empty rectangle, so the rectangle's horizontal and/or vertical coordinates may need to be swapped before FrameRect is called to add a rect to the key's region.

The pen is moved to the top left of the keyboard boundary rect before drawing each group of keys of a given shape. The pen location for each key is given as a horizontal and vertical offset from the pen location for the previous key. The pen location for the first key of each shape is an offset from the top left corner of the keyboard boundary rectangle. The pen does not change location when a key is drawn.

Use KeyTrans to determine the character to be drawn on the key. The KCAP resource provides a 7-bit virtual keycode, plus a mask for the modifiers to be passed to KeyTrans. If the most significant bit of the keycode byte is set, AND the desired modifiers with the modifier mask. If the bit is clear, OR the modifiers with the mask.

The high bit of the virtual keycode byte indicates to KeyTrans the type of the keystroke; before calling KeyTrans, clear the bit for a keydown, or set it for a keyup. The bit should be clear if you're drawing a keyboard. KeyTrans sets the state appropriately for dead keys only when called for keydowns.

The global KbdType ($21E), a byte, contains the KCAP resource number for the last keyboard used. Under System 6, KCAP resources are kept in the file "Key Layout" in the System folder. Starting with System 7, KCAP resources are in the System file. Alternatively, a machine's KCAP may be stored in ROM, where it's available with the GetResource call but cannot be viewed with ResEdit.

The most complete information about the KCAP resource format can be found in the new Inside Macintosh "Text" volume, C-28 to C-34. For more information on KeyTrans and KCHRs, see Chapter 10 of Inside Macintosh Volume V, pages 14-23 and 14-96 of Inside Macintosh Volume VI, and the Macintosh Technical Note "Key Mapping." KCAP resources are also discussed on pages 14-95, 14-100 and 14-101 of Inside Macintosh Volume VI.

Back to top

Macintosh Option key: Techniques for ignoring

Date Written: 10/16/91

Last reviewed: 2/28/92

I would like to use the Macintosh Option key as the Control key for keyboards that lack a Control key, such as for Macintosh Plus keyboards. How can I find the ASCII value that would have been returned if the Option key weren't pressed, in a way that would be compatible with other keyboards?

There are a couple of clean ways to ignore the Option key. One is to "reprocess" the keyboard event. The fourth byte of the event message is the ASCII code, but the third byte is the virtual key code. The system calls the trap KeyTrans to map the virtual key code to ASCII according to a 'KCHR' resource. You can do the same, and since the high byte of the modifiers are part of the input to KeyTrans, you can strip out the Option key, call KeyTrans on the third byte of the event message, and get back the "true" ASCII keypress. KeyTrans and 'KCHR' resources are documented in Chapter 10 of Inside Macintosh Volume V, Chapter 14 of Inside Macintosh Volume VI (pages 14-23 and 14-96), and the Macintosh Technical Note "Key Mapping." In Pascal, these steps would look something like:

    keycode := BAND(event.message, keyCodeMask); { get virtual code }
    keycode := BSR(keycode, 8); { move to low byte }
    { now combine with modifiers }
    keycode := BOR(keycode, BAND($FF00, event.modifiers));
    keycode := BAND(keycode, $FFFF - optionKey); { strip option }

The resource ID of the current KCHR is available as GetScript(GetEnvirons(smKeyScript), smScriptKeys). Alternatively, a pointer to the KCHR data is available under System 7 as GetEnvirons(smKCHRCache), as discussed in the Technote "International Canceling."

This method may work for you, but there is a possible problem: dead keys. Since dead keys are processed before your application gets the event, your application will not see (for example) the first Option-e typed. However, the dead keys are specified in the 'KCHR' resource, so you can create a KCHR (ResEdit 2.1.1 includes a template) to omit dead keys (and, if you choose, option characters) and include it with your application. Call SetScript to get the system to use your 'KCHR' (see the Technote "Key Mapping," IM V-313, and IM VI 14-40).

Another problem is that System 7 ignores a 'KCHR' in the application's resources, so an application's 'KCHR' has to be installed in the system. You can install the 'KCHR' with an installer program, or provide a keyboard file users can drag to the System file. (To create a keyboard file, use ResEdit to put the 'KCHR' in the System file, and then drag it out with the System 7 Finder.)

Back to top

Downloadables