| int ToAscii(VirtKey, Scancode, lpKeyState, lpState, KeyFlags) | |||
| WORD VirtKey; | |||
| WORD Scancode; | |||
| LPSTR lpKeyState; | |||
| LPSTR lpState; | |||
| WORD KeyFlags; |
The ToAscii function translates the virtual-key code passed to it, along with the current keyboard state, to an ANSI character.
VirtKey
Specifies a virtual-key code.
Scancode
Specifies a hardware-scan code in the low-order byte, and a shift state 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
Points to virtual key-state array maintained by Windows.
lpState
Points to state block. This 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 display, 0 if not. |
| 1 | 1 if an extended key, 0 if not. |
The return value is the number of characters returned in the state block. The number of characters, 1 byte per WORD is returned in the AX register. The lpState parameter points to the state block.
The return value is one of the following values.
| Value | Description |
| 2 | Two characters are returned (mainly an accent and a dead-key character, when a dead key cannot be translated otherwise). |
| 1 | One ANSI character is returned. |
| 0 | This virtual-key code has no translation (for the current state of shift keys, and so on). |
| -1 | This key is a dead key. The character returned is normally an ANSI accent character representing the dead key. |
The export ordinal for this function is 4.
The ToAscii function is called mainly whenever TranslateMessage is called to translate a virtual-key code (for example, for WM_KEYDOWN messages).
The given parameters of ToAscii 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 ToAscii.
ToAscii 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.
ToAscii 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 ToAscii 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 points to 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 points to a data buffer that contains the translated character(s) and state information. The Inquire function in the KBINFO structure returns the size required for this state buffer.