Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 2 - Event Manager / Event Manager Reference

Event Manager Routines / Reading the Keyboard

KeyTranslate

You can use the KeyTranslate function to convert a virtual key code to a character code based on a 'KCHR' resource. The KeyTranslate function is also available as the KeyTrans function.

FUNCTION KeyTranslate (transData: Ptr; keycode: Integer; 
                        VAR state: LongInt): LongInt;

transData

A pointer to the 'KCHR' resource that you want the KeyTranslate function to use when converting the key code to a character code.

keycode

A 16-bit value that your application should set so that bits 0-6 contain the virtual key code and bit 7 contains either 1 to indicate an up stroke or 0 to indicate a down stroke of the key. Bits 8-15 have the same interpretation as the high byte of the modifiers field of the event record and should be set according to the needs of your application.

state

A value that your application should set to 0 the first time it calls KeyTranslate or any time your application calls KeyTranslate with a different 'KCHR' resource. Thereafter, your application should pass the same value for the state parameter as KeyTranslate returned in the previous call.

DESCRIPTION

The KeyTranslate function returns a 32-bit value that gives the character code for the virtual key code specified by the keycode parameter. Figure 2-17 shows the structure of the 32-bit number that KeyTranslate returns.

Figure 2-17 Structure of the KeyTranslate function result

The KeyTranslate function returns the values that correspond to one or possibly two characters that are generated by the specified virtual key code. For example, a given virtual key code might correspond to an alphabetic character with a separate accent character. For example, when the user presses Option-E followed by N, you can map this through the KeyTranslate function using the U.S. 'KCHR' resource to produce \xA5n, which KeyTranslate returns as two characters in the bytes labeled Character code 1 and Character code 2. If KeyTranslate returns only one character code, it is always in the byte labeled Character code 2. However, your application should always check both bytes labeled Character code 1 and Character code 2 in Figure 2-17 for possible values that map to the virtual key code.

SEE ALSO

For additional information on the 'KCHR' resource and the KeyTranslate function, see Inside Macintosh: Text.