ToAsciiEx

int ToAscii(
  WORD VirtKey, 
  WORD Scancode, 
  LPSTR lpKeyState, 
  LPSTR lpState, 
  WORD KeyFlags, 
  DWORD lcid
 );

Translates the virtual-key code passed to it, along with the current keyboard state, to an ANSI character. The translation is based on the specified layout.

Value Description
AX > 0 The lpState parameter is the address of a buffer that contians the number of characters specified in AX. These are "standard" characters and will be processed with WM_CHAR messages. The usual values are one and two. Normally, when two characters are returned they are an accent and a dead-key character, when a dead key cannot be translated otherwise.
0 This virtual-key code has no translation (for the current state of shift keys, and so on).
AX < 0 Dead keys. The characters returned are ANSI accent characters representing the dead keys.

VirtKey
Virtual-key code.
Scancode
Hardware-scan code and shift state. The scan code is in the low-order byte, and the shift state is in the high-order byte. The bits in the shift state have the following meaning.
Bit Meaning
15 1 if the key is up; 0 if the key is down.
14 1 if the key was previously up; 0 if the key was previously down.
13 1 if the ALT key is down.
12 1 if Windows displays a menu.
11 1 if Windows displays a dialog box.
10 Not used.
9 Not used.
8 1 if the key is extended; 0 if it is not.

Bits 0 through 6 are the hardware-scan code (used mainly in the translation of ALT+number-pad character code input). Bit 7 is generally 0.

lpKeyState
Address of the virtual key-state array maintained by Windows.
lpState
Address of the state block. It is used mainly for the output of ANSI characters.
KeyFlags
Specifies duplicate shift-state information. The bits have the following meaning.
Bit Meaning
0 1 if a menu is displayed, 0 if not.
1 1 if an extended key, 0 if not.

lcid
Layout identifier.

The export ordinal for this function is 10.

The ToAsciiEx function is called mainly whenever TranslateMessage is called to translate a virtual-key code (for example, for WM_KEYDOWN messages).

The given parameters of ToAsciiEx are not necessarily sufficient to translate the virtual-key code. This is because a previous dead key is stored internally in the driver. Also, the MS-DOS shift-state byte is accessed by ToAsciiEx.

ToAsciiEx is responsible for maintaining the state of the keyboard LED indicator lights. For most AT-compatible computers, this is done by making a ROM BIOS interrupt 16H call; for others, I/O must be done directly through the keyboard.

ToAsciiEx also has a special case which, if it is called with the virtual-key code equal to 0, will only set the keyboard lights according to the state of the appropriate entries in the keyboard-state vector. This function is intended to be called from the SetKeyboardState function and not directly used by applications. The Scancode parameter is ignored. The vector pointed to by lpState should be different from the one used by ToAsciiEx calls in the USER module. The vector should be at least 4 bytes long.

Most translations are made on the basis of the Windows virtual-key code. However, the Scancode parameter's sign bit is used to distinguish key depressions (sign cleared) from key releases (sign set). Also, the scan code is used in the translation of ALT + number-key translations.

The lpKeyState parameter Address of a 256-byte array indexed by the virtual-key code. In each byte, the high-order bit indicates the state of the key and the low-order bit is toggled each time the key is pressed. The CAPSLOCK key is handled in a special manner for some European keyboards.

The lpState parameter Address of a data buffer that contains the translated character(s) and state information. The InquireEx function in the KBINFO structure returns the size required for this state buffer.

See Also

KBINFO